Upgrading

Broch upgrades are a container image swap. The new image applies any pending database migrations on its first start, then serves. This page covers the parts every platform shares — what to do before you upgrade, how to tell it worked, and how to roll back. For the exact commands on your platform, see its install guide:

• Docker Compose
• Azure
• AWS
• DigitalOcean

Before you upgrade

1. Back up the database. It holds the only irreplaceable state — the Data Protection key ring, your license token, the audit log, and usage counters. The image carries no state; the database is everything. Use your platform’s backup (managed snapshot, or pg_dump for embedded Postgres — see your install guide’s Backup section).
2. Pin a version. Set the explicit image tag for the release you’re moving to (BROCH_VERSION / broch_image), not a floating latest. An upgrade should be a decision, not whatever happened to publish.
3. Keep BROCH_MASTER_KEY and the database connection unchanged. The same key from your secret store keeps the key ring readable, so no one re-authenticates. See At-Rest Encryption.

Upgrade

Bump the version and roll out per your platform’s install guide. On its first start the new container runs any pending migrations, then begins serving.

Verify

Watch the startup logs, then the health endpoints:

curl https://tunnels.company.com/healthz        # liveness — 200 once the process is up
curl https://tunnels.company.com/healthz/ready  # readiness — 200 once license + auth load

A clean upgrade logs Running database migrations followed by a normal boot and a 200 from /healthz/ready. Active tunnels drop on the restart; CLI clients reconnect automatically.

If a migration fails

Migrations are applied as a unit on startup. If one fails, the server logs the error at Critical and refuses to start rather than serving on a half-applied schema — so a failed upgrade is loud and obvious, not silent corruption. The container will not become ready.

When this happens:

1. Capture the startup log — it names the failure.
2. Roll back (below) to restore service.
3. Send the log to [email protected].

Rolling back

A rollback is two steps, not one — reverting the image alone is not enough:

1. Restore the database from the backup you took before upgrading.
2. Revert the image to the previous version.

This is because migrations move the schema forward only — they are not automatically reversed when you downgrade the image. The old image running against the new (migrated) schema is an unsupported, broken combination. Restoring the pre-upgrade database snapshot is what actually returns you to a known-good state; reverting the image without it leaves old code on a new schema.

This is why the database backup in step 1 of Before you upgrade is not optional — it is your only rollback path.

Staying current

Broch ships as an image you control; it never auto-updates and never phones home for code. Watch broch-io/broch-deploy for new releases and upgrade on your own schedule. Apply security-relevant releases promptly — a fielded image runs whatever version you last deployed.