# Updating

Source: https://bulwarkmail.org/docs/deployment/updating
Last updated: 2026-11-12

> Release channels, how to upgrade each install type, and how the update notice works.

## Release channels

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

| 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`                                |

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](https://bulwarkmail.org/docs/deployment/static.md) 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](https://bulwarkmail.org/docs/deployment/stalwart-app.md#updating).

## Upgrading

**Docker Compose:**

```bash
docker compose pull
docker compose up -d
```

**Plain Docker:**

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

**Manual install:**

```bash
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](https://bulwarkmail.org/docs/deployment/updating/stalwart-1-0.md) 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.

| Directory            | Variable             | Holds                                              |
| -------------------- | -------------------- | -------------------------------------------------- |
| `/app/data/admin`       | `ADMIN_CONFIG_DIR`   | Wizard and admin console config, plugins, themes, branding |
| `/app/data/admin-state` | `ADMIN_STATE_DIR`    | Audit log, login timestamps, setup token, generated session secret |
| `/app/data/settings`    | `SETTINGS_DATA_DIR`  | Encrypted per-account user settings                |
| `/app/data/plugin-secrets` | `PLUGIN_SECRETS_DIR` | Credentials users saved for plugins, encrypted |
| `/app/data/telemetry`   | `TELEMETRY_DATA_DIR` | Instance id and telemetry consent                  |
| `/app/data/version-check` | `VERSION_CHECK_DATA_DIR` | Last 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](https://github.com/bulwarkmail/webmail/security/advisories). [Security fixes and updates](https://bulwarkmail.org/docs/deployment/security-updates.md) says how to hear about them.

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

```env
BULWARK_UPDATE_CHECK=off
```

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

```env
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](https://bulwarkmail.org/docs/features/telemetry.md), which is off unless you turn it on.

## Backing up the shared store

With [several instances](https://bulwarkmail.org/docs/deployment/multi-instance.md), 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.

## Related pages

- [Docker deployment](https://bulwarkmail.org/docs/deployment/docker.md)
- [Manual deployment](https://bulwarkmail.org/docs/deployment/manual.md)
- [Admin console](https://bulwarkmail.org/docs/guides/admin.md)
