First of all, what is Stalwart?
Stalwart is an open-source, all-in-one mail and collaboration server written in Rust. It speaks IMAP4, JMAP, POP3, SMTP, CalDAV, CardDAV and WebDAV, and ships with built-in spam and phishing filtering, full-text search, Sieve scripting, DKIM/SPF/DMARC/ARC support and a web-based administration console.
Running your own mail server used to mean stitching together Postfix (MTA), Dovecot (IMAP/POP3), Rspamd (spam), OpenDKIM, Let's Encrypt scripts and a webmail on top. Stalwart replaces that whole stack with a single binary that handles every protocol and every authentication concern in one place. It is secure, memory-safe (thanks to Rust) and scales from a small VPS to a cluster.
This guide covers the three things you need to go live on Dokploy: a compose project that runs Stalwart, a webmail (Bulwark) so your users can read and send mail from the browser, and automatic TLS certificate syncing so IMAP/SMTP/Submission keep a valid certificate without manual work. The mail ports are published directly on the Stalwart container, so there is no TCP proxy in front and the server sees the real client IP. Migrating existing mailboxes from another server will be covered in a separate article.
This was supposed to be simple... ¡Hope this post helps someone!
Edited: Some people might ask, "Why? Is this necessary?' Well, actually, no. But it's simple: you have a Dokploy server, and you are also paying for a mail subscription that you want to stop. So you ask yourself: is there an advanced, lightweight service that I can deploy on my Dokploy server(s)? If you add new servers or VPSs with just Stalwart or just Docker, without any PaaS like Dokploy, keep it simple. Don't do this. But if you want to use what you already have and you have Dokploy, read on, because it won't be as easy as deploying the existing official template from Dokploy and continuing with your life. In this version the mail ports are published directly on the Stalwart container, which keeps the deployment simple.
Edit note (2026-10-05): The original version of this post pushed the mail ports through Traefik with TCP routers, extra entrypoints, additional port mappings and Proxy Protocol. It worked, but it was needlessly complex and, honestly, a bit stupid. This version publishes the ports directly on the Stalwart container: this is the setup a monkey with a single working neuron would use. If you already copied the old configuration... sorry, it still works, but sorry...
What are we using in this guide?
| Component | Value |
|---|---|
| Platform | Dokploy (self-hosted PaaS) |
| Image | stalwartlabs/stalwart:v0.16-alpine |
| Webmail | ghcr.io/bulwarkmail/webmail:1.11.0 |
| Cert sync | ghcr.io/kereis/traefik-certs-dumper |
| Edge proxy | Traefik (managed by Dokploy) |
| Protocols | SMTP, IMAP, JMAP, POP3, ManageSieve, CalDAV, CardDAV |
| Data store | RocksDB (default, local) |
The -alpine Stalwart image bundles the server binary with a minimal Alpine runtime. It runs as the unprivileged user stalwart (UID 2000) and is published to both Docker Hub and the GitHub Container Registry. Pin a v<major>.<minor> tag like v0.16-alpine for production instead of chasing latest.
Considerations
- A VPS with at least 2 GB of RAM and a public, static IPv4 address. Mail delivery relies heavily on IP reputation, so a provider that lets you configure reverse DNS (PTR) is strongly recommended.
- A working Dokploy installation. The official documentation covers the install script and the first login; this guide assumes you already have a project and an environment ready.
- A domain you control (e.g.
example.com) with DNS managed by your provider or an API-enabled provider (Cloudflare, Route 53, Google Cloud DNS, ...) if you want automatic DNS management. - Full control of the firewall: the mail ports
25,110,143,465,587,993,995and4190are published directly by the Stalwart container, while80/443(Traefik) and8484(JMAP) serve the HTTP surface. - You are aware that email deliverability depends on your IP reputation, check the IP against DNS blocklists before going live and keep the SPF/DKIM/DMARC records correct.
How the pieces fit together
Dokploy ships with a Traefik instance that terminates HTTPS for every service. That works great for HTTP, but mail is different: SMTP, IMAP, POP3 and Submission speak raw TCP with TLS that Stalwart terminates itself. Instead of forcing those ports through Traefik as TCP routers, this guide publishes them directly on the Stalwart container with a plain ports: mapping. (i'm really really sorry for being stubborn since the beggining and not noticing I wasn't using ports: but expose: since the begging) Docker forwards the host port to the container and Stalwart sees the real client IP; there is no proxy in the middle.
For the HTTP surface you still use Dokploy's domain management as usual. The mail entrypoints, the Additional Port Mappings for the mail ports and the file provider with one TCP router per port are no longer needed: the compose file itself is the whole routing configuration for mail. Traefik is kept only for the WebUI/JMAP endpoint, so it still terminates HTTPS there, applies the CORS middleware and keeps issuing the Let's Encrypt certificate that cert-sync hands to Stalwart.
The final stack looks like this:
- Stalwart (
stalwart-mail): the mail server itself. - Bulwark (
bulwark): the webmail, connected to Stalwart over JMAP. - cert-sync: watches Traefik's
acme.json, dumps the current certificate for your mail host, and tells Stalwart to reload it whenever it is renewed. Only needed when DNS-01 validation is not available (see the note in Step 2).
Step 1: Prepare DNS before deploying
DNS is the part that breaks most self-hosted mail deployments. Configure these records before you cut over:
| Type | Name | Value |
|---|---|---|
| A | mail.example.com | your VPS IPv4 |
| MX | example.com | 10 mail.example.com. |
| PTR | reverse zone | mail.example.com (set at your hosting provider) |
The PTR record is especially important, many receiving servers reject mail from IPs without a proper reverse DNS entry. Do not skip it.
You will add SPF, DKIM and DMARC after the setup wizard, because Stalwart generates the DKIM keys for you.
Step 2: Create the compose project in Dokploy
In Dokploy, create a new Compose service inside a project and an environment. Give it a name, keep the source as Raw or paste a docker-compose.yml, and set Create .env File to on, you will define secrets through the environment panel.
The core of the project is the compose file. It defines three services: Stalwart, the Bulwark webmail, and the certificate sync helper.
services:
stalwart-mail:
image: stalwartlabs/stalwart:v0.16-alpine
restart: unless-stopped
ports:
- "25:25"
- "110:110"
- "143:143"
- "465:465"
- "587:587"
- "993:993"
- "995:995"
- "4190:4190"
expose:
- "8080"
volumes:
- stalwart-etc:/etc/stalwart
- stalwart-data:/var/lib/stalwart
- /etc/dokploy/traefik/certs/mail:/etc/stalwart/certs:ro
environment:
STALWART_RECOVERY_ADMIN: ${STALWART_RECOVERY_ADMIN}
STALWART_LOG_TARGETS: console:stdout=info
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/healthz/live >/dev/null 2>&1 && nc -z 127.0.0.1 25 && nc -z 127.0.0.1 587 && nc -z 127.0.0.1 993 || exit 1"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
bulwark:
image: ghcr.io/bulwarkmail/webmail:1.11.0
restart: unless-stopped
environment:
JMAP_SERVER_URL: https://mail.example.com:8484
APP_NAME: Example Webmail
APP_SHORT_NAME: Mail
SESSION_SECRET: ${BULWARK_SESSION_SECRET}
volumes:
- bulwark-data:/app/data/admin
- bulwark-state:/app/data/admin-state
depends_on:
- stalwart-mail
cert-sync:
image: ghcr.io/kereis/traefik-certs-dumper:latest
restart: unless-stopped
environment:
DOMAIN: mail.example.com
CERTIFICATE_FILE_NAME: mail.example.com
PRIVATE_KEY_FILE_NAME: mail.example.com
CERTIFICATE_FILE_EXT: .crt
PRIVATE_KEY_FILE_EXT: .key
OVERRIDE_UID: "2000"
OVERRIDE_GID: "2000"
POST_HOOK_FILE_PATH: /hook/hook.sh
STALWART_API_TOKEN: ${STALWART_API_TOKEN}
volumes:
- /etc/dokploy/traefik/dynamic/acme.json:/traefik/acme.json:ro
- /etc/dokploy/traefik/certs/mail:/output:rw
- /etc/dokploy/traefik/reload-stalwart.sh:/hook/hook.sh:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
networks:
default:
name: dokploy-network
external: true
volumes:
stalwart-etc:
stalwart-data:
bulwark-data:
bulwark-state:yamlNotes:
- Stalwart runs as UID/GID 2000, which is why
OVERRIDE_UIDandOVERRIDE_GIDincert-syncare set to2000, the dumped files must be readable by the mail process. - The
portsblock publishes the mail protocols directly on the host. Docker forwards the traffic to the container, Stalwart terminates the TLS for IMAP/SMTP/POP3 itself and therefore sees the client's real IP.expose: "8080"is only there so Traefik can reach the WebUI/JMAP listener over thedokploy-network. - The
cert-synccontainer mounts Traefik'sacme.json(newer Dokploy keeps it at/etc/dokploy/traefik/dynamic/acme.json) and writes the extracted certificate to/etc/dokploy/traefik/certs/mail/, which Stalwart mounts read-only at/etc/stalwart/certs. - No static IPs needed. The services join the shared
dokploy-networkand get whatever address Docker assigns. This works because every reference to Stalwart from Traefik orcert-syncuses the Docker DNS namestalwart-mail. Pinning an IP in the compose is an unnecessary hard dependency. - The healthcheck is the standard
curl+nccombination. It verifies both the HTTP API and that the SMTP/Submission/IMAPS listeners are actually bound, so a container that lost its listeners is marked unhealthy instead of pretending everything is fine. It connects to127.0.0.1, so the probes are processed as direct connections. STALWART_RECOVERY_ADMINandSTALWART_API_TOKENare read from the environment panel. Define them asKey = Valuepairs there; compose variables are substituted automatically.
Do you even need
cert-sync? Only use thiscert-syncsetup when your certificate provider and your DNS provider do not let you solve the ACME challenge with DNS-01. If they do, let Stalwart manage its own certificates with DNS-01 and omit thecert-syncservice, its volumes and the reload hook entirely.
Environment variables
In the Dokploy environment panel define:
| Key | Value |
|---|---|
STALWART_RECOVERY_ADMIN | admin:your-strong-password (bootstrap/recovery credential) |
STALWART_API_TOKEN | an API token generated in Stalwart used by cert-sync to reload certificates |
BULWARK_SESSION_SECRET | a random string for the webmail session signing |
Generate the random values on the host:
openssl rand -hex 32bashBULWARK_SESSION_SECRET can be any random string from the command above. STALWART_RECOVERY_ADMIN is your bootstrap admin. The STALWART_API_TOKEN is not a random string: it must be an API key created inside Stalwart that grants permission to reload the TLS certificates, because cert-sync uses it to call the Stalwart API over JMAP.
Create it in the Stalwart WebUI after the first sign-in (once the WebUI is reachable, see Step 6):
- Go to Management › API Keys (or Access Control › API Keys, depending on the version).
- Click Create and generate a key (or paste one you generated).
- Enable the permission
actionReloadTlsCertificates(that is the method the reload hook invokes; without it the call returns a permission error and certificates never refresh). - Copy the key value and set it as
STALWART_API_TOKENin the Dokploy environment, then redeploycert-sync.
Ordering note: the token is only consumed by
cert-sync, so you can create it after deploying — butcert-syncwill log a failed reload until the token exists and matches. If you prefer to deploy everything in one shot, run the wizard, create the API key, then addSTALWART_API_TOKENto the environment and redeploy the compose.
Step 3: Publish the mail ports directly
The mail ports are already published by the ports: block in the compose file, so there is nothing to route in Traefik: Docker forwards host:port straight to the Stalwart container, and Stalwart answers on the matching listener with its own TLS certificate (supplied by cert-sync, Step 2).
That means you do not need:
- a
stalwart.ymlfile provider with one TCP router per port, - extra mail entrypoints (
smtp,smtps,submission,imap,imaps,pop3,pop3s,sieve) in Traefik's static config, - an Additional Port Mapping for the mail ports.
Traefik is kept only for the WebUI/JMAP endpoint. Because Stalwart's HTTP listener is on 8080 inside the container and 8080 is Dokploy's own API port, that one keeps going through a dedicated stalwart-web entrypoint on 8484.
Why not use port
443? On a Dokploy host, Traefik already owns all80/443traffic for every service. Traefik terminates TLS for the mail HTTP surface on thestalwart-webentrypoint (8484) and forwards plain HTTP to the Stalwart container on8080. Reusing443would also work, since Traefik routes byHost, but I keep the mail endpoint on its own port because I prefer to publish the whole service under a single domain: the admin console and the JMAP API onmail.example.com:8484, together with the Bulwark webmail.
Register the JMAP entrypoint in the static config
The stock traefik.yml only defines the HTTP entrypoints web and websecure, so add stalwart-web so Traefik also listens on 8484.
Edit /etc/dokploy/traefik/traefik.yml (mounted into the container at /etc/traefik/traefik.yml):
sudo nano /etc/dokploy/traefik/traefik.ymlbashAdd under the existing entryPoints: section:
entryPoints:
stalwart-web:
address: :8484yamlSave the file and restart the Traefik container so the new entrypoint binds its port:
sudo docker restart dokploy-traefikbashPublish the JMAP port on the host (Additional Port Mapping)
Declaring stalwart-web makes Traefik bind :8484 inside its container, but Dokploy does not forward it from the host automatically. In Dokploy go to Settings › Web Server › Traefik › Additional Port Mapping and add a single entry:
| Host Port | Container Port | Protocol |
|---|---|---|
8484 | 8484 | TCP |
Save and apply; Dokploy recreates Traefik with the published port.
Migrating from the old TCP-router setup? If you previously routed the mail ports through Traefik, remove their Additional Port Mappings and the
stalwart.ymlfile provider first. Otherwise Docker cannot bind the mail ports on the Stalwart container and the deploy fails withbind: address already in use.
Create the CORS middleware for the webmail
The Bulwark webmail is served on https://mail.example.com (443) and calls the JMAP API on https://mail.example.com:8484 from the browser. Same host, different port, which is still a different origin, and Stalwart's HTTP listener only serves the API, it does not add the Access-Control-Allow-Origin headers for it. You must create a CORS middleware in the dynamic directory and attach it to the JMAP domain.
Create /etc/dokploy/traefik/dynamic/middlewares.yml:
http:
middlewares:
stalwart-cors:
headers:
accessControlAllowOriginList:
- https://mail.example.com
accessControlAllowMethods:
- GET
- POST
- OPTIONS
- PUT
- PATCH
- DELETE
accessControlAllowHeaders:
- Authorization
- Content-Type
- X-JMAP-Request-Id
addVaryHeader: trueyamlNotes:
accessControlAllowOriginListmust contain exactly the webmail origin (https://mail.example.com). Traefik then emits the correctAccess-Control-Allow-Originheader and, becauseaddVaryHeader: true, also sendsVary: Originso browsers do not cache the wrong CORS response across origins.- The allowed methods and headers above cover the JMAP calls the webmail makes (including the
AuthorizationandX-JMAP-Request-Idheaders). - The file provider watches
middlewares.ymltoo, so no Traefik restart is needed after saving it. - This middleware is what the
stalwart-webHTTP router will reference in Step 6; without it the webmail's JMAP requests will be rejected by the browser with a CORS error even though the API itself works.
Alternative: everything on 443 with two domains
If you do not want a dedicated port at all, you can route Stalwart's HTTP surface through Traefik's default websecure entrypoint on 443 and split the service across two FQDNs: mail.example.com for the WebUI/JMAP and webmail.example.com for Bulwark. In that case you do not need the stalwart-web entrypoint, you do not restart Traefik to add it, and you do not create any Additional Port Mapping: nothing is published on 8484.
In Step 6, instead of the stalwart-web entrypoint, add two domains through Dokploy's normal domain form:
| Service | Host | Container Port | Entrypoint | HTTPS |
|---|---|---|---|---|
stalwart-mail | mail.example.com | 8080 | websecure (default) | on |
bulwark | webmail.example.com | 3000 | websecure (default) | on |
Then set JMAP_SERVER_URL to https://mail.example.com (no :8484) and change the CORS middleware origin to https://webmail.example.com.
Why does 8080 appear here if it cannot be published? Dokploy's own API already binds host port 8080, so you cannot publish it as a host port, but Traefik does not need that. The number in the Dokploy domain form is the container port: Traefik reaches Stalwart's 8080 over the dokploy-network and exposes it on 443. No host port is involved.
The trade-off: with websecure you share 443 with every other Dokploy service (fine, Traefik routes by Host) and the webmail lives on a second FQDN. The single-FQDN setup documented in Steps 6 and 8 keeps the whole service on mail.example.com at the cost of one extra entrypoint and one additional port mapping.
Step 4: Create the certificate reload hook
Skip this step if Stalwart manages its own certificates with DNS-01 (see the note in Step 2).
The cert-sync container dumps the current certificate whenever Traefik renews it, then runs a post-hook. The hook must tell Stalwart to reload its TLS material. The clean way is to call the Stalwart API over JMAP with the token from the environment:
Create /etc/dokploy/traefik/reload-stalwart.sh:
#!/bin/sh
set -eu
wget --quiet --post-data='{"using":["urn:ietf:params:jmap:core"],"methodCalls":[["x:Action/set",{"type":"tls","action":"reload"},"reload"]]}' \
--header="Authorization: Bearer ${STALWART_API_TOKEN}" \
--header="Content-Type: application/json" \
-O - http://stalwart-mail:8080/api 2>/dev/null || truebashMake it executable, otherwise the post-hook silently does nothing:
sudo chmod +x /etc/dokploy/traefik/reload-stalwart.shbashNotes:
- The image running
cert-syncis minimal, so the hook useswget(present in the image) and deliberately fails open (|| true): a reload failure should not abort the dump or restart anything. - The hook is mounted read-only into the container at
/hook/hook.shand readsSTALWART_API_TOKENfrom the environment passed through the compose project. STALWART_API_TOKENmust be the Stalwart API key you created (with theactionReloadTlsCertificatespermission) — see the environment variables section in Step 2. A random string that is not a valid Stalwart API key makes the reload return an authentication error, which the hook silently swallows.- Because the hook triggers a reload through the API instead of restarting the container, no mail session is interrupted and Traefik keeps its established backend connections. Restarting the container after every renewal would drop active IMAP/SMTP sessions for no reason.
Step 5: Client IPs and auto-ban (no Proxy Protocol)
With the mail ports published directly, Stalwart accepts the mail connections itself and sees the client's real address. This is the biggest win of dropping the TCP router: SPF/DMARC sender authentication, per-IP rate limiting and auto-banning all work on the real client IP. There is no proxy IP to block, so the "Stalwart banned Traefik and every port died" trap of the proxy-based design cannot happen.
Rules that matter:
- Do not enable Proxy Protocol on a directly exposed listener. There is no proxy prepending a PROXY header, so
proxy_protocolmust stayoff(the default). If you turn it on, Stalwart parses the first bytes of the client's TLS handshake as a PROXY header and resets the connection. - Clear the old trusted networks when migrating. Remove
overrideProxyTrustedNetworksfrom each mail listener and drop thestalwart-proxyserversTransportfrom the file provider you deleted in Step 3. They only apply to the Traefik-TCP design. - The HTTP listener still uses
X-Forwarded-For. WebUI/JMAP go through Traefik in HTTP mode, so keepuseXForwarded = trueinSettings › Network › HTTP › General. Do not set proxy trust there either: Traefik terminates TLS and forwards plain HTTP.
How to recognise the old design: security.ip-blocked entries for a 10.0.1.x address, or TLS handshake errors with reason = "received corrupt message of type InvalidContentType", mean Stalwart is talking to a proxy it should not be talking to. In this setup those logs disappear, because the proxy is out of the mail path.
Step 6: Publish the WebUI / JMAP endpoint and run the setup wizard
Deploy the project from Dokploy. The Stalwart admin UI (WebUI) and the JMAP API are served by the same HTTP listener on port 8080. You cannot publish that port directly on the host, because port 8080 is Dokploy's own API port, so the WebUI/JMAP must reach the internet through Traefik. In the setup below that is the stalwart-web entrypoint you added in Step 3; if you chose the alternative in Step 3, use the standard websecure entrypoint instead.
In Dokploy, add a single domain to the stalwart-mail service that serves both the admin UI and JMAP:
- Host:
mail.example.com - Port:
8080 - Entrypoint:
stalwart-web - Middlewares:
stalwart-cors@file - HTTPS: on (Let's Encrypt)
The stalwart-cors middleware (created in Step 3) is what lets the Bulwark webmail call the JMAP API cross-origin from the browser. It must be attached here, otherwise the webmail's requests will be rejected with a CORS error.
This one domain is the whole story for Stalwart's HTTP surface: the admin UI lives at https://mail.example.com:8484/admin and the JMAP API at https://mail.example.com:8484. Do not create a separate plain-HTTP domain for bootstrap — the WebUI and JMAP share the same route, and you cannot bypass Traefik to reach 8080.
If your DNS does not resolve yet, edit /etc/hosts on the machine you browse from (or use an IP-based host entry) pointing mail.example.com to the server, and open:
https://mail.example.com:8484/admintextAccept the temporary certificate warning if Let's Encrypt has not finished issuing yet. Sign in with admin and the password from STALWART_RECOVERY_ADMIN. The wizard has five screens:
- Server identity: set
mail.example.comas the hostname andexample.comas the default domain. Leave both toggles enabled: Stalwart will request a Let's Encrypt TLS certificate automatically (ACME) and generate DKIM signing keys for the domain. - Storage: keep the defaults (RocksDB) for a single-node VPS.
- Account directory: keep Internal Directory so accounts are managed through the WebUI.
- Logging: choose Console so Docker's log driver captures the logs. That is also what the
STALWART_LOG_TARGETSvariable in the compose file does; pick one approach and keep them consistent. - DNS management: choose Manual DNS Server Management for now, or select a provider if you want Stalwart to publish the records automatically.
The final screen prints the administrator email and a randomly generated password. Write both down, this is the only time the password is shown.
Step 7: Publish the DNS records
In the admin UI go to Management › Domains, open your domain's menu and select View DNS Zone file. Stalwart gives you the complete zone file for the domain, everything from MX, SPF, DKIM and DMARC to MTA-STS and autoconfig/autodiscover.
Add those records to your DNS provider. If you configured automatic DNS management in the wizard, Stalwart publishes them itself through the provider API and keeps them in sync.
After the records propagate (give it 5–30 minutes), verify the authentication chain:
# SPF
dig +short TXT example.com
# DKIM
dig +short TXT default._domainkey.example.com
# DMARC
dig +short TXT _dmarc.example.combashThe DKIM public key in DNS must match the one Stalwart generated for the domain. If you publish the records by hand, copy the value from the zone file exactly, a single character difference breaks signature validation and your mail will be marked as spam.
Step 8: Add the Bulwark webmail on the same domain
In Dokploy, add a domain to the bulwark service:
- Host:
mail.example.com - Port:
3000 - HTTPS: on (Let's Encrypt)
Bulwark and Stalwart share the mail.example.com FQDN but listen on different ports: Bulwark on 443 through Traefik's default websecure entrypoint, Stalwart's WebUI/JMAP on 8484 through stalwart-web. Open https://mail.example.com and sign in with a Stalwart account. If the webmail does not find the JMAP endpoint automatically, point it to https://mail.example.com:8484. CORS is already handled by the stalwart-cors middleware you attached to the JMAP domain in Step 6; if you still see CORS errors in the browser, double-check that the middleware's accessControlAllowOriginList matches the exact webmail origin (https://mail.example.com).
Step 9: Create accounts
Add users in Management › Accounts. Each account needs:
- The email address (e.g.
alice@example.com). - A password (or let Stalwart generate one).
- A mailbox quota if you want per-user limits.
Mail clients connect using:
| Protocol | Host | Port | Encryption |
|---|---|---|---|
| IMAP | mail.example.com | 993 | SSL/TLS |
| SMTP (submission) | mail.example.com | 587 | STARTTLS |
| JMAP | https://mail.example.com:8484 | - | HTTPS |
Step 10: Backups
Back up the named volumes. The safest approach is a scheduled job on the host that snapshots the data directory:
sudo tar czf /backup/stalwart-data-$(date +%F).tar.gz \
-C /var/lib/docker/volumes stalwart-databashOr stop the containers briefly and copy the volume:
sudo docker compose -f /etc/dokploy/compose/<project>/code/docker-compose.yml stop
sudo docker run --rm -v stalwart-etc:/etc -v "$PWD":/backup \
alpine tar czf /backup/stalwart-etc-$(date +%F).tar.gz -C /etc .
sudo docker compose -f /etc/dokploy/compose/<project>/code/docker-compose.yml startbashStore the archive off-server and test a restore before you need it.
Scheduled backups to an S3 endpoint with Dokploy
Instead of shell scripts, you can let Dokploy snapshot the compose volumes on a schedule and upload them to any S3-compatible endpoint (AWS S3, Cloudflare R2, MinIO, Backblaze B2, DigitalOcean Spaces...).
In Dokploy, open the stalwart compose service and go to the Backups tab:
- Create a Backup and pick the volumes to include. For Stalwart you need at least:
- stalwart-data (/var/lib/stalwart — the mail store, accounts, keys and queues) - stalwart-etc (/etc/stalwart — the configuration) - bulwark-data and bulwark-state if you want the webmail settings preserved
- Choose the schedule (e.g. daily at
0 3 * * *). - Under Storage, configure the S3 destination:
- Endpoint: the S3 endpoint URL of your provider (e.g. https://s3.eu-west-1.amazonaws.com or https://<account>.r2.cloudflarestorage.com for R2). - Bucket: the name of the bucket, e.g. mikelmc-stalwart-backups. - Region: the bucket region (us-east-1 if in doubt, or your provider's region). - Access Key / Secret Key: credentials with write permission to that bucket.
- Save and test with a manual backup run (the Backups tab has a run button) before trusting the schedule.
Notes:
- The backups are stored as compressed volume archives, one per run, in the bucket. Older entries accumulate, so enable lifecycle/retention rules on the bucket (or a Dokploy retention policy if available) to prune them.
- S3 is the off-server copy: keep the local volume intact and treat the bucket as the disaster-recovery copy. Verify a restore in a scratch environment before you need it.
- If you are already doing host-level
tarsnapshots, you do not need both; pick one strategy and stick to it (Dokploy S3 backups are the more automated option and give you off-site storage out of the box).
Troubleshooting
Mail clients get "connection reset" on every port
If you migrated from the Traefik-TCP design, this is Stalwart's auto-ban having blocked the old proxy IP. With direct ports the client IP is real, so the ban targets misbehaving clients as intended. Remove any stale 10.0.1.x entry in Settings › Security › Blocked IPs (or restart the container to clear the in-memory cache) and make sure the mail Additional Port Mappings were removed from Traefik.
IMAP/Submission fail with "InvalidContentType" in the logs
Stalwart is reading a PROXY header it did not expect: proxy_protocol or overrideProxyTrustedNetworks is still enabled on a listener that is now published directly. Turn Proxy Protocol off for the mail listeners and clear their trusted networks (Step 5). The remoteIp in the error will be a proxy address instead of the client's real IP.
Ports work locally but not from the internet
Check the firewall. The mail ports are published directly by the container, so open 25, 110, 143, 465, 587, 993, 995, 4190 on the host and at your provider, and make sure nothing else (the old Traefik port mappings) is already bound to them.
Outbound mail lands in spam
- Verify SPF, DKIM and DMARC all validate with an online tester (e.g.
mail-tester.com). - Make sure the PTR (rDNS) matches the HELO hostname
mail.example.com. - Check the IP is not on any DNS blocklist.
Certificates do not update after renewal
Check the cert-sync logs and confirm the hook is executable and mounted at /hook/hook.sh. Confirm STALWART_API_TOKEN is set in the environment and that the Stalwart API is reachable from the cert-sync container. If everything looks right, trigger a manual dump by touching acme.json and watch the log.
The JMAP endpoint responds but the webmail shows CORS errors
Confirm the stalwart-cors middleware is attached to the JMAP domain in Dokploy and that its accessControlAllowOriginList contains exactly https://mail.example.com (no trailing slash, no http). Check the browser's devtools: the response should include Access-Control-Allow-Origin: https://mail.example.com and a Vary: Origin header. If the middleware is missing, create it as shown in Step 3 and attach it to the domain.
Security notes
- Never expose the admin console without HTTPS.
- Remove
STALWART_RECOVERY_ADMINfrom the environment once the permanent administrator works, it is a backdoor credential. - Limit who can reach the admin console. Because the WebUI is served through Traefik and shares the listener with JMAP, it is always reachable at
https://mail.example.com:8484/admin— do not try to "disable the HTTP listener on 8080", that would take the WebUI and JMAP offline together. Instead, restrict access to the admin console: serve it only over HTTPS (already the case), and gate it by IP allowlist (Traefik middleware or firewall) or by a VPN tunnel so only your administrators can reach it. - The Stalwart image runs as UID 2000 with minimal capabilities; keep it that way and don't add
--privileged. - Stalwart ships built-in spam/phishing filtering, greylisting, rate limiting and auto-banning. Review Settings › Spam & Phishing after setup and consider enabling greylisting.
- Keep the named volumes intact; they hold all configuration, accounts, keys and mail.
Upgrading
Because data lives in named volumes, upgrading Stalwart is mostly changing the image tag and redeploying the project in Dokploy:
sudo docker compose -f /etc/dokploy/compose/<project>/code/docker-compose.yml pull
sudo docker compose -f /etc/dokploy/compose/<project>/code/docker-compose.yml up -dbashBack up before upgrading and check the release notes for any breaking changes or required database migrations.
References
- Dokploy documentation
- Stalwart official documentation
- Stalwart Docker deployment guide
- Stalwart DNS records
- Stalwart auto-banning
- Bulwark webmail
- traefik-certs-dumper
- Stalwart source code
- Docker Compose documentation
AI-generated image disclosure
The cover image (/images/posts/stalwart-dokploy-header.webp) was generated with the assistance of an AI model (deepseek-v4-flash). In accordance with Regulation (EU) 2024/1689 (EU Artificial Intelligence Act, Article 50), this content is disclosed as AI-generated. It is an original illustration created for this article without third-party images, logos or external assets; product names (Stalwart, Dokploy, Traefik) appear descriptively and no affiliation or endorsement is implied.
I hope I did not skip any detail. Thanks for reading and sorry for the madness of this post. I hope you found it entertaining and, in some way, instructive. I did, and I felt really stupid when I realised I was not using ports while configuring ports for another service... Sorry to everyone who saw the old content O_O
