Updating
An update is a new image tag, a database backup and two commands. Three rules make it boring — keep them.
The three rules
- 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.
- Back up PostgreSQL before every update. One command, a few seconds, the whole term saved.
- Move one version at a time. From
2026.10.15to2026.11.14is one step; skipping versions compounds small surprises into big ones.
Before you start
- Read the release highlights for the version you are moving to.
- Confirm your
compose.yamlpins an explicit version tag (not a floating one), and that you can still reach the old image — locally cached or still in the registry. Keeping the previous image around is your rollback plan. - Take the backup:
docker compose exec -T postgres \
pg_dump -U lecture -d lecture -Fc > backups/pre-update-$(date +%F-%H%M).dump
Update
# 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.
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
- Update cadence is the project's: dated versions, occasionally several in a week during active stretches. Nothing forces you to follow every one — but the smaller the gap when you do update, the easier it is.
- Before larger surgery (a new host, a major jump), export a workspace from inside the app as a second copy, and say hello on hello@nilox.network — early operators get a reply.