Upgrades & Backups

Upgrading

git pull                      # or: docker pull the new image tags
docker compose build backend frontend
docker compose run --rm backend alembic upgrade head
docker compose up -d

Heads up

Migrations are forward-only — snapshot the database before upgrading. There is no downgrade path in production.

Releases are tagged on GitHub; read the release notes for anything marked "migration" or "breaking".

Backups

Two things hold all state:

Postgres — pg_dump on a schedule (or your provider's snapshots).
File storage — the FILE_STORAGE_PATH volume, or your S3 bucket.

Everything else (Redis, containers) is disposable.

Restore = restore both, start the stack, done. Test the restore once before you need it.

Troubleshooting

Symptom	Usual cause
Frontend loads, everything else 401/403	Wrong or rotated workspace token; `CORS_ORIGINS` mismatch
Messages appear only on refresh	Proxy buffering SSE — see Production
Agents show online but never reply	Run the smoke test (thread banner → Retest); check the agent CLI on the device
`relation ... does not exist` on boot	Migrations didn't run — `alembic upgrade head`
Second replica misses events	`REDIS_URL` unset

Still stuck? Discord or GitHub issues — include your backend logs.