Environment Variables Reference

Overview of environment variables used to configure docker-mailserver. Set these in your .env file or in the environment.

Basic Configuration

Database

When using the database service provided by docker-mailserver compose, you do not need to set host, port, or database name. You must set DB_PASSWORD.

The DB_USER defaults above are the image defaults, which a Kubernetes deployment gets when it does not set the variable. Every compose service overrides it to mailserver.

DB_SERVER_VERSION has to match the server, because Doctrine cannot detect the PostgreSQL version by itself in this image. Use the major version, for example 18.

DB_TLS_VERIFY_CERT applies to the MTA and the MDA, and only with DB_DRIVER=mysql. The two services interpret it slightly differently, because Postfix and Dovecot expose different settings:

Certificates are validated against the system trust store, so yes requires a database certificate signed by a public CA. The bundled database container ships a self-signed certificate and fails validation.

PostgreSQL has no equivalent setting. Dovecot connects with sslmode=prefer; Postfix leaves the mode unset and uses the libpq default.

These variables configure the bundled database container only:

Using PostgreSQL

DB_DRIVER=pgsql
DB_PORT=5432
DB_SERVER_VERSION=18
# only when using the bundled database container
DB_IMAGE=postgres:18-alpine
DB_DATA_DIR=/var/lib/postgresql

Switching engines does not migrate any data. Run make clean first when using the bundled container: PostgreSQL refuses to initialise into a data directory that is not empty.

Renamed From MYSQL_*

The database variables were renamed from MYSQL_* to DB_*. Docker Compose deployments keep working with the old names, which are used as a fallback.

Kubernetes deployments have no such fallback, because the variables reach the containers straight from the generated ConfigMap. Rename them in your .env before applying the manifests.

Mail Server Identity

Redis

When using the Redis service provided by docker-mailserver compose or kustomize, you do not need to configure host or port. You must set REDIS_PASSWORD.

Authentication

Relay

Set RELAYHOST to [hostname]:port to route all outgoing mail through an external SMTP server. Leave unset to deliver directly.

Filter

Fetchmail

The fetchmail service passes this value straight to fetchmail --interval and has no fallback, so it must be set. .env.dist ships 300.

Startup

.env.dist ships WAITSTART_TIMEOUT=2m. The Kubernetes web Deployment sets SKIP_INIT=true, because an init container performs the provisioning instead.

TLS Certificate Generation

These configure the ssl container, which generates a self-signed certificate when none is mounted.

Extended Configuration

Service Addresses

The defaults above are the image defaults, which apply to Docker Compose. Kubernetes deployments override several of them in deploy/kustomize/common/configmap.yaml, because the Services publish different ports than the containers listen on: MDA_IMAP_ADDRESS becomes mda:143, WEB_HTTP_ADDRESS becomes web:80, and RSPAMD_DNS_SERVERS becomes round-robin:unbound:53. See Ports reference.

mailserver-admin

See mailserver-admin configuration reference.

PHP Sessions

Proxy Protocol

When set to true, the mail server accepts the HAProxy PROXY protocol to receive the original client IP when behind a load balancer or reverse proxy.

TRUSTED_PROXIES sets Dovecot's haproxy_trusted_networks. Without it, Dovecot rejects PROXY protocol connections even when MDA_UPSTREAM_PROXY is enabled. The same variable configures trusted proxies in mailserver-admin, see mailserver-admin configuration reference.