Skip to content

Upgrades and rollback

Each release is a vX.Y.Z tag with a GitHub Release (the CLI and server binaries, the Cloudflare bundle, SHA256SUMS, and release notes with the upgrade notes and schema version) and the image ghcr.io/angler-ai/runbook, tagged X.Y.Z, X.Y and latest for linux/amd64 and linux/arm64. Read the release notes before updating.

Terminal window
deploy/update.sh --dry-run # the plan only
deploy/update.sh # the latest release, asking before changing anything
deploy/update.sh --to 0.3 # the newest 0.3.x
  1. Preflight. runbook-server doctor on the running server, its release, the target release and free disk space. A downgrade is refused; the same release is “nothing to do”.
  2. Verify and pull. The tag is resolved to a digest, its build provenance verified with gh attestation verify against the release workflow and tag, and the image pulled by digest. Nothing from the image runs before that. The target’s own doctor then checks your database: a schema it can’t run is refused.
  3. Back up. pg_dump of the whole database to a 0600 file in deploy/backups/, read back in full, so an empty or truncated dump stops the update before anything changes. The newest 5 are kept (--keep-backups).
  4. Restart on the new image; the server applies its migrations as it starts. The previous image stays as <image>:rollback-<release>.
  5. Check health: the container healthcheck, /health/ready, /v1/meta reporting the new version and schema, doctor, the web UI and the CLI.

Pin a line in deploy/.env with RUNBOOK_UPDATE_PIN=0.3 (or 0.3.1), so a plain deploy/update.sh only takes patch releases. With an external database, back up with your provider’s tools and pass --skip-backup.

Every migration keeps the previous release working (expand, then contract in a later release), so rolling the code back is safe on the migrated schema.

If the restart or the health check fails, the script offers to roll back (without asking under --yes): it starts the previous image on the migrated database, with RUNBOOK_ALLOW_NEWER_SCHEMA=true set by a compose override it writes to deploy/backups/allow-newer-schema.yml. Until the next update, start the stack with that file too, or the older server refuses the newer schema (postgres.schema_newer_than_code).

A problem found later: deploy/update.sh --rollback undoes the last update.

The backup is restored only with --restore-backup, since that loses everything written after it. It never drops your database: it restores into a scratch database and swaps the two by rename, keeping the old one as runbook_replaced_<time>.

runbook-server --version prints the release’s rollback floor: the oldest release whose code is safe on its schema. If you skip releases past one that removed something (a contract migration), your current release may be below the floor of the new one. A failed update then can’t simply restart your old release, so the update asks for --restore-backup (a failure restores the backup) or --no-rollback.

Exit status, for automation: 0 updated, 1 refused (nothing changed), 3 failed and rolled back, 4 failed and not rolled back.

Terminal window
runbook version # this CLI's release and the server's
curl -s https://runbooks.example.com/v1/meta # "version" and "schema"
runbook-server --version # release, schema and rollback floor