How-to guide

Upgrade Workbench

Upgrading is a tag swap against the same persistent state: stop the old container, pull the new tag, start it against the same volumes. Schema migrations apply automatically on the new binary's first start. The one rule that matters is back up first.

1. Back up first

The recovery story across a failed upgrade depends on a known-good snapshot. Three things make up a restorable install:

The arq_workbench_data volume — the SQLite database and the license artefact.
The identity volume (/var/lib/arq) — instance_id and install_secret.
The master key (WORKBENCH_MASTER_KEY / WORKBENCH_MASTER_KEY_FILE). It is not in either volume — it lives in your secret manager. Restoring the volumes with a missing or wrong master key cannot unwrap the workspace seed.

The supported backup is a stopped-container snapshot — SQLite must be quiesced:

# 1. Stop the container so the SQLite file is quiesced.
docker compose stop arq-workbench

# 2. Snapshot the data volume to a tarball. Substitute the actual
#    Docker volume name (Compose prefixes it with the project name).
docker run --rm \
  -v arq_workbench_data:/data:ro \
  -v "$(pwd):/backup" \
  alpine tar czf /backup/arq_workbench_data.tgz -C /data .

Repeat for the identity volume.

2. Pull the new tag and start

# Update the image tag in docker-compose.yml, e.g.
#   image: ghcr.io/elevarq/workbench:v0.2.0
docker compose pull
docker compose up -d

On first start the new binary applies any SQLite migrations new in that tag (listed in the release's changelog). Verify the upgrade through /healthz — schema_version reflects the highest applied migration:

curl -fsS http://127.0.0.1:8080/healthz
# {"status":"ok","version":"v0.2.0","schema_version":31, ... }

Verify the new image before you run it. Re-run the signature and SBOM checks for the new tag, exactly as you did for the first install.

Migrations are forward-only — there is no automatic downgrade. If a new binary will not start against your data, the recovery is to restore the pre-upgrade tarball and run the previous tag. That is what the step-1 backup is for.