TOWERBY CETMIX
← Hangar / jet_template_stalwart_docker

Stalwart Mail Server with Docker and Traefik

Deploy a Stalwart all-in-one mail and collaboration server in Docker with an HTTPS web UI behind Traefik and an automated first-run setup.

↓ 0 downloads

Summary

Category
Jet Templates
Tags
Mail
Authors
Cetmix OÜ
License
AGPL-3
Version
1.0.0
Call sign
jet_template_stalwart_docker

This snippet imports a Stalwart Mail Server Jet Template using stalwartlabs/stalwart:v1. It allows one instance per server and runs SMTP, IMAP, POP3, JMAP, CalDAV and CardDAV in a single container. Configuration and mail are stored in two named Docker volumes labelled with the Jet reference. The web UI is served over HTTPS through a running Traefik Jet and reaches Stalwart on its internal HTTP port 8080. Mail ports 25, 465, 993, 995 and 4190 are published directly on the host, because Traefik cannot proxy them. Port 8080 is also published on the host loopback only. The Traefik, Docker, Fail2ban and Tower Core dependency templates are included.

Before you start

  1. The server needs a public IPv4 address, outbound port 25 and a reverse DNS (PTR) record for that address that matches the Jet hostname. Many hosting providers block port 25 by default, so check this first.
  2. Import the YAML and install the template on the server. Open the host firewall for the published mail ports and for ports 80 and 443 used by Traefik.
  3. Set the Stalwart Recovery Admin secret as admin:<password>. Use only letters, digits, underscore and hyphen, and a password of at least 16 characters.
  4. Configure the hostname and DNS. With Cloudflare DNS registration, set web_domain, cloudflare_token and cloudflare_zone_id. For other DNS providers, make sure the Jet has a URL and a matching DNS record. Set the Traefik instance_certbot_email to a valid contact address, for example admin@example.org. For a Traefik DNS challenge, set the selected provider's credentials (cloudflare_token, digitalocean_api_token, hetzner_api_token, or aws_dns_key_id and aws_dns_access_key).

Deploy

  1. Create a Jet and set stalwart_mail_domain to your primary mail domain, for example example.com. Target Running.
  2. Prepare locks the Jet against deletion, sets the Jet URL, registers the DNS record, validates the configuration and creates the volumes. Build pulls the image and creates a stopped container. Start starts it and waits until it is healthy.
  3. On a Jet that was never set up, Start also runs the automated first-run setup through the Stalwart management API and restarts the container. No wizard and no SSH tunnel are needed. It then applies the reverse-proxy settings, so bans and rate limits use the real client address from Traefik. The Docker private range 172.16.0.0/12 is allow-listed, so the proxy cannot ban itself.
  4. Sign in at https://<jet hostname>/admin as admin with the Stalwart Recovery Admin password. Configure ACME with the DNS-01 challenge in the admin UI, add mailboxes, and publish the MX, SPF, DKIM and DMARC records for your mail domain.
  5. Once the setup is finished, set stalwart_recovery_admin_mode to disabled and run Rebuild, so the recovery credentials are no longer passed to the container.

Operate and troubleshoot

Changed variables, secrets and the image tag are applied by Rebuild, not by Restart. Rebuild keeps all mail and configuration, but mail is unavailable while it runs. Remove deletes the container only and keeps the volumes and the deletion lock. Destroy permanently deletes all mail and configuration, the DNS record and the volumes. The Jet logs show the container output, the service health, the published ports and the setup status. If the web UI answers 502 behind Traefik, Stalwart has probably banned the proxy address. Review the allowed addresses in the admin UI. Start re-applies the reverse-proxy settings only while stalwart_recovery_admin_mode is enabled. If outgoing mail is rejected, check the PTR record, the SPF, DKIM and DMARC records and that outbound port 25 is open.