mirror of
https://github.com/tomav/docker-mailserver.git
synced 2024-06-29 12:41:27 +02:00
docs: Layout adjustments
This commit is primarily wrapping content with some `example` admonitions. The `Certificate` tab does shuffle the content a little bit with minor revisions, but otherwise non-layout revisions in this commit are minimal. PROXY protocol tabs split off to a separate `example` admonition. Some longer example admonitions may instead be open by default, but are collapsible (`???+`) for improved UX.
This commit is contained in:
polarathene
parent
302adc3415
commit
24d8d07c52
|
|
@ -18,14 +18,18 @@ This article describes how to deploy DMS to Kubernetes. We highly recommend ever
|
||||||
|
|
||||||
## Manually Writing Manifests
|
## Manually Writing Manifests
|
||||||
|
|
||||||
If using our Helm chart is not viable, here is some guidance to start with your own manifests.
|
If using our Helm chart is not viable for you, here is some guidance to start with your own manifests.
|
||||||
|
|
||||||
<!-- This empty quote block is purely for a visual border -->
|
<!-- This empty quote block is purely for a visual border -->
|
||||||
!!! quote ""
|
!!! quote ""
|
||||||
|
|
||||||
=== "`ConfigMap`"
|
=== "`ConfigMap`"
|
||||||
|
|
||||||
Provide the basic configuration via environment variables with a `ConfigMap`. Note that this is just an example configuration; tune the `ConfigMap` to your needs.
|
Provide the basic configuration via environment variables with a `ConfigMap`.
|
||||||
|
|
||||||
|
!!! example
|
||||||
|
|
||||||
|
Below is only an example configuration, adjust the `ConfigMap` to your own needs.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
@ -62,9 +66,11 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
||||||
SSL_KEY_PATH: /secrets/ssl/rsa/tls.key
|
SSL_KEY_PATH: /secrets/ssl/rsa/tls.key
|
||||||
```
|
```
|
||||||
|
|
||||||
**Providing config files**
|
You can also make use of user-provided configuration files (_e.g. `user-patches.sh`, `postfix-accounts.cf`, etc_), to customize DMS to your needs.
|
||||||
|
|
||||||
You can also make use of user-provided configuration files (_e.g. `user-patches.sh`, `postfix-accounts.cf` and more_), to customize DMS to your needs. Here is a minimal example that supplies a `postfix-accounts.cf` file inline with two users:
|
??? example "Providing config files"
|
||||||
|
|
||||||
|
Here is a minimal example that supplies a `postfix-accounts.cf` file inline with two users:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
@ -92,7 +98,11 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
||||||
|
|
||||||
=== "`PersistentVolumeClaim`"
|
=== "`PersistentVolumeClaim`"
|
||||||
|
|
||||||
To persist data externally from the DMS container, configure a `PersistentVolumeClaim` (PVC). Make sure you have a storage system (like Longhorn, Rook, etc.) and that you choose the correct `storageClassName` (according to your storage system).
|
To persist data externally from the DMS container, configure a `PersistentVolumeClaim` (PVC).
|
||||||
|
|
||||||
|
Make sure you have a storage system (like Longhorn, Rook, etc.) and that you choose the correct `storageClassName` (according to your storage system).
|
||||||
|
|
||||||
|
!!! example
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
@ -117,6 +127,8 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
||||||
|
|
||||||
The configuration for a `Service` affects if the original IP from a connecting client is preserved (_this is important_). [More about this further down below](#exposing-your-mail-server-to-the-outside-world).
|
The configuration for a `Service` affects if the original IP from a connecting client is preserved (_this is important_). [More about this further down below](#exposing-your-mail-server-to-the-outside-world).
|
||||||
|
|
||||||
|
!!! example
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
apiVersion: v1
|
apiVersion: v1
|
||||||
|
|
@ -158,9 +170,7 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
||||||
|
|
||||||
=== "`Certificate`"
|
=== "`Certificate`"
|
||||||
|
|
||||||
In this example, we use [`cert-manager`][cert-manager] to supply RSA certificates.
|
!!! example "Using [`cert-manager`][cert-manager] to supply TLS certificates"
|
||||||
|
|
||||||
You could also supply RSA certificates as fallback certificates, which DMS supports out of the box with `SSL_ALT_CERT_PATH` and `SSL_ALT_KEY_PATH`, and provide ECDSA as the proper certificates.
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
@ -183,11 +193,17 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
||||||
kind: Issuer
|
kind: Issuer
|
||||||
```
|
```
|
||||||
|
|
||||||
!!! warning "Sensitive Data"
|
The [TLS docs page][docs-tls] provides guidance when it comes to certificates and transport layer security.
|
||||||
|
|
||||||
For storing OpenDKIM keys, TLS certificates, or any sort of sensitive data - you should be using `Secret`s. A `Secret` is similar to `ConfigMap`, it can be used and mounted as a volume as demonstrated in the `Deployment` tab.
|
!!! tip "ECDSA + RSA (fallback)"
|
||||||
|
|
||||||
The [TLS docs page][docs-tls] provides guidance when it comes to certificates and transport layer security. Always provide sensitive information via `Secrets`.
|
You could supply RSA certificates as fallback certificates instead, with ECDSA as the primary. DMS supports dual certificates via the ENV `SSL_ALT_CERT_PATH` and `SSL_ALT_KEY_PATH`.
|
||||||
|
|
||||||
|
!!! warning "Always provide sensitive information via a `Secret`"
|
||||||
|
|
||||||
|
For storing OpenDKIM keys, TLS certificates, or any sort of sensitive data - you should be using `Secret`s.
|
||||||
|
|
||||||
|
A `Secret` is similar to `ConfigMap`, it can be used and mounted as a volume as demonstrated in the `Deployment` tab.
|
||||||
|
|
||||||
=== "`Deployment`"
|
=== "`Deployment`"
|
||||||
|
|
||||||
|
|
@ -196,6 +212,8 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
||||||
- It instructs Kubernetes how to run the DMS container and how to apply your `ConfigMap`s, persisted storage, etc.
|
- It instructs Kubernetes how to run the DMS container and how to apply your `ConfigMap`s, persisted storage, etc.
|
||||||
- Additional options can be set to enforce runtime security.
|
- Additional options can be set to enforce runtime security.
|
||||||
|
|
||||||
|
???+ example
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
apiVersion: apps/v1
|
apiVersion: apps/v1
|
||||||
|
|
@ -234,8 +252,8 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
||||||
imagePullPolicy: IfNotPresent
|
imagePullPolicy: IfNotPresent
|
||||||
|
|
||||||
securityContext:
|
securityContext:
|
||||||
# `allowPrivilegeEscalation: true` is required to support SGID via the
|
# `allowPrivilegeEscalation: true` is required to support SGID via the `postdrop`
|
||||||
# `postdrop` executable in `/var/mail-state` for Postfix (maildrop + public dirs):
|
# executable in `/var/mail-state` for Postfix (maildrop + public dirs):
|
||||||
# https://github.com/docker-mailserver/docker-mailserver/pull/3625
|
# https://github.com/docker-mailserver/docker-mailserver/pull/3625
|
||||||
allowPrivilegeEscalation: true
|
allowPrivilegeEscalation: true
|
||||||
readOnlyRootFilesystem: false
|
readOnlyRootFilesystem: false
|
||||||
|
|
@ -449,12 +467,10 @@ Kubernetes provides multiple ways to address this; each has its upsides and down
|
||||||
- [ ] It is not possible to access DMS via other cluster nodes, only via the node that DMS was deployed on
|
- [ ] It is not possible to access DMS via other cluster nodes, only via the node that DMS was deployed on
|
||||||
- [ ] Every port within the container is exposed on the host side
|
- [ ] Every port within the container is exposed on the host side
|
||||||
|
|
||||||
**General**
|
!!! example
|
||||||
|
|
||||||
Using `hostPort` and `hostNetwork: true` is a similar approach to [`network_mode: host` with Docker Compose][docker-docs::compose::network_mode].
|
Using `hostPort` and `hostNetwork: true` is a similar approach to [`network_mode: host` with Docker Compose][docker-docs::compose::network_mode].
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
apiVersion: apps/v1
|
apiVersion: apps/v1
|
||||||
|
|
@ -513,9 +529,7 @@ Kubernetes provides multiple ways to address this; each has its upsides and down
|
||||||
|
|
||||||
For more information on the PROXY protocol, refer to [our dedicated docs page][docs-mailserver-behind-proxy] on the topic.
|
For more information on the PROXY protocol, refer to [our dedicated docs page][docs-mailserver-behind-proxy] on the topic.
|
||||||
|
|
||||||
!!! example
|
???+ example "Configure the Ingress Controller"
|
||||||
|
|
||||||
**Configure the Ingress Controller**
|
|
||||||
|
|
||||||
=== "Traefik"
|
=== "Traefik"
|
||||||
|
|
||||||
|
|
@ -594,9 +608,7 @@ Kubernetes provides multiple ways to address this; each has its upsides and down
|
||||||
993: "mailserver/mailserver:993::PROXY"
|
993: "mailserver/mailserver:993::PROXY"
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
???+ example "Adjust DMS config for Dovecot + Postfix"
|
||||||
|
|
||||||
**Adjust DMS config for Dovecot + Postfix**
|
|
||||||
|
|
||||||
??? warning "Only ingress should connect to DMS with PROXY protocol"
|
??? warning "Only ingress should connect to DMS with PROXY protocol"
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user