- Introduction
- Prerequisites
- Getting Started
- Configuration
- Values YAML
- Ports
- Persistence
- Upgrading to Version 3.0.0
- Development
(Created by gh-md-toc)
This chart deploys docker-mailserver into a Kubernetes cluster. docker-mailserver is a production-ready, fullstack mail server that supports SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). Just as importantly, it is designed to be simple to install and configure.
!!WARNING!! - Version 3.0.0 is not backwards compatible with previous versions. Please refer to the upgrade section for more information.
- Helm
- A Kubernetes cluster with persistent storage and access to email ports
- A custom domain name (for example, example.com)
- Correctly configured DNS
Setting up docker-mailserver requires generating a number of configuration files. To make this easier, docker-mailserver includes a setup command that can generate these files.
To get started, first add the helm repo and install docker-mailserver:
helm repo add docker-mailserver https://docker-mailserver.github.io/docker-mailserver-helm
helm upgrade --install docker-mailserver docker-mailserver/docker-mailserver --namespace mail --create-namespaceNext open a command prompt to the running container.
kubectl exec -it --namespace mail deploy/docker-mailserver -- bashAnd now create a new account for Postfix and Dovecot.
kubectl exec -it --namespace mail deploy/docker-mailserver -- bash
setup email add [email protected] passwordAlternatively you can do it one step like this:
$kubectl exec -it --namespace mail deploy/docker-mailserver -- setup email add [email protected] passwordAccount information will be saved in a file postfix-accounts.cf in the container path:
cat /tmp/docker-mailserver/postfix-accounts.cfThis path is mapped to a Kubernetes Volume.
Assuming you still have a command prompt open in the running container, run the setup command to see additional configuration options:
setupAs you run various setup commands, additional files will be generated. At a minimum you will want to run:
setup email add [email protected] password
setup config dkim keysize 2048 domain 'example.com'These paths are stored to the container path /tmp/docker-mailserver which is mapped to a Kubernetes Volume.
Configuration files are stored on a Kubernetes volume mounted at /tmp/docker-mailserver in the container. The PVC is named mail-config. You can of course add additional configuration files to the volume as needed.
Its is also possible to use ConfigMaps to mount configuration files in the container. This is done by adding to the configFiles key in a custom values.yaml file. For more information please see the documentation in values.yaml
Secrets can also be used to mount configuration files in the container. For example, dkim keys could be stored in a secret as opposed to a file in the mail-config volume. Once again, for more information please see the documentation in values.yaml
In addition to the configuration files generated above, the values.yaml file contains a number of knobs for customizing the docker-mailserver installation. Please refer to the extensive comments in values.yaml for additional information.
Included in the knobs are many environment variables which allow you to customize the behaviour of docker-mailserver. These environment variables are documented in the docker-mailserver's configuration page. Note that docker-mailserver expects any true/false values to be set as numbers (1/0) rather than boolean values (true/false).
By default, the Chart enables rspamd and disables opendkim, dmarc, policyd-spf and clamav. This is the setup recommended by the docker-mailserver project.
Once you have created your own values.yaml files, then redeploy the chart like this:
helm upgrade docker-mailserver docker-mailserver --namespace mail --values <path_to_values.yaml>You can also override individual configuration setting with helm upgrade --set, specifying each parameter using the --set key=value[,key=value] argument to helm install. For example:
$helm upgrade docker-mailserver docker-mailserver --namespace mail --set pod.dockermailserver.image="your/image:1.0.0"There are various settings in values.yaml that you must override.
| Parameter | Description | Default |
|---|---|---|
| deployment.env.OVERRIDE_HOSTNAME | The hostname to be presented on SMTP banners | mail.example.com |
certificate |
Name of a Kubernetes secret that stores TLS certificate for your mail domain |
You will need to setup a TLS certificate for your email domain. The easiest way to do this is use cert-manager.
Once you acquire a certificate, you will need to store it in a TLS secret in the docker-mailserver namespace. Once you have done that, update the values.yaml file like this:
certificate: my-certificate-secretThe chart will then automatically copy the certificate and private key to the /tmp/dms/custom-certs director in the container and correctly set the SSL_CERT_PATH and SSL_KEY_PATH environment variables.
If you are running on a bare-metal Kubernetes cluster, you will have to expose ports to the internet to receive and send emails. In addition, you need to make sure that `docker-mailserver`` receives the correct client IP address so that spam filtering works.
This can get a bit complicated, as explained in the docker-mailserver documentation.
One approach to preserving the client IP address is to use the PROXY protocol, which is explained in the documentation.
The Helm chart supports the use of the proxy protocol via the proxyProtocol key. To enable it set the proxyProtocol.enable key to true. You will also want to set the trustedNetworks key.
proxyProtocol:
enabled: true
# List of sources (in CIDR format, space-separated) to permit PROXY protocol from
trustedNetworks: "10.0.0.0/8 192.168.0.0/16 172.16.0.0/16"Enabling the PROXY protocol will create an additional port for each protocol (by adding 10,000 to the standard port value) that is configured to understand the PROXY protocol. Thus:
| Protocol | Port | PROXY Port |
|---|---|---|
| submissions | 465 | 10465 |
| submission | 587 | 10587 |
| imap | 143 | 10143 |
| imaps | 993 | 10993 |
| pop3 | 110 | 10110 |
| pop3s | 995 | 10995 |
If you do not enable the PROXY protocol and your mail server is not exposed using a load-balancer service with an external traffic policy in "Local" mode, then all incoming mail traffic will look like it comes from a local Kubernetes cluster IP.
By default, the Chart assumes there are for Persistent volumes. Thus it requests four PersistentVolumeClaims which are defined using the persistent_volume_claims key. Each PVC can be set to an existing claim by settin the persistent_volume_claims.<volume_name>.existing_claim key or a new cliams. To disable creation of a PVC, set persistent_volume_claims.<volume_name>.enabled to false. The default PVCs have the following characteristics:
| PVC Name | Default Size | Mount | Description |
|---|---|---|---|
| mail-config | 1Mi | /tmp/docker-mailserver | Stores generated configuration files |
| mail-data | 10Gi | /var/mail | Stores emails |
| mail-state | 1Gi | /var/mail-state | Stores state for mail services |
| mail-log | 1Gi | /var/log/mail | Stores log files |
The PVCs are then mounted to volumeMounts via the persistence key. Each volumeMount must specify a volume name and mount path. It is also possbile to set a subpath via the subPath key.
Extra volumes and volume mounts may be added using the extraVolumes and extraVolumeMounts keys.
Version 5.0 upgrades docker-mailserver to version 15. This version of the chart does include backwards incompatible changes
Previously by default the Chart created four persistent volume claims and then mounted them to the container. This made it difficult for users that want to use just one Volume. Therefore the persistence key was spit into two keys:
persistent_volume_claimspersistence
This separate the creation of PVCs from mounting their associated volumes. If you previously overrode the creation of PVCs or their mount paths you will need to update your custom values.yaml file.
Version 4.0 upgrades docker-mailserver to version 14. There are no backwards incompatible changes in the chart.
Version 3.0 is not backwards compatible with previous versions. The biggest changes include:
- Usage of four PersistentVolumeClaims (PVCs) instead of one
- Usage of a PVC to store configuration files
- Rearrangement of keys in
values.yaml - Removal of RainLoop and HaProxy
- Removal of Cert Manager
- Enable rspamd by default
Previously the Chart created a single PVC to store emails, logs and the state of various docker-mailserver components. Now the Chart creates four PVCs, as described in the persistence section. One of the PVCs is mail-config which is used to store configuration files.
The addition of the mail-config PVC removes the requirement to use the setup.sh script and its dependency on Docker or Podman. Instead, you can directly deploy the chart to a Kubernetes cluster. For more information see the configuration files section.
To upgrade you will need to copy data from the existing PersistentVolume (PV) to one of the new PVs:
| Original PV | Path | New PV | Path |
|---|---|---|---|
| docker-mailserver | mail-data | mail-data | / |
| docker-mailserver | mail-state | mail-state | / |
| docker-mailserver | mail-log | mail-log | / |
The location of a number of keys has changed in the chart. Please see values.yaml for the changed locations.
The Chart now enables Rpsamd by default as recommened by the docker-mailserver documentation. You can disable this change by setting the environment variable ENABLE_RSPAMD to 0 and setting ENABLE_OPENDKIM, ENABLE_OPENDMARC and ENABLE_POLICYD_SPF to 1.
If you keep this change, you will need to generate new DKIM signing keys (see the configuration section for more information). In addition, you may wish to enable the Rspamd ingress (see rspamd.ingress.enabled)
Support for creating a TLS certificate using cert-manager has been removed. Instead, create a secret that contains a certificate before installing the chart and reference it via the certificate key. Of course you can use cert-manager to create this secret - it is just not part of this chart anymore.
Support for installing HaProxy with the Chart has been removed. Instead, generic support for the Proxy protocol has been added.
Unit tests are created for every chart template. Tests are applied to confirm expected behaviour and interaction between various configurations.
In addition to tests above, a "snapshot" test is created for each manifest file. This permits a final test per-manifest, which confirms that the generated manifest matches exactly the previous snapshot. If a template change is made, or legit value in values.yaml changes (i.e., the app version) this snapshot test will fail.
If you're comfortable with the changes to the saved snapshot, then regenerate the snapshots, by running the following from the root of the repo
$helm plugin install https://github.com/lrills/helm-unittest
$helm unittest helm-chart/docker-mailserver