docker-compose-cookbooks/mailu_dev/README.md

Mailu

Overview

Mailu is a self-hosted mail server suite providing SMTP, IMAP, POP3, webmail, and antispam/antivirus filtering. This Docker Compose stack deploys the full Mailu system with persistent storage and an external reverse proxy for the admin/webmail UI.

Project Details

• Project Repository: Mailu
• Container Image: GitHub Container Registry
• Compose Example: Mailu Compose Setup
• Documentation: Configuration Reference
• Reverse Proxy Port: 80 (admin/webmail via front container)

Getting Started

1. Copy sample.env to .env and edit all values (especially DOMAIN, HOSTNAMES, SECRET_KEY, TLS_FLAVOR)
2. Create the required directories under ${VOL_PATH}/mailu/:
   • certs/ — TLS certificates (only needed if TLS_FLAVOR=cert)
   • overrides/ — optional service overrides
3. Start the stack: docker compose up -d
4. Create the initial admin user:

   docker compose exec admin flask mailu admin admin example.com 'password'
   

   Or use INITIAL_ADMIN_* env vars in .env for auto-creation.
5. Log in at https://mail.example.com/admin and configure domains, users, and aliases.

Environment Variable Notes

Compose

• VOL_PATH – base path for persistent data volumes (default: /data)
• BIND_ADDRESS4 – IPv4 address to bind mail ports (default: empty = all interfaces)
• MAILU_VERSION – Mailu image tag (default: 2024.06)
• MAILU_RESTART – container restart policy (default: always)
• MAILU_ORG – container registry org (default: ghcr.io/mailu)
• MAILU_WEBMAIL – webmail image choice (default: roundcube)

Domain

• DOMAIN – primary mail domain (required)
• HOSTNAMES – comma-separated public hostnames (required; first is primary)
• POSTMASTER – local part of the postmaster address (required)

Security

• SECRET_KEY – random 16+ character string for session encryption (required)
• TLS_FLAVOR – TLS mode: letsencrypt, cert, notls (default: cert)

Network

• SUBNET – Docker network subnet (default: 192.168.203.0/24)

Web

• WEB_ADMIN – admin interface path (default: /admin)
• WEB_WEBMAIL – webmail path (default: /webmail)
• WEB_API – API path (default: /api)
• SITENAME – site name in admin panel
• WEBSITE – linked website URL

Initial Admin

• INITIAL_ADMIN_ACCOUNT – admin username local part
• INITIAL_ADMIN_DOMAIN – admin domain (usually same as DOMAIN)
• INITIAL_ADMIN_PW – admin password
• INITIAL_ADMIN_MODE – creation mode: create, ifmissing, update

Volume Notes

All volumes are rooted at ${VOL_PATH:-/data}/mailu/:

• certs/ – TLS certificate and key files (cert.pem, key.pem)
• data/ – admin database and configuration
• dkim/ – DKIM signing keys
• filter/ – Rspamd spam filter state
• mail/ – user mailbox storage
• mailqueue/ – outgoing mail queue
• overrides/nginx/ – custom nginx config snippets
• overrides/dovecot/ – custom Dovecot config
• overrides/postfix/ – custom Postfix config
• overrides/rspamd/ – custom Rspamd config
• overrides/webmail/ – custom webmail config
• redis/ – Redis persistence data
• webmail/ – webmail plugin data

Network Notes

• Requires the external proxy network for HTTP/HTTPS access via Nginx Proxy Manager (admin, webmail, API).
• Mail protocols (SMTP, IMAP, POP3) are published directly on the host via the front container.
• An internal bridge network connects all Mailu services.

Docker Run

docker run -d \
  --name=mailu-redis \
  redis:alpine

docker run -d \
  --name=mailu-front \
  --env-file .env \
  -p 25:25 -p 465:465 -p 587:587 \
  -p 110:110 -p 995:995 \
  -p 143:143 -p 993:993 \
  -p 4190:4190 \
  -v /data/mailu/certs:/certs \
  -v /data/mailu/overrides/nginx:/overrides:ro \
  ghcr.io/mailu/nginx:2024.06

Additional Notes / Gotchas

• DNS setup is critical. Ensure MX, A/AAAA, SPF, DKIM, and DMARC records are configured before going live. See Mailu DNS docs.
• Port 25 requires the container to run with --network host or proper port publishing. Some ISPs block port 25 — verify before deploying.
• TLS certificates must exist in certs/cert.pem and certs/key.pem when TLS_FLAVOR=cert.
• Let's Encrypt requires ports 80 and 443 to be reachable from the internet and DNS records pointing to the server IP.
• Redis runs without authentication by default — keep it on the internal network only.
• The webmail service uses a Docker Compose profile (--profile webmail) and is not started by default.
• Skip the antivirus service to save ~1GB RAM — Mailu works without it.

Dockhand Stack, Deploy from Git

Cookbooks Repository stackname: mailu Compose file path: mailu_dev/compose.yaml Additional env file (optional): mailu_dev/sample.env

Then "Load" mailu_dev/sample.env into the Environmental variables in dockhand

Create the Stack