Upgrade

Bookend never updates itself. A release is a bundle the bank verifies and applies inside a maintenance window. Schema changes are forward-only DDL scripts applied by the migrator; the release notes list every script a release adds.

The commands below use the production override from the Installation Guide; add -f deploy/compose.external-db.yml if the install uses an external database.

Before the window

1. Read the release notes (CHANGELOG.md in the new bundle; after the upgrade, also System → Release notes or GET /v1/releases). Note any restart_required settings and the DDL scripts the release adds.
2. Verify the new bundle’s checksums and signature per its VERIFY.md, then load its images: docker load -i bookend-<new version>-images.tar. Loading does not touch the running stack, and the previous images stay available for a rollback.
3. Compare the new bundle’s deploy/compose.yml and deploy/.env.example with the installed ones. Copy the new compose.yml into place; keep your deploy/.env and override files, adding any new variable the release notes call for.
4. Take a backup (backup-restore.md): database dump, documents and exports volumes, deploy/.env.
5. Confirm the current state is clean: GET /v1/diagnostics shows every health entry healthy, the last evidence sweep has no broken chains, no pipeline runs are in flight (GET /v1/loans?state=processing is empty) and no boarding record is committing.

During the window

# set BOOKEND_VERSION=<new version> in deploy/.env
docker compose -f deploy/compose.yml -f deploy/compose.production.yml up -d --wait
docker compose -f deploy/compose.yml -f deploy/compose.production.yml logs migrator   # lists the scripts it applied; exits 0

api starts only after the migrator has completed successfully, and its readiness check (/readyz, schema) stays unhealthy until the ledger holds every script the new build requires, so an upgrade cannot run against a half-migrated database. The scheduler picks up persisted jobs (pipeline stages, nightly evidence sweep, daily heartbeat) where they were.

Smoke test

• GET /readyz healthy; GET /v1/diagnostics shows the new version and the expected database.schemaVersion.
• Golden-package test: upload BK-DEMO-001 from the new validation pack as a new loan; it must reach review with no findings, and GET /v1/loans/BK-DEMO-001/evidence/verify must report intact: true. Reject the test loan afterward.
• Open one existing loan: values, provenance chips, findings and the evidence chain render; its evidence/verify is intact.
• Send a metering heartbeat (System → Metering & license → Send heartbeat now) unless air-gapped.

Rollback

1. The release added no DDL scripts (the release notes say so, and logs migrator reported 0 applied): set BOOKEND_VERSION back to the previous version in deploy/.env and run up -d --wait again.
2. The release applied new scripts: the previous version’s migrator refuses to run against a ledger that holds scripts it does not know (exit 4), so the previous images cannot simply be restarted. Set BOOKEND_VERSION back and restore the pre-upgrade backup (backup-restore.md); the restored ledger matches the previous version.
3. Record the rollback in the change log and send the GET /v1/diagnostics output and logs migrator to Bookend support.