Updating

An update is a new image tag, a database backup and two commands. Three rules make it boring — keep them.

The three rules

  1. Never run two application versions against one database. One app version writes to the database at a time — old and new containers must never run side by side, not even briefly.
  2. Back up PostgreSQL before every update. One command, a few seconds, the whole term saved.
  3. Move one version at a time. From 2026.10.15 to 2026.11.14 is one step; skipping versions compounds small surprises into big ones.

Before you start

back up the database (adjust paths to your setup)
docker compose exec -T postgres \
  pg_dump -U lecture -d lecture -Fc > backups/pre-update-$(date +%F-%H%M).dump

Update

shell — from the folder with compose.yaml
# 1. point the compose file at the new version tag, then:
docker compose pull app

# 2. replace the app container (the database keeps running)
docker compose up -d

# 3. confirm: app and database up, app logs quiet
docker compose ps
docker compose logs --tail 50 app

Then open the app, log in and check one of your documents is intact and edits sync. Users get a one-time "What's new" screen describing the version in plain language.

Rolling back

Rollback means: stop the new app, and point the compose file back at the previous tag — retagging, not restoring, as long as you still have the image.

shell — go back to the previous version
docker compose down            # without -v ! this keeps the data volume
# set services.app.image back to the previous tag
docker compose up -d

Rolling back works cleanly while the database schema stays compatible. A version that changed the schema may not accept an older app — which is exactly why the backup above exists: worst case, you restore the dump into a fresh volume and take it from there. Never let the app "just try" an older version over a newer schema without a backup in hand, and don't experiment against your main database — restore the dump elsewhere and look first.

Notes for pre-1.0