stalwart
All-in-one Mail & Collaboration server. Secure, scalable and fluent in every protocol (IMAP, JMAP, SMTP, CalDAV, CardDAV, WebDAV).
⚠️ Upgrading from a pre-1.0 deployment? This is a breaking, non-in-place change — see Upgrading from 0.x to 1.x before deploying.
- Maintainer: @dannygroenewegen
- Category: Apps
- Status: 3
- Image:
stalwartlabs/stalwart, 4 - Healthcheck: Yes
- Backups: Yes
- Email: N/A
- Tests: 0
- SSO: 1
Quick start
abra app new stalwart --secrets
abra app config <app-name> # set DOMAIN, BASE_DOMAIN
abra app deploy <app-name>
On first deploy, Stalwart generates a random admin password and prints it to logs:
abra app logs <app-name> app
Then open https://mail.example.com/admin to complete the setup wizard.
Post-deploy configuration (required)
After the setup wizard, apply these settings in the Stalwart admin UI under Network → Servuces → HTTP → General:
- Enable Obtain remote IP from Forwarded header — required so Stalwart sees real client IPs from Traefik
Ports
| Port | Mode | Protocol | Purpose |
|---|---|---|---|
| 25 | Host | SMTP | Inbound mail from other servers |
| 465 | Host | SMTPS | Client mail submission (implicit TLS) |
| 587 | Host | Submission | Client mail submission (STARTTLS) |
| 993 | Host | IMAPS | Client mail retrieval (implicit TLS) |
| 443 | Traefik | HTTPS | Admin UI, JMAP, autodiscover, webmail |
Mail ports are exposed directly rather than via Traefik: 25/587 use STARTTLS so Traefik could only blind-forward them anyway, and 465/993 use implicit TLS which Stalwart terminates itself so it can manage its own certificates for TLSA/ACME. Only HTTP(S) traffic goes through Traefik.
Bulwark webmail (optional)
To enable the Bulwark webmail client at webmail.example.com:
- Add a DNS record:
webmail.example.comCNAME →mail.example.com - Uncomment the three Bulwark lines in
.env:COMPOSE_FILE="compose.yml:compose.bulwark.yml" WEBMAIL_DOMAIN=webmail.example.com SECRET_SESSION_SEC_VERSION=v1 - Generate the session secret:
abra app secret generate <app-name> - Redeploy:
abra app deploy <app-name>
When Bulwark is active, https://mail.example.com/ redirects to https://webmail.example.com/. The admin interface remains at https://mail.example.com/admin.
Upgrading from 0.x to 1.x
Stalwart 1.0 introduced a new database layout. A v0.16.x deployment cannot be upgraded in place — the 1.x binary will not open a v0.16 store. Migrating requires Stalwart's own stalwart-migrate tool (against Stalwart 0.16.27), copying into a new, empty data store before deploying this recipe version. Full official guide: https://stalw.art/docs/migration/upgrade-0-16/quick-guide/
Before upgrading, read Stalwart's v1.0.0 release notes and the full migration guide. There have been breaking changes beyond what's summarized here (e.g. in how OIDC is handled), and your specific deployment may need attention the steps below don't cover.
Below is a quick summary for a typical single-node deployment already on 0.16.27, with a RocksDB datastore. Replace <stack_name> with your app's actual swarm stack name (docker volume ls will show it as the prefix on your _config/_data volumes).
1. Create scratch volumes and a minimal target config. The migration tool needs an empty target store to write into, plus a state directory for its own progress/reports. It reads a config.json describing the target store, but never creates one itself:
docker volume create <stack_name>_config_v1
docker volume create <stack_name>_data_v1
docker volume create <stack_name>_migrate_state
docker run --rm -v <stack_name>_config_v1:/etc/stalwart-v1 alpine \
sh -c 'echo "{\"@type\": \"RocksDb\", \"path\": \"/var/lib/stalwart-v1/\"}" > /etc/stalwart-v1/config.json'
2. Review the settings conversion (interactive, needs a real terminal). This only reads the source, nothing is touched on the live deployment:
docker run --rm -it \
-v <stack_name>_config:/etc/stalwart:ro \
-v <stack_name>_data:/var/lib/stalwart:ro \
-v <stack_name>_config_v1:/etc/stalwart-v1 \
-v <stack_name>_data_v1:/var/lib/stalwart-v1 \
-v <stack_name>_migrate_state:/var/lib/stalwart-migrate \
stalwartlabs/stalwart-migrate:1.0 \
prepare --source /etc/stalwart/config.json --state /var/lib/stalwart-migrate
# review the result:
docker run --rm -v <stack_name>_migrate_state:/state alpine cat /state/prepare-report.txt
3. Copy the bulk of the data while the old deployment keeps serving mail. This can take a while for a large mailbox history; safe to re-run as many times as needed, each time copying only the delta since the last pass. Run it once more right before the actual upgrade:
docker run --rm -it \
-v <stack_name>_config:/etc/stalwart:ro \
-v <stack_name>_data:/var/lib/stalwart:ro \
-v <stack_name>_config_v1:/etc/stalwart-v1 \
-v <stack_name>_data_v1:/var/lib/stalwart-v1 \
-v <stack_name>_migrate_state:/var/lib/stalwart-migrate \
stalwartlabs/stalwart-migrate:1.0 \
run \
--source /etc/stalwart/config.json --target /etc/stalwart-v1/config.json \
--state /var/lib/stalwart-migrate \
--target-path-map /etc/stalwart=/etc/stalwart-v1 \
--target-path-map /var/lib/stalwart=/var/lib/stalwart-v1
4. Upgrade, downtime starts here. Undeploy the running app, then copy the final delta and verify:
abra app undeploy <app-name>
docker run --rm -it \
-v <stack_name>_config:/etc/stalwart:ro \
-v <stack_name>_data:/var/lib/stalwart:ro \
-v <stack_name>_config_v1:/etc/stalwart-v1 \
-v <stack_name>_data_v1:/var/lib/stalwart-v1 \
-v <stack_name>_migrate_state:/var/lib/stalwart-migrate \
stalwartlabs/stalwart-migrate:1.0 \
run --final \
--source /etc/stalwart/config.json --target /etc/stalwart-v1/config.json \
--state /var/lib/stalwart-migrate \
--target-path-map /etc/stalwart=/etc/stalwart-v1 \
--target-path-map /var/lib/stalwart=/var/lib/stalwart-v1
# (will ask you to type "yes" to confirm the old server is actually stopped)
docker run --rm \
-v <stack_name>_migrate_state:/var/lib/stalwart-migrate \
stalwartlabs/stalwart-migrate:1.0 \
report --state /var/lib/stalwart-migrate --severity error
# confirm 0 rows before continuing
5. Swap the migrated data into this recipe's expected volume names. Docker volumes can't be renamed, so this is a plain file copy via a throwaway container. Back up the originals first.
docker run --rm -v <stack_name>_config:/from -v <stack_name>_config_pre_1_0:/to alpine sh -c 'cp -a /from/. /to/.'
docker run --rm -v <stack_name>_data:/from -v <stack_name>_data_pre_1_0:/to alpine sh -c 'cp -a /from/. /to/.'
docker volume rm <stack_name>_config <stack_name>_data
docker volume create <stack_name>_config
docker volume create <stack_name>_data
docker run --rm -v <stack_name>_config_v1:/from -v <stack_name>_config:/to alpine sh -c 'cp -a /from/. /to/.'
docker run --rm -v <stack_name>_data_v1:/from -v <stack_name>_data:/to alpine sh -c 'cp -a /from/. /to/.'
6. Fix the config.json path. --target-path-map rewrites paths inside the data store's registry, not this config file. It still says /var/lib/stalwart-v1/ from step 1. Point it at this recipe's real mount path, or the 1.x server won't find its own data store at startup:
docker run --rm -v <stack_name>_config:/v alpine \
sh -c 'echo "{\"@type\": \"RocksDb\", \"path\": \"/var/lib/stalwart/\"}" > /v/config.json'
7. Deploy the Stalwart v1.1 recipe version, then restart once with STALWART_UPDATE_ROLE_PERMISSIONS=true set (then remove it and restart again) Upgraded servers don't automatically get default-role permissions added since v1.0.0 otherwise.
8. If you use an external OIDC provider (Rauthy, Keycloak, Authentik, etc.) for WebUI/account login: re-set the Application's oauthClientId to your existing client, or let it fall back to Client ID Metadata Document discovery if your provider supports draft-ietf-oauth-client-id-metadata-document.
9. If running Bulwark webmail with SSO against an external OIDC provider: grant that provider's client one of Stalwart's urn:stalwart:oauth:scope:{security,settings,full} scopes (added in Stalwart 1.0.3). Without it, login still works but Bulwark can't manage app passwords, API keys, or account settings.
Backup
Backupbot backs up both volumes:
/etc/stalwart- server configuration/var/lib/stalwart- RocksDB mail data (hot copy; RocksDB's WAL ensures the backup is recoverable on restore)