Containerized deployment architecture for Stalwart Mail Server using PostgreSQL for persistent storage, Valkey for in-memory caching, and Angie as the perimeter reverse proxy.
- Scratch Runtime: Built
FROM scratchwith CA certificates and no shell, package manager, or system utilities. Theserverimage addsstalwartalong with two static Go binaries:init(loads optional recovery secrets and bridges loopback Valkey connections to a UNIX domain socket before starting the server) andprobe(queries/healthz/livefor container healthchecks). Thecliimage adds onlystalwart-cli. - Socket-Only Database & Cache IPC: Both PostgreSQL and Valkey run with networking completely disabled. Each service communicates over its own isolated, in-memory
tmpfsUNIX domain socket restricted to the unprivileged container user, preventing cross-service socket access. - Least-Privilege Execution: Services run as an unprivileged host user with read-only root filesystems, privilege escalation disabled, and all Linux capabilities dropped—except
NET_BIND_SERVICEon the mail server for ports25,465, and993. - File-Backed Secret Injection: Database passwords, recovery accounts, DKIM private keys, and DNS API tokens are mounted as read-only Docker Secrets (
/run/secrets/*), keeping plaintext secrets out of.envfiles and Compose manifests. - Locked HTTP Perimeter: Edge Angie exposes only client discovery and MTA-STS endpoints, returning
404for/adminand/accountby default. WebAdmin is accessed over an SSH tunnel (127.0.0.1:18080:8080) or a private VPN interface (<VPN_IP>:18080:8080). - On-Demand CLI:
stalwart-cliis packaged into a separate scratch image underprofiles: [tools]and shares the mail server's network namespace on demand, keeping administrative tooling out of the runtime container.
Directory Structure
Production directory layout on the host (/home/stalwart):
├── docker-compose.yaml # Production deployment manifest
├── .env # Host infrastructure variables (UID, GID, HOST_IP, image versions)
├── config/ # Service configuration
│ ├── stalwart/
│ │ └── config.json # Bootstrap-generated store connection config
│ └── valkey/
│ └── valkey.conf # In-memory Valkey configuration
├── secrets/ # Docker secrets directory
│ ├── db_name.txt # PostgreSQL database name
│ ├── db_user.txt # PostgreSQL username
│ ├── db_password.txt # PostgreSQL password
│ ├── stalwart_recovery_user.txt # Recovery administrator username
│ ├── stalwart_recovery_password.txt # Recovery administrator password
│ ├── cf_api_token.txt # Optional: DNS provider API token for ACME DNS-01
│ ├── dkim_ed25519.key # Optional: Ed25519 DKIM private key
│ └── dkim_rsa.key # Optional: RSA-2048 DKIM private key
├── postgres/ # Persistent PostgreSQL data directory
├── data/ # Stalwart blob storage
└── logs/ # Stalwart log directory (consumed by host CrowdSec)
Deployment & Setup
- Docker Engine & Compose: Ensure Docker Engine and the Docker Compose plugin are installed on the host. Follow the official installation guide for Ubuntu.
- External Gateway Network: The stack communicates with the host's Edge reverse proxy over a shared Docker network named
frontend_gateway(declared asexternal: true). This network is provisioned by the angie-docker-compose stack. If deploying standalone, create it manually:
docker network create --subnet=172.20.0.0/16 frontend_gatewayChoose a dedicated, unprivileged numeric ID unique to this service on your host and verify that it is not already in use by another user or group:
APP_UID=<CHOSEN_UID>
getent passwd ${APP_UID}
getent group ${APP_UID}Important: Both commands must return empty output. Each containerized service must have its own dedicated unprivileged user and group to enforce strict host DAC privilege separation between different stacks.
Create an unprivileged system account with a matching user-group (-U) and disabled login shell:
sudo useradd -m -d /home/stalwart -s /usr/sbin/nologin -u ${APP_UID} -U stalwartsudo mkdir -p /home/stalwart/{config/{stalwart,valkey},data,logs,postgres,secrets}
sudo chown root:stalwart /home/stalwart/secrets
sudo chmod 0750 /home/stalwart/secrets
sudo chown stalwart:stalwart /home/stalwart/{config/valkey,data,logs,postgres}
sudo chmod 0700 /home/stalwart/{config/stalwart,data,logs,postgres}Log Access for Non-Root Services (Optional): By default,
logs/is restricted to0700. If an external unprivileged service (such as CrowdSec running under a non-root account) requires access to parse application logs, grant read permissions to the directory and log files:
sudo chmod 0755 /home/stalwart/logs
sudo chmod 0644 /home/stalwart/logs/*Install the required tools:
sudo apt update && sudo apt install -y pwgen opensslDatabase and recovery administrator credentials:
Initialize secret files with strict DAC permissions before writing:
sudo touch /home/stalwart/secrets/{db_name,db_user,db_password,stalwart_recovery_user,stalwart_recovery_password}.txt
sudo chown root:stalwart /home/stalwart/secrets/{db_name,db_user,db_password,stalwart_recovery_user,stalwart_recovery_password}.txt
sudo chmod 0440 /home/stalwart/secrets/{db_name,db_user,db_password,stalwart_recovery_user,stalwart_recovery_password}.txt
printf "db_%s" "$(pwgen -s -A 6 1)" | sudo tee /home/stalwart/secrets/db_name.txt > /dev/null
printf "u_%s" "$(pwgen -s -A 6 1)" | sudo tee /home/stalwart/secrets/db_user.txt > /dev/null
pwgen -s 64 1 | tr -d '\n' | sudo tee /home/stalwart/secrets/db_password.txt > /dev/null
printf "r_%s" "$(pwgen -s -A 6 1)" | sudo tee /home/stalwart/secrets/stalwart_recovery_user.txt > /dev/null
pwgen -s 64 1 | tr -d '\n' | sudo tee /home/stalwart/secrets/stalwart_recovery_password.txt > /dev/nullNOTE:
stalwart_recovery_user.txtandstalwart_recovery_password.txtare required for initial bootstrap. Although the official Stalwart documentation advises disabling the recovery account in production, leaving it enabled in this stack is safe if desired:
- The credentials are high-entropy random strings stored in
0440host files owned byroot:stalwart, mounted read-only via Docker Secrets, and loaded at startup by theinitbinary without appearing indocker-compose.yamlor.env.- Public access to
/adminand/accountis blocked (404) by default in Edge Angie (the WebUI location block is commented out). WebAdmin is only reachable over an SSH tunnel (127.0.0.1:18080:8080) or a private VPN interface (<VPN_IP>:18080:8080).Both recovery secrets are commented out by default in
docker-compose.yamland can be enabled permanently or on demand.
Optional secrets (DKIM keys & ACME DNS API token):
Stalwart can generate DKIM keys and manage ACME certificates directly in its database. Alternatively, you can provision keys and API tokens on the host as read-only Docker Secrets (/run/secrets/*)—creating as many domain keys as needed—and select Secret read from file in WebAdmin:
sudo openssl genpkey -algorithm ed25519 -out /home/stalwart/secrets/dkim_ed25519.key
sudo openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out /home/stalwart/secrets/dkim_rsa.key
sudo chown root:stalwart /home/stalwart/secrets/dkim_*.key
sudo chmod 0440 /home/stalwart/secrets/dkim_*.keysudo touch /home/stalwart/secrets/cf_api_token.txt
sudo chown root:stalwart /home/stalwart/secrets/cf_api_token.txt
sudo chmod 0440 /home/stalwart/secrets/cf_api_token.txt
sudo nano /home/stalwart/secrets/cf_api_token.txtREPO="https://raw.githubusercontent.com/webstudiobond/stalwart-docker/main"
sudo -u stalwart curl -fsSL ${REPO}/config/valkey/valkey.conf -o /home/stalwart/config/valkey/valkey.conf
sudo curl -fsSL ${REPO}/docker-compose.yaml -o /home/stalwart/docker-compose.yaml
sudo curl -fsSL ${REPO}/examples/.env.example -o /home/stalwart/.env
sudo chown root:root /home/stalwart/{docker-compose.yaml,.env}
sudo chmod 0600 /home/stalwart/{docker-compose.yaml,.env}sed -i "s/^APP_UID=.*/APP_UID=${APP_UID}/" /home/stalwart/.env
sed -i "s/^APP_GID=.*/APP_GID=${APP_UID}/" /home/stalwart/.envIdentify your host's public IP address:
ip --br aUpdate /home/stalwart/.env:
- Set
HOST_IPto the host's dedicated public IP address so Stalwart binds its public mail ports (25,465,993) strictly to that network interface. Never use0.0.0.0. - IPv6 Support (Optional): If IPv6 connectivity is required, define
HOST_IP6in/home/stalwart/.envwith your host's dedicated public IPv6 address, and add the corresponding bracketed port mappings (e.g.,"[${HOST_IP6}]:25:25","[${HOST_IP6}]:465:465","[${HOST_IP6}]:993:993") underports:indocker-compose.yaml.
Security Note:
HOST_IPintentionally defaults to127.0.0.1in.env.examplefor initial staging so automated scanners and malicious bots cannot probe or attack the mail server while the administrator completes initial configuration. You may keep127.0.0.1during bootstrap, but you must replace it with the host's dedicated public IP once setup is finalized to receive external mail.
sudo nano /home/stalwart/.envInitial Configuration (Bootstrap)
Stalwart stores its operational configuration, accounts, and domains inside PostgreSQL. Initial setup is performed once via a temporary bootstrap container with outbound network access so Stalwart can download its WebUI asset bundle and write the store connection config to /home/stalwart/config/stalwart/config.json.
sudo docker compose -f /home/stalwart/docker-compose.yaml up -d postgres valkey
sudo docker compose -f /home/stalwart/docker-compose.yaml psPull the server image and run a temporary container bound to 127.0.0.1:18080:
sudo docker compose -f /home/stalwart/docker-compose.yaml pull stalwart
APP_UID="$(id -u stalwart)"
APP_GID="$(id -g stalwart)"
sudo docker run --rm -d \
--name stalwart_bootstrap \
--network bridge \
--user "${APP_UID}:${APP_GID}" \
--tmpfs /tmp:mode=1777,noexec,nosuid,nodev,size=64m \
--tmpfs /run:mode=1777,noexec,nosuid,nodev,size=16m \
-v stalwart_postgres_socket:/var/run/postgresql \
-v stalwart_valkey_socket:/var/run/valkey \
-v "/home/stalwart/config/stalwart:/etc/stalwart:rw" \
-v "/home/stalwart/data:/var/lib/stalwart:rw" \
-v "/home/stalwart/logs:/var/log/stalwart:rw" \
-v "/home/stalwart/secrets/db_name.txt:/run/secrets/db_name:ro" \
-v "/home/stalwart/secrets/db_user.txt:/run/secrets/db_user:ro" \
-v "/home/stalwart/secrets/db_password.txt:/run/secrets/db_password:ro" \
-v "/home/stalwart/secrets/stalwart_recovery_user.txt:/run/secrets/stalwart_recovery_user:ro" \
-v "/home/stalwart/secrets/stalwart_recovery_password.txt:/run/secrets/stalwart_recovery_password:ro" \
-p 127.0.0.1:18080:8080 \
ghcr.io/webstudiobond/stalwart-docker:latest
sudo docker logs -f stalwart_bootstrap- Access Setup Wizard: Forward port
18080over SSH from your workstation (ssh -N -L 18080:127.0.0.1:18080 user@server) and navigate tohttp://127.0.0.1:18080/admin. - Authenticate: Sign in using the credentials from
secrets/stalwart_recovery_user.txtandsecrets/stalwart_recovery_password.txt. - Server Identity: Set Server Hostname to your public mail FQDN (e.g.,
mail.example.com) and Default Email Domain to your primary domain (e.g.,example.com). Disable automatic TLS certificate retrieval (configure DNS-01 ACME or external certificates after setup). Enable email signing key generation to auto-generate DKIM keys in the database, or disable if providing external key files via Docker Secrets. - Data Store: Select
PostgreSQL. Set Host to/var/run/postgresql, Port to5432(used in the UNIX socket filename.s.PGSQL.5432), Database to the value fromsecrets/db_name.txt, and Username to the value fromsecrets/db_user.txt. Select Secret read from file for Password with path/run/secrets/db_password. Disable TLS and allow invalid certs. Set Max Connections to10(Fastrecycling). - Attachment & File Storage: Select
FileSystem, set path to/var/lib/stalwart, and choose Nested Depth2. - Full-Text Search Index: Keep the default (
PostgreSQL). - Cache & Temporary Data: Select standalone
Redis/Valkey, set URL toredis://127.0.0.1:6379, and keep default timeouts and connection limits. - Account Directory: Select
Internal. - Log Destination: Select
File, set path to/var/log/stalwart, prefixstalwart.log, daily rotation, ANSI colors disabled, tracer enabled, and levelInfo. Set Filtering Mode toExclude the specified eventsand exclude noisy background events (Metric store,Metrics collected,Metrics pushed,Task queued for processing,Task scheduled for future execution,Search index updated). - Automatic DNS Management: Select manual (or configure DNS provider integration later).
- Administrator Account: The wizard automatically generates a default
admin@<domain>mailbox and displays its password once—record it if you plan to keep the account. Becauseadmin@<domain>is a predictable target for brute-force and credential-stuffing attacks, log back in with yourstalwart_recovery_usercredentials after setup, delete the auto-generatedadmin@<domain>account, and create accounts with non-predictable identifiers instead. - Terminate Bootstrap Container: Stop log following (
Ctrl+C) and terminate the temporary container:
sudo docker stop stalwart_bootstrapThe bootstrap container must be stopped before locking its writable configuration mount. Make the generated file readable, but not writable, by the service account:
sudo chown root:stalwart /home/stalwart/config/stalwart/config.json
sudo chmod 0440 /home/stalwart/config/stalwart/config.jsonOperation & Maintenance
Start all production services in the background:
sudo docker compose -f /home/stalwart/docker-compose.yaml up -dInspect container status, healthcheck states, and resource usage:
sudo docker compose -f /home/stalwart/docker-compose.yaml ps
sudo docker stats --no-stream stalwart-mail stalwart-db stalwart-cacheFollow real-time application and database logs:
# Follow all stack logs
sudo docker compose -f /home/stalwart/docker-compose.yaml logs -f
# Follow mail server logs only
sudo docker compose -f /home/stalwart/docker-compose.yaml logs -f stalwartPull updated container images and recreate services with minimal downtime:
sudo docker compose -f /home/stalwart/docker-compose.yaml pull
sudo docker compose -f /home/stalwart/docker-compose.yaml up -dGracefully stop running containers without removing them:
sudo docker compose -f /home/stalwart/docker-compose.yaml stopStop and remove containers and internal networks (persistent data in data/, postgres/, and logs/ is preserved):
sudo docker compose -f /home/stalwart/docker-compose.yaml downPost-Bootstrap Configuration & Recommendations
Stalwart includes a built-in auto-ban and rate-limiting engine. Keeping it active alongside host-level CrowdSec provides defense in depth: CrowdSec tails /home/stalwart/logs/stalwart.log* and escalates protocol errors, authentication failures, and Stalwart's own block events into host firewall bans.
To ensure all security-relevant events are written at Info level for CrowdSec scenarios, configure Custom event levels in WebAdmin (Settings › Telemetry › Event Levels → /account/Settings/x:EventTracingLevel) with level Info for:
POP3 error occurredIMAP error occurredTLS handshake errorConcurrent request limit reachedCommand not implementedSyntax errorInvalid commandHTTP error occurredAuthentication failed
In WebAdmin (Settings › Security › Allowed IPs), optionally whitelist internal infrastructure addresses to ensure healthcheck probes and host-forwarded administrative sessions are never throttled or blocked by internal rate limiters:
127.0.0.1(healthcheck): Container loopback used by/usr/local/bin/probe(http://127.0.0.1:8080/healthz/live).172.20.0.1(frontend_gateway): Host bridge gateway IP seen by Stalwart when accessing the published WebAdmin port (18080:8080) from the host via SSH port forwarding or a VPN interface.
Provisioning keys via Docker Secrets keeps private keys out of the PostgreSQL database (0440 host files owned by root:stalwart mounted on read-only tmpfs) and allows publishing strict DNS records (t=s) rather than Stalwart's permissive defaults. Because DKIM2 reuses standard v=DKIM1 _domainkey DNS TXT records and has cryptographic domain separation from DKIM1, the same key pairs and selectors can safely sign both protocols simultaneously.
-
Mount secret files: Uncomment
dkim_ed25519_keyanddkim_rsa_key(and any additional domain keys) under both thestalwartservicesecrets:section and the rootsecrets:block indocker-compose.yaml, then recreate the container (sudo docker compose -f /home/stalwart/docker-compose.yaml up -d). -
Extract public keys & publish strict DNS TXT records:
# Extract base64 Ed25519 public key sudo openssl pkey -in /home/stalwart/secrets/dkim_ed25519.key -pubout -outform DER | tail -c 32 | openssl base64 -A && echo # Extract base64 RSA-2048 public key sudo openssl rsa -in /home/stalwart/secrets/dkim_rsa.key -pubout -outform DER 2>/dev/null | openssl base64 -A && echo
Publish the two TXT records in DNS (
t=senforces strict domain alignment in both DKIM1 and DKIM2 by forbidding subdomain signing;h=sha256; s=emailharden DKIM1 and are ignored by DKIM2 verifiers):mail-ed25519._domainkey.example.com. IN TXT "v=DKIM1; k=ed25519; h=sha256; s=email; t=s; p=<ED25519_PUBLIC_KEY>" mail-rsa._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; h=sha256; s=email; t=s; p=<RSA_PUBLIC_KEY>"Warning: Strict constraints such as
t=s,h=sha256, ands=email(as well as DKIM2donotmodify/donotexplodeflags below) may not fit every mail topology—for example,t=sinvalidates signatures if a parent-domain key signs messages for subdomains or uses subdomaini=identities. Always review RFC 6376 § 3.6.1 and test verification across your own mail flows before deploying strict parameters in production. -
Configure DKIM1 signatures (
RFC 6376/RFC 8463): In WebAdmin (Management › Domains › DKIM Signatures →/account/Management/x:DkimSignature/new), create dual DKIM1 signatures:-
DKIM1 (Ed25519 SHA-256): Selectormail-ed25519, private key set to Secret read from file →/run/secrets/dkim_ed25519_key. -
DKIM1 (RSA SHA-256): Selectormail-rsa, private key set to Secret read from file →/run/secrets/dkim_rsa_key. -
Per RFC 6376 § 5.4.1 (Recommended Signature Content), extend the signed header list on both DKIM1 signatures beyond Stalwart's defaults:
Default headers:
Date From Message-ID Subject ToAdditional headers to include:
Cc Reply-To In-Reply-To References MIME-Version Content-Type Content-Transfer-Encoding Resent-Date Resent-From Resent-To Resent-Cc
-
-
Configure DKIM2 signatures (
draft-ietf-dkim-dkim2-spec): In the same DKIM Signatures section, create two additional signatures reusing the same selectors and secret files:DKIM2 (Ed25519 SHA-256): Selectormail-ed25519, private key set to Secret read from file →/run/secrets/dkim_ed25519_key.DKIM2 (RSA SHA-256): Selectormail-rsa, private key set to Secret read from file →/run/secrets/dkim_rsa_key.- DKIM2 hashes all non-trace message headers automatically by specification (no manual header list is required). Under Signing Flags, enable all three strict delivery constraints:
Request that the message not be modified in transit(donotmodify)Request that the message not be delivered to more than one recipient(donotexplode)Request feedback about how the message is handled during delivery(feedback)
To obtain TLS certificates for mail protocols (25, 465, 993) via DNS-01 without exposing API credentials in plaintext—for example, if you use Cloudflare as your DNS provider (for other DNS providers, rename or add the corresponding secret files in docker-compose.yaml):
- Uncomment
cf_api_tokenindocker-compose.yamland runsudo docker compose -f /home/stalwart/docker-compose.yaml up -d. - In WebAdmin (Settings › Server › TLS › ACME Providers), select Secret read from file for the provider token and specify
/run/secrets/cf_api_token.
In docker-compose.yaml, optional listeners are commented out by default:
${HOST_IP}:587:587(STARTTLS Submission): Disabled in favor of Implicit TLS on port465. Uncomment only if legacy clients require port587.127.0.0.1:18080:8080(Private WebAdmin): Exposes the HTTP management interface on loopback for SSH port forwarding (ssh -N -L 18080:127.0.0.1:18080 user@server) when public WebUI access is blocked at the Edge proxy. For direct access over a VPN (e.g., WireGuard), replace127.0.0.1with the host's internal VPN interface IP (e.g.,10.0.0.1:18080:8080). Note that accessing WebAdmin over plain HTTP requires pre-registering anOAuthClient(see Stalwart CLI).127.0.0.1:4190:4190(ManageSieve): Bound to localhost by default; replace127.0.0.1with a private VPN IP or uncomment as needed if desktop mail clients require direct ManageSieve access.
External Angie
The stalwart container joins the external frontend_gateway network (172.20.0.0/16) without publishing HTTP ports on the host. An external Edge Angie instance terminates HTTPS/TLS, manages HTTP ACME certificates, and restricts public HTTP exposure strictly to required discovery endpoints.
Production-hardened virtual host templates for Stalwart are maintained in the angie-docker-compose repository under data/conf.d/domains/:
stalwart.conf— Primary mail host (mail.example.com). Exposes client autodiscovery (/autodiscover/*,/.well-known/user-agent-configuration.json) and JMAP discovery (/.well-known/jmap). Public access to the WebUI (/admin,/account) is locked (404) by default, with an optional commented location block if public WebUI access is required.autoconfig.conf— Mozilla Autoconfig virtual host (autoconfig.example.com) for Thunderbird and K-9 Mail (/mail/config-v1.1.xml,/.well-known/autoconfig/mail/config-v1.1.xml,/.well-known/mail-v1.xml,/.well-known/user-agent-configuration.json).autodiscover.conf— Microsoft Autodiscover virtual host (autodiscover.example.com) for Outlook (/autodiscover/autodiscover.xml,/autodiscover/autodiscover.json,/.well-known/user-agent-configuration.json).mta-sts.conf— SMTP MTA-STS policy virtual host (mta-sts.example, RFC 8461) exposing/.well-known/mta-sts.txt.
Download the required templates into your Edge Angie domains directory:
DATA_ANGIE="/home/angie/data"
ANGIE_REPO="https://raw.githubusercontent.com/webstudiobond/angie-docker-compose/main/data/conf.d/domains"
for conf in stalwart autoconfig autodiscover mta-sts; do
curl -fsSL "${ANGIE_REPO}/${conf}.conf" -o "${DATA_ANGIE}/conf.d/domains/${conf}.conf"
doneOpen each file to customize domain names, upstream definitions, and ACME client identifiers for your environment before reloading Angie:
nano "${DATA_ANGIE}/conf.d/domains/stalwart.conf"
nano "${DATA_ANGIE}/conf.d/domains/autoconfig.conf"
nano "${DATA_ANGIE}/conf.d/domains/autodiscover.conf"
nano "${DATA_ANGIE}/conf.d/domains/mta-sts.conf"Permissions & Ownership
The stack enforces strict host-level privilege separation across three ownership tiers so that even in the event of a container compromise (stalwart), the process cannot modify deployment manifests, service configurations, or secret files:
root:root(0600):docker-compose.yamland.env(accessible exclusively to host root).root:stalwart(0750/0440):/home/stalwartbase directory (0750),config/directories (0750),secrets/directory (0750), configuration files (config.json,valkey.confat0440), and secret files (*.txt,*.keyat0440; read-only to containers, immutable to runtime processes).stalwart:stalwart(0700/0600):data/(blob storage),postgres/(database cluster), andlogs/(application logs). Managed with strict DAC: directories0700, files0600.
| Host path | Owner | Mode | Reason |
|---|---|---|---|
/home/stalwart |
root:stalwart |
0750 |
Allow service traversal without access for other users |
docker-compose.yaml, .env |
root:root |
0600 |
Host-only manifests and environment settings |
config/ directories |
root:stalwart |
0750 |
Prevent service-account modification |
config/stalwart/config.json, config/valkey/valkey.conf |
root:stalwart |
0440 |
Read-only service configuration |
secrets/ directory |
root:stalwart |
0750 |
Traverse-only access for the service group |
secrets/* |
root:stalwart |
0440 |
Read-only to the service group |
data/, postgres/ |
stalwart:stalwart |
0700 |
Private writable runtime storage |
logs/ directory |
stalwart:stalwart |
0700 |
Writable by Stalwart, readable by host root CrowdSec |
logs/ files |
stalwart:stalwart |
0600 |
Writable by Stalwart, readable by host root CrowdSec |
Use this self-contained block to apply or restore canonical ownership and permissions on an existing or migrated installation without stopping the stack:
sudo chown root:stalwart /home/stalwart
sudo chmod 0750 /home/stalwart
sudo chown root:root /home/stalwart/{docker-compose.yaml,.env}
sudo chmod 0600 /home/stalwart/{docker-compose.yaml,.env}
sudo chown -R root:stalwart /home/stalwart/{config,secrets}
sudo find /home/stalwart/{config,secrets} -type d -exec chmod 0750 {} +
sudo find /home/stalwart/{config,secrets} -type f -exec chmod 0440 {} +
sudo chown -R stalwart:stalwart /home/stalwart/{data,logs,postgres}
sudo find /home/stalwart/{data,logs,postgres} -type d -exec chmod 0700 {} +
sudo find /home/stalwart/{data,logs,postgres} -type f -exec chmod 0600 {} +Log Access for Non-Root Services (Optional): By default,
logs/is restricted to0700. If an external unprivileged service (such as CrowdSec running under a non-root account) requires access to parse application logs, grant read permissions to the directory and log files:
sudo chmod 0755 /home/stalwart/logs
sudo chmod 0644 /home/stalwart/logs/*Client Configuration (Apple Mail Profile)
Because Apple Mail on macOS and iOS does not support standard IMAP/SMTP Autoconfig or Autodiscover, use examples/email.mobileconfig.example to provision IMAP (993, Implicit TLS) and SMTP (465, Implicit TLS) automatically.
By default, the <key>IncomingPassword</key> block in the template is commented out so macOS/iOS prompts the user for the password interactively during installation and stores it directly in the Apple Keychain. You may uncomment this block to embed the password inside the profile; however, because .mobileconfig files store embedded passwords in plaintext, any profile containing credentials must be transferred strictly over encrypted channels and deleted immediately after installation.
Generate a customized .mobileconfig profile (including fresh PayloadUUID values via uuidgen):
EMAIL="user@example.com"
MAIL_HOST="mail.example.com"
ORG_DOMAIN="example.com"
UUID_ACCOUNT="$(uuidgen)"
UUID_PROFILE="$(uuidgen)"
curl -fsSL https://raw.githubusercontent.com/webstudiobond/stalwart-docker/main/examples/email.mobileconfig.example \
-o "${EMAIL}.mobileconfig"
sed -i \
-e "s|info@example.org|${EMAIL}|g" \
-e "s|mail.example.com|${MAIL_HOST}|g" \
-e "s|example.org|${ORG_DOMAIN}|g" \
-e "s|5E0CFDD5-49CD-45CF-AE90-F0E3140A581C|${UUID_ACCOUNT}|g" \
-e "s|817768DA-0EE0-4436-87B5-B8ACC2FBCAD6|${UUID_PROFILE}|g" \
"${EMAIL}.mobileconfig"TIP:
- Always generate unique
PayloadUUIDvalues: You must replace bothPayloadUUIDplaceholders with freshly generated UUIDs (uuidgen) for every profile you create—never reuse the static template UUIDs.- By default, the example profile includes only IMAP/SMTP mail settings (
com.apple.mail.managed). Refer to Apple's Profile-Specific Payload Keys documentation if you wish to extendPayloadContentwith CalDAV (com.apple.caldav.account), CardDAV (com.apple.carddav.account), or other payloads supported by Stalwart (and ensure the corresponding routes are enabled in Edge Angie).
Stalwart CLI
stalwart-cli runs as an on-demand container under profiles: [tools] and shares the stalwart container's network namespace (network_mode: "service:stalwart").
Authenticate interactively with --user <ADMIN_USER> (either a database administrator account or the recovery administrator username when stalwart_recovery_user / stalwart_recovery_password are enabled in docker-compose.yaml); stalwart-cli prompts for the password interactively via TTY so credentials are never exposed in shell history, process arguments, or container environment inspection.
Note that Domain, Account, Application, OAuthClient, and QueueMessage below are literal JMAP schema object types (not placeholders—query Domain lists all configured domains on the server). Because /home/stalwart/docker-compose.yaml and .env are restricted to 0600 root:root, standalone commands require sudo:
# List all available configuration object types (or inspect a specific schema, e.g. 'describe Account')
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> describe
# List all configured mail domains
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> query Domain
# List all accounts
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> query Account
# Inspect the outbound mail queue
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> query QueueMessage
# List web applications and inspect their bundle URLs
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> query Application
# Update WebUI application bundle URL (e.g. to release channel v2)
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> update Application <APPLICATION_ID> --field resourceUrl=https://github.com/stalwartlabs/webui/releases/download/v2/webui.zip
# List registered OAuth clients
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> query OAuthClientTIP: When the
stalwartcontainer is already running,--no-depsskips dependency checks and executes commands immediately.
When accessing WebAdmin over plain HTTP (127.0.0.1:18080 via SSH tunnel or <VPN_IP>:18080 via WireGuard), Stalwart rejects dynamic client registration with Unknown client id. Register an explicit OAuthClient in the database to authorize private HTTP access:
For SSH port forwarding loopback (127.0.0.1:18080):
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> create OAuthClient --json '{
"clientId": "http://127.0.0.1:18080/account/oauth-client.json",
"description": "Stalwart WebAdmin (SSH Tunnel)",
"redirectUris": {
"http://127.0.0.1:18080/account/oauth/callback": true,
"http://127.0.0.1:18080/admin/oauth/callback": true
}
}'For private VPN / WireGuard access (<VPN_IP>:18080):
Replace <VPN_IP> and <PORT> with your dedicated internal VPN interface address and management port:
sudo docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli --user <ADMIN_USER> create OAuthClient --json '{
"clientId": "http://<VPN_IP>:<PORT>/account/oauth-client.json",
"description": "Stalwart WebAdmin (WireGuard)",
"redirectUris": {
"http://<VPN_IP>:<PORT>/account/oauth/callback": true,
"http://<VPN_IP>:<PORT>/admin/oauth/callback": true
}
}'Once registered, navigate to http://127.0.0.1:18080/admin (or http://<VPN_IP>:<PORT>/admin), sign in with your administrator or recovery credentials, and click Allow on the authorization consent screen.
Because sudo cannot be embedded inside .bashrc functions, this helper is designed for use exclusively under root (sudo -i). Add the helper function to /root/.bashrc:
stalwart_cli() {
docker compose -f /home/stalwart/docker-compose.yaml run --rm --no-deps stalwart-cli "$@"
}source ~/.bashrc
stalwart_cli --user <ADMIN_USER> describe
stalwart_cli --user <ADMIN_USER> query Domain
stalwart_cli --user <ADMIN_USER> query Account
stalwart_cli --user <ADMIN_USER> query Application
stalwart_cli --user <ADMIN_USER> query OAuthClient
stalwart_cli --user <ADMIN_USER> query QueueMessageDevelopment
For local image building, static analysis, unit testing, and CI/CD pipeline documentation, see DEVELOPMENT.md.
License & Attribution
This repository and deployment architecture are licensed under the MIT License. This project is an independent containerized deployment architecture and is not affiliated with, endorsed, or sponsored by Stalwart Labs LLC.
Stalwart License & Ownership: Stalwart Mail Server is open-source software licensed under the GNU Affero General Public License v3.0 (AGPLv3) and developed by Stalwart Labs LLC.