Docker deployment
Docker is the shortest production path for the full edition. (Bulwark Lite needs no container at all; see static hosting.) Pre-built images live on GitHub Container Registry at ghcr.io/bulwarkmail/webmail, and nowhere else. Both linux/amd64 and linux/arm64 come off native runners rather than QEMU emulation, which is why the ARM image isn't the slow one.
Two GHCR packages carry the images:
| Image | Channel | Built from |
|---|---|---|
ghcr.io/bulwarkmail/webmail:latest | Stable | each published release |
ghcr.io/bulwarkmail/webmail:1.19.1, :1.19, :1 | Pinned | one release, or the newest release of a minor or major line |
ghcr.io/bulwarkmail/webmail-beta:latest | Beta | every push to main, for testing |
Every release tag also has an -always variant (for example 1.19.1-always or latest-always), built with NEXT_PUBLIC_LOCALE_PREFIX=always so every URL carries the locale. The old webmail:dev tag is no longer built; don't use it.
Which tag to run
The examples on these pages use :latest, which moves to each release as it ships. For a server you don't watch closely, pin a line instead:
:1takes every 1.x release, fixes and features, and never a 2.0 with breaking changes.:1.19takes only the fixes for 1.19 until you move it on yourself.:1.19.1never changes, for deploys that have to be reproducible. You then upgrade by hand, so watch the releases for security fixes.
Bulwark (not Lite) shows a notice in the admin console when a newer release is out, whatever tag you run.
First-launch setup wizard
There is no .env.local to write before the first start. Launch the container with a volume on /app/data:
docker run -d --name bulwark \
-p 3000:3000 \
-v bulwark-data:/app/data \
ghcr.io/bulwarkmail/webmail:latest
docker logs bulwark # the SETUP REQUIRED block has the setup token
Open http://localhost:3000. The wizard asks for a setup token first: copy it, or the full /setup#token=… link, from the SETUP REQUIRED block in docker logs bulwark. It expires after an hour; restart the container for a new one. The wizard then walks through the server, sign-in, security, logging and branding, and ends with the admin password. It writes the config to ADMIN_CONFIG_DIR (config.json, and the admin password hash in admin.json) and keeps the generated session secret in ADMIN_STATE_DIR.
Afterwards you can remount the config volume read-only; give /app/data/admin a volume of its own for that (see Persistent volumes). Set ADMIN_CONFIG_READONLY=true as well, so the app refuses config writes with a clear message. The wizard's "Lock the configuration after setup" box only leaves a .config-locked reminder file; it doesn't lock anything by itself.
Setting JMAP_SERVER_URL in the environment skips the wizard. Use that path when you want env-driven configuration.
Using Docker
Pull and run
# Latest stable release
docker run -d \
--name bulwark \
-p 3000:3000 \
-v bulwark-data:/app/data \
-e JMAP_SERVER_URL=https://mail.example.com \
ghcr.io/bulwarkmail/webmail:latest
# Pin to a specific version
docker run -d \
--name bulwark \
-p 3000:3000 \
-v bulwark-data:/app/data \
-e JMAP_SERVER_URL=https://mail.example.com \
ghcr.io/bulwarkmail/webmail:1.19.1
# IPv6 dual-stack
docker run -d \
--name bulwark \
-p 3000:3000 \
-v bulwark-data:/app/data \
-e HOSTNAME=:: \
-e JMAP_SERVER_URL=https://mail.example.com \
ghcr.io/bulwarkmail/webmail:latest
Bulwark reads environment variables at runtime, so changing the configuration needs no rebuild.
Build from source
git clone https://github.com/bulwarkmail/webmail.git
cd webmail
docker build -t bulwark .
docker run -d --name bulwark -p 3000:3000 -e JMAP_SERVER_URL=https://mail.example.com bulwark
Docker Compose
For anything longer-lived than a test, run Bulwark and Stalwart from one compose file. The full file, the env_file variant, and the volume layout are on the Docker Compose page.
Persistent volumes
Bulwark writes everything under /app/data, in the directories below. Mount /app/data as one volume and all of them survive when the container is recreated. Docker fills a new named volume from the image, owned by the app's user (uid 1001). A bind mount to a host directory has to be writable by uid 1001.
Settings sync (SETTINGS_DATA_DIR)
Encrypted per-account user preferences. Required only when SETTINGS_SYNC_ENABLED=true. Default: ./data/settings → /app/data/settings in the container.
Admin config (ADMIN_CONFIG_DIR)
Operator-authored state written by the setup wizard and the admin console: config.json, policy.json, admin.json (passwordHash only), plugin-config/, plugins/, themes/, and uploaded branding assets. Default: ./data/admin → /app/data/admin in the container.
After the setup wizard completes, you can mount this directory read-only for immutable deployments. For that it needs a volume of its own on top of the /app/data one (see the example below). Pair with ADMIN_CONFIG_READONLY=true so the app produces a clean error instead of an EROFS halfway through a write.
Admin runtime state (ADMIN_STATE_DIR)
Runtime mutations that must always stay writable: admin-state.json (login timestamps), audit.log, the bootstrap setup token, and the session secret Bulwark generates when SESSION_SECRET isn't set. Default: ./data/admin-state → /app/data/admin-state in the container.
Plugin credentials (PLUGIN_SECRETS_DIR)
The encrypted credentials users save when they connect a plugin to an outside account. Default: next to the settings directory, /app/data/plugin-secrets in the container. Lose it and every user has to connect those accounts again.
Update check (VERSION_CHECK_DATA_DIR)
The result of the last update check. Default: /app/data/version-check. Safe to lose.
Telemetry state (TELEMETRY_DATA_DIR)
Random instance_id, admin consent choice, HMAC'd login fingerprints. Default: ./data/telemetry → /app/data/telemetry. Mount this so the consent and instance id survive image upgrades. The heartbeat is off until an admin opts in; BULWARK_TELEMETRY=off locks it off and greys out the toggle.
Legacy single-volume installs (ADMIN_DATA_DIR)
Pre-1.6.4 installs used a single ADMIN_DATA_DIR volume containing both config and state. That variable is still honoured when neither split variable is set, so existing installs keep working without migration.
Example
bulwark:
image: ghcr.io/bulwarkmail/webmail:latest
environment:
JMAP_SERVER_URL: https://mail.example.com
SESSION_SECRET: replace-with-64-hex-chars # openssl rand -hex 32
SETTINGS_SYNC_ENABLED: "true"
ADMIN_PASSWORD: your-strong-admin-password
EXTENSION_DIRECTORY_URL: https://extensions.bulwarkmail.org
volumes:
- bulwark-data:/app/data
# Only if you want to mount the admin config read-only after setup:
# - bulwark-config:/app/data/admin # rw during setup
# - bulwark-config:/app/data/admin:ro # ro after setup
SESSION_SECRET must be at least 32 characters; generate one with openssl rand -hex 32. Leave it out and Bulwark generates one in the state directory.
Reverse proxy
Terminate TLS in front of Bulwark, in Caddy, Nginx, or Traefik, and forward X-Forwarded-For, X-Forwarded-Proto and Host. Push uses a JMAP EventSource that the browser opens to Stalwart directly, so it's the proxy in front of Stalwart that must not buffer it. Working configs for all three, plus subpath mounting, are on the reverse proxy page.
Health check
/api/health answers liveness probes for Docker and orchestrators with {"status":"healthy"}. Signed-in users and admins can add ?detailed=true to get uptime, version and heap usage measured against V8's own limit; the status turns degraded from 85 % of that limit. If the handler itself fails, it answers unhealthy with a 503. The heap figure is the first thing to look at when a container is being OOM-killed rather than crashing.
/api/ready is the readiness check: 200 once the instance can serve, 503 while it is still starting or, with several instances, while it can't reach the shared store. A single instance answers 200 as soon as it is up.
Updating
docker compose pull && docker compose up -d. Release channels, what survives an upgrade, and the in-app update notice are covered under Updating.