# Upgrade and rollback runbook

1. Record the running image digest and take a tested metadata backup plus repository
   recovery evidence before changing the image.
2. Pull/build the pinned image, then run `docker compose run --rm migrate upgrade`.
   Do not start web, scheduler, or worker against an unverified schema.
3. Start the stack, wait for `/readyz`, and inspect `/metrics` for stale leases,
   schedule lag, unavailable repositories, and corrupt backups.
4. If migration fails, stop and restore the prior metadata backup and matching image;
   do not attempt to downgrade an unknown partially migrated database in place.
5. Preserve migration logs and verify a representative backup restore before closing
   the change.