How to Configure a Reverse Proxy (Traefik)
To run docker-mailserver behind a reverse proxy (e.g. Traefik) and preserve client IPs, enable PROXY protocol and point internal addresses at the proxy.
Steps
1. Enable PROXY protocol
In .env:
MDA_UPSTREAM_PROXY=true
MTA_UPSTREAM_PROXY=true
MDA_UPSTREAM_PROXY applies to IMAP, IMAPS, POP3, POP3S. MTA_UPSTREAM_PROXY applies to SMTP and submission (587).
2. Set trusted proxies
Dovecot only accepts PROXY protocol connections from these networks, and the web interface uses the same variable. Use your proxy’s CIDR range(s):
TRUSTED_PROXIES=10.0.0.0/8
3. Point internal addresses at the proxy
With PROXY protocol enabled, connections without a PROXY header fail, including those from other services. Point the internal service addresses at the proxy, not directly at MTA/MDA. Example for a Traefik internal service:
MDA_IMAP_ADDRESS=traefik-internal:33143
MDA_IMAPS_ADDRESS=traefik-internal:33993
MDA_POP3_ADDRESS=traefik-internal:33110
MDA_POP3S_ADDRESS=traefik-internal:33995
MTA_SMTP_ADDRESS=traefik-internal:3325
MTA_SMTP_SUBMISSION_ADDRESS=traefik-internal:33587
Adjust host and port names to match your Traefik configuration.
4. Configure Traefik (Kubernetes)
To use the provided Traefik ingress with Kustomize, add:
resources:
- deploy/kustomize/ingress/traefik
This adds IngressRoutes for SMTP (25), submission (587), IMAP (143), IMAPS (993), POP3 (110), POP3S (995). Configure entry points and PROXY protocol (v2) on the Traefik side to match.
5. Preserve the Host header
The MCP server matches MCP_ALLOWED_HOSTS against the raw Host header of the request, so any reverse proxy in front of the web service must pass it on unchanged. X-Forwarded-Host does not count. A request with a changed Host gets 403 Forbidden: Invalid Host header.
Traefik preserves the header by default, as long as passHostHeader stays on. nginx does not:
location / {
proxy_pass http://web:8080;
proxy_set_header Host $host;
}
With Apache, set ProxyPreserveHost On.
Also set TRUSTED_PROXIES as in step 2, or the audit log records the address of the proxy instead of the client.
Verification
- Check Traefik logs and IngressRoutes.
- Test connectivity to SMTP, submission, IMAP, and POP3 on the proxy’s public ports.
For variable details, see Environment variables reference (Proxy Protocol and Service Addresses). For a Docker Compose example, see Traefik reverse proxy example.