How to Install on Kubernetes

This guide describes how to deploy docker-mailserver on Kubernetes with Kustomize. An external database is required (MySQL/MariaDB or PostgreSQL); the kustomization does not provision a database.

A full example is in example-configs/kustomize/external-db-and-https-ingress.

Prerequisites

  • Kubernetes cluster with kubectl configured
  • MySQL, MariaDB, Percona XtraDB or PostgreSQL database
  • Domain and DNS (for ingress)

Steps

1. Configure environment variables

Copy the example environment file and edit .env:

cp .env.dist .env

Set at least DB_PASSWORD, REDIS_PASSWORD, CONTROLLER_PASSWORD, and DOVEADM_API_KEY. See Environment variables reference.

2. Create namespace

kubectl create namespace mail

3. Generate TLS certificates (if not using cert-manager)

bin/create-tls-certs.sh

This writes a self-signed certificate to config/tls/tls.crt and key to config/tls/tls.key. For production, use CA certificates (e.g. cert-manager with Let's Encrypt) instead.

4. Create TLS secret

kubectl create -n mail secret tls tls-certs \
  --cert=config/tls/tls.crt \
  --key=config/tls/tls.key

5. Apply Kustomize manifests

From the project root, first split .env into the inputs of the ConfigMap config-env and the Secret secret-config-env:

bin/kubernetes-env.sh

This writes config/kubernetes/config.env and config/kubernetes/secret.env. Every key whose name contains PASSWORD, PASSWD or _KEY goes into the Secret, everything else into the ConfigMap. Run it again after every change to .env, then apply:

kubectl apply -n mail -k .

6. Verify pods

kubectl get pods -n mail

Wait until all pods are running and healthy.

7. Run setup wizard

kubectl exec -n mail -it deployment/web -- setup.sh

Use the wizard to set initial configuration, create the first email address, and create an admin user.

8. Access the management interface

Use your configured ingress and the admin credentials from the wizard.

Post-installation

Troubleshooting

  • Pods not starting: Check logs with kubectl logs -n mail <pod-name> and events with kubectl describe pod -n mail <pod-name>.
  • Database errors: Verify database connectivity and that the DB_* variables in ConfigMap/Secrets are correct.
  • TLS errors: Confirm the tls-certs secret exists in the mail namespace and certificate paths are correct.
  • Setup wizard fails: Ensure the web pod is running (kubectl get pods -n mail) before running the exec command.