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
|
||||
|
||||
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 -->
|
||||
!!! quote ""
|
||||
|
||||
=== "`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
|
||||
---
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
**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
|
||||
---
|
||||
|
|
@ -92,7 +98,11 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
|||
|
||||
=== "`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
|
||||
---
|
||||
|
|
@ -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).
|
||||
|
||||
!!! example
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
|
|
@ -158,9 +170,7 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
|||
|
||||
=== "`Certificate`"
|
||||
|
||||
In this example, we use [`cert-manager`][cert-manager] to supply RSA 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.
|
||||
!!! example "Using [`cert-manager`][cert-manager] to supply TLS certificates"
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -183,11 +193,17 @@ If using our Helm chart is not viable, here is some guidance to start with your
|
|||
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`"
|
||||
|
||||
|
|
@ -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.
|
||||
- Additional options can be set to enforce runtime security.
|
||||
|
||||
???+ example
|
||||
|
||||
```yaml
|
||||
---
|
||||
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
|
||||
|
||||
securityContext:
|
||||
# `allowPrivilegeEscalation: true` is required to support SGID via the
|
||||
# `postdrop` executable in `/var/mail-state` for Postfix (maildrop + public dirs):
|
||||
# `allowPrivilegeEscalation: true` is required to support SGID via the `postdrop`
|
||||
# executable in `/var/mail-state` for Postfix (maildrop + public dirs):
|
||||
# https://github.com/docker-mailserver/docker-mailserver/pull/3625
|
||||
allowPrivilegeEscalation: true
|
||||
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
|
||||
- [ ] 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].
|
||||
|
||||
!!! example
|
||||
|
||||
```yaml
|
||||
---
|
||||
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.
|
||||
|
||||
!!! example
|
||||
|
||||
**Configure the Ingress Controller**
|
||||
???+ example "Configure the Ingress Controller"
|
||||
|
||||
=== "Traefik"
|
||||
|
||||
|
|
@ -594,9 +608,7 @@ Kubernetes provides multiple ways to address this; each has its upsides and down
|
|||
993: "mailserver/mailserver:993::PROXY"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Adjust DMS config for Dovecot + Postfix**
|
||||
???+ example "Adjust DMS config for Dovecot + Postfix"
|
||||
|
||||
??? warning "Only ingress should connect to DMS with PROXY protocol"
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue