Upgrading & rolling back

This page covers how to upgrade a running instance without losing data if something goes wrong, and how to roll back if it does.

Upgrades run database migrations automatically, every time

Every time the web container starts, it runs any pending database migrations automatically, with no dry-run step and no automatic snapshot first. If a new migration (or the code that shipped with it) turns out to be broken once it’s live, the only way back is the backup and restore tooling below, and only if you took a snapshot before upgrading. Make that step part of the upgrade itself, not something you reach for after it’s already gone wrong.

The upgrade procedure

1. Snapshot the current, known-good state before pulling anything new:

   docker compose exec -T web python manage.py create_backup

2. Pull the new version, refresh the base images, and restart:

   git pull
   docker compose pull --ignore-buildable
   docker compose build --pull
   docker compose up -d

   The two middle commands fetch the latest PostgreSQL, nginx, and Python base images, so OS and library security fixes arrive with every upgrade. A plain docker compose up -d --build keeps reusing whatever base images are already on the host. If you run the Tailscale profile, add --profile tailscale to the pull and up commands.

3. If something’s broken, roll the code back first:

   git checkout <previous-tag-or-commit>
   docker compose up -d --build

4. Then restore the pre-upgrade snapshot from step 1 (the path was printed when you ran create_backup, or look in BACKUP_DIR for the most recent redscribe-backup-<timestamp>.rsbk):

   docker compose exec web python manage.py restore_backup /app/backups/redscribe-backup-<timestamp>.rsbk

Rolling the code back alone is sometimes enough, if it’s a bad release with no migration in it. You only need to restore the database once a migration has actually changed the schema in a way the old code can’t run against. Either way, having that pre-upgrade snapshot in hand before you start means you’re never making this call under pressure with nothing to fall back on.

For the full detail on create_backup and restore_backup, including retention, encryption, the account-reconciliation report restore_backup prints before it touches anything live, and the automatic safety snapshot it takes for you right before restoring, see Backup & restore.

Version tags

Releases are tagged v<version> (for example v0.2.0-alpha). The git checkout <previous-tag-or-commit> in step 3 above means exactly that tag, or any commit you know was working. See Alpha status & versioning for how RedScribe’s pre-1.0 versioning works and what to expect from a minor-version bump.