How to Install on Kubernetes

This guide describes how to deploy docker-mailserver on Kubernetes with Kustomize. An external MySQL-compatible database is required; 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 or Percona XtraDB (or compatible) database
  • Domain and DNS (for ingress)

Steps

1. Configure environment (ConfigMap and Secrets)

Use .env.dist as a reference for required variables. Create a Kubernetes ConfigMap for non-sensitive values and Secrets for sensitive values (credentials, passwords, API keys). See Environment variables reference for the full list.

See the example-configs/kustomize/external-db-and-https-ingress directory for a sample configuration showing how to structure these resources.

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:

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 -c php-fpm -- 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 MYSQL_* 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.