Docs / DeploymentUpdated MarkdownEdit on GitHub

Updating

Release channels

Two GHCR packages, built for linux/amd64 and linux/arm64 on native runners:

ImageChannelBuilt from
ghcr.io/bulwarkmail/webmail:latestStableeach published release
ghcr.io/bulwarkmail/webmail:1.19.1, :1.19, :1Pinnedone release, or the newest release of a minor or major line
ghcr.io/bulwarkmail/webmail-beta:latestBetaevery push to main

Run :latest unless you have a reason not to. Pin :1.19.1 (or :1.19) when you need reproducible deploys. Use ghcr.io/bulwarkmail/webmail-beta:latest only where breakage is acceptable; it moves with every push to main. Every release tag also has an -always variant (for example 1.19.1-always) built with NEXT_PUBLIC_LOCALE_PREFIX=always. The old webmail:dev tag is no longer built.

Each GitHub release also carries the standalone Node.js tarballs (bulwark-standalone-<version>-linux-amd64.tar.gz, -arm64) and, from 1.11 on, the Bulwark Lite zips bulwark-lite-<version>.zip and bulwark-lite-stalwart.zip. Every file has a .sha256 next to it and a build provenance attestation: gh attestation verify <file> --repo bulwarkmail/webmail. Lite has no update channel of its own: download the new zip, keep your config.json, and re-upload. A Lite install hosted by Stalwart updates when Stalwart downloads bulwark-lite-stalwart.zip again, see Install on Stalwart.

Upgrading

Docker Compose:

docker compose pull
docker compose up -d

Plain Docker:

docker pull ghcr.io/bulwarkmail/webmail:latest
docker rm -f bulwark
# then re-run your original `docker run` command

Manual install:

cd /opt/bulwark
git pull origin main
npm install
npm run build
pm2 restart bulwark      # or: sudo systemctl restart bulwark

Bulwark reads its configuration at runtime, so an upgrade never requires rewriting .env.local, and changing a setting needs no rebuild. The one exception is the handful of build-time variables (NEXT_PUBLIC_BASE_PATH, NEXT_PUBLIC_LOCALE_PREFIX, NEXT_PUBLIC_DEFAULT_LOCALE, NEXT_PUBLIC_PUSH_RELAY_URL), which need a rebuild if you change them. The Docker build takes the first three as --build-arg; for a different push relay, add it under User policy > Push relays in the admin console instead.

Moving to Stalwart 1.0

Upgrade Bulwark to 1.18.0 or newer before the mail server moves to Stalwart 1.0. Once the server runs 1.0, click Set up with Stalwart under OAuth / OpenID Connect on the admin Authentication page, and check the server settings some features depend on there. Upgrading to Stalwart 1.0 has the order, the settings and the differences.

What survives an upgrade

Only what you mounted. Everything Bulwark writes lives under /app/data, split into directories so they can be given different treatment. Mounting /app/data as one volume (-v bulwark-data:/app/data) keeps all of them. Docker fills a new named volume from the image, owned by the app's user (uid 1001); a bind-mounted host directory has to be writable by uid 1001.

DirectoryVariableHolds
/app/data/adminADMIN_CONFIG_DIRWizard and admin console config, plugins, themes, branding
/app/data/admin-stateADMIN_STATE_DIRAudit log, login timestamps, setup token, generated session secret
/app/data/settingsSETTINGS_DATA_DIREncrypted per-account user settings
/app/data/plugin-secretsPLUGIN_SECRETS_DIRCredentials users saved for plugins, encrypted
/app/data/telemetryTELEMETRY_DATA_DIRInstance id and telemetry consent
/app/data/version-checkVERSION_CHECK_DATA_DIRLast update check (safe to lose)

An install that mounts only some of these directories loses the others when the container is recreated. Older examples in these docs, and the repository's docker-compose.yml, mount four volumes and leave out the plugin credentials; add a volume for /app/data/plugin-secrets, or move to the one /app/data volume.

Lose the config volume and Bulwark starts as a fresh install: the setup wizard runs again (the token is in the log), or, with JMAP_SERVER_URL set, the admin console stays off until ADMIN_PASSWORD is set. Lose the settings volume and users get defaults back. Neither loses mail, because Bulwark stores no mail.

The in-app update notice

Bulwark checks for a newer release 30 seconds after it starts and then every hour, and logs the result. When one exists, the version line on the login page turns amber ("New version available") and links to the release notes, and the admin entry in the navigation gets a dot. The admin console's Updates page shows the details.

The feed can mark a release as a security fix. When the running build is older than a release marked that way, or no longer supported, the version line turns red ("Security update available", "Version no longer supported"), so an operator can tell a routine update from one that should happen today. Signed-in users also see the advisory text in the version details; visitors who aren't signed in never do. Every release that fixed a published advisory is marked (1.4.10, 1.4.11, 1.9.0, 1.9.2, 1.10.0 and 1.16.0 so far). Fixes without a published advisory can still come with a plain notice, so read the release notes too and check the repository's security advisories. Security fixes and updates says how to hear about them.

Turn it off if you'd rather manage upgrades entirely from outside:

BULWARK_UPDATE_CHECK=off

Or point it at your own feed, which is the better option on an air-gapped deployment:

BULWARK_UPDATE_CHECK_URL=https://updates.example.com/bulwark.json

An empty value for that variable disables the check as well. State is kept in VERSION_CHECK_DATA_DIR (default ./data/version-check).

The check is separate from the anonymous usage heartbeat, which is off unless you turn it on.

Backing up the shared store

With several instances, everything the data volume held lives in the shared store instead, so back that up before an upgrade:

  • Valkey or Redis with AOF or RDB: copy the persistence files from its data directory (BGSAVE first for an RDB snapshot), or snapshot its volume.
  • A managed service: take a snapshot in its console.
  • Or start one instance with REDIS_URL and SHARED_STORE_EXPORT=1 on an empty volume: it writes everything into the usual file layout and exits. That copy also starts a single instance if you ever need one.

Rolling updates work: replace replicas one at a time. While two versions run side by side a page may need a reload.

Downgrading

Pin the earlier tag and restart. Config files are read forwards and backwards for anything within a minor series, but a downgrade across a release that changed the config layout may leave keys the older build ignores. Take a copy of the config volume before a major upgrade.