Upgrading & Rollback

A Broch upgrade swaps the container image. The new image applies any pending database migrations on its first start, then serves. This page covers what every platform shares: what to do first, how to tell it worked, and how to roll back. The commands for each platform:

• Azure and AWS appliances
• Docker Compose
• DigitalOcean
• Azure Container Apps
• AWS ECS Fargate

Before You Upgrade

1. Back up the database. It holds Broch’s state: the Data Protection key ring, your license token, the audit log and usage counters. The image carries none. On Docker Compose, keep .env too, for the master key and database password. Use your platform’s backup: a managed snapshot, or pg_dump for a bundled database. On the appliances, see Back Up.
2. Pin a version. Set the release you’re moving to, not latest: BROCH_VERSION in /opt/broch/.env on the Azure appliance, BrochVersion on AWS, BROCH_VERSION on Docker Compose, image_tag on DigitalOcean, broch_image on the Terraform modules. An upgrade should be a decision, not whatever happened to publish.
3. Keep BROCH_MASTER_KEY and the database connection unchanged. The same key keeps the key ring readable, so no one has to sign in again. See At-Rest Encryption.

Upgrade

Change the version and roll out with your platform’s commands. On its first start the new container runs any pending migrations, then serves.

Verify

Watch the startup logs, then the health endpoints:

curl https://broch.{your-domain}/healthz        # liveness — 200 once the process is up
curl https://broch.{your-domain}/healthz/ready  # readiness — 200 once the license and database check out

A clean upgrade logs Running database migrations, boots normally, and returns 200 from /healthz/ready. Active tunnels drop on the restart, and CLI clients reconnect automatically.

If a Migration Fails

Migrations apply as a unit on startup. If one fails, the server logs the error at Critical and refuses to start rather than serve on a half-applied schema. The container never becomes ready.

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

Reverting the image alone isn’t enough. Migrations move the schema forward only, and an older image refuses to start on a migrated schema. A rollback takes two steps:

1. Restore the database from the backup you took before upgrading. Docker Compose → Backup has the commands.
2. Revert the image to the previous version.

That backup is your only way back, which is why step 1 of Before You Upgrade isn’t optional.

On the appliances, restore the database, then rebuild at the earlier version as in Recover.

Staying Current

Broch ships as an image you control. It never updates itself and never downloads code. Watch broch-io/broch-deploy for new releases and upgrade on your own schedule. Apply security releases promptly: a deployment runs whatever version you last deployed.