Upgrades & rollback

Pull a new release, run migrations, and roll back when one goes wrong

Nothing in the stack is built locally: every service runs a published image, tagged by version variables in .env. So an upgrade is a pull of new images, and a rollback is pinning those variables back. Migrations run automatically on boot either way. This page covers the routine upgrade, the two cases that need a manual step, and how to roll back.

Upgrade to a new release

Take a Postgres backup before you start. Migrations run on boot and a git checkout won’t reverse them, so a backup is the only thing that gets you back if one goes wrong. Backups & restore has the command.

Pull the new images

git pull              # picks up compose file changes
docker compose pull   # fetch the new images
docker compose up -d

docker compose up -d won’t fetch anything on its own when the tag is already present locally, which is why pull is its own step.

Let migrations run

Database migrations run automatically on backend startup, so watch the backend come up rather than assuming it worked:

docker compose logs -f backend    # look for "Application startup complete"

If a migration failed, the backend won’t reach that line. Run it by hand to see the error:

docker compose exec backend python manage.py migrate

Re-run PeerDB init if the release notes say so

When a release changes which Postgres tables are mirrored, re-run init. The release notes say when that applies. The container’s entrypoint is already bash /setup.sh, so no arguments are needed:

docker compose run --rm peerdb-init

Note

PeerDB init only rebuilds the tables it mirrors from Postgres. It does not restore the spans the fi-collector writes straight to ClickHouse, so it is not a recovery path for lost ClickHouse data. For that, restore from a ClickHouse backup.

Roll back a bad release

Warning

Checking out older code does not undo a migration that already ran. If the release you’re leaving applied one you need reversed, roll that back or restore Postgres from a backup before you pin the old images, or you’ll be running an old binary against a newer schema.

Rolling back is a version pin, not a git checkout. First find the tags you’re on:

docker compose images    # IMAGE and TAG per running service

Then set each one back to the previous release in .env and bring the stack up again:

# .env (release tags are vX.Y.Z, matching the repo's git tags)
FUTURE_AGI_VERSION=v1.25.0
FRONTEND_VERSION=v1.25.0
AGENTCC_GATEWAY_VERSION=v1.25.0
SERVING_VERSION=v1.25.0
CODE_EXECUTOR_VERSION=v1.25.0

docker compose up -d

FUTURE_AGI_VERSION covers backend, worker and fi-collector, which all share one image. Leaving a variable empty means :latest, so for anything carrying real traffic, pin all five rather than floating.

Dive deeper

Troubleshooting & FAQs

Symptoms, causes, and fixes for common errors

Support

Where to get help when you’re stuck

Was this page helpful?

Questions & Discussion