Skip to content

Operate

Upgrades and migrations

How to upgrade a running installation safely.

CirCI is one image plus Postgres. Upgrading is: back up, build the new image, start it, and let it migrate.

  1. Back up. Save the database (and the storage if it's local disk). See Backups.

  2. Read the changes. Look through the repository's history since your commit, especially new migrations in packages/db/migrations and new environment variables.

  3. Pull and rebuild. Start the new image.

    Terminal window
    git pull
    cd deploy
    docker compose up -d --build
  4. Let it migrate. serve, worker and all apply pending migrations before they start serving, unless started with --no-migrate. Look at the log for the migration messages, and run docker compose exec circi circi admin doctor.

For a deployment where several instances start at once, or where you want a step in your pipeline, apply the migrations first and start the app with --no-migrate:

Terminal window
docker compose run --rm circi migrate # applies migrations and exits
# command: ['serve', '--no-migrate'] and ['worker', '--no-migrate'] for the long-running services

Background jobs are rows in the database and outlive a deploy. A new version has to understand jobs queued by the old one, and the old one may still be running while the new starts. CirCI avoids changing a job name or payload key without a rolling-deploy plan, so upgrading one step at a time is safe to roll out. If you skip many commits, stop the old workers and let the queue drain first (Instance › Health shows the queue depth), then upgrade.

Section titled “Things that sign people out or break links”
  • Changing BETTER_AUTH_SECRET signs everyone out.
  • Moving the dashboard to another host: set PREVIOUS_PUBLIC_URLS. See TLS and reverse proxy.
  • Changing the storage driver: copy the files with circi admin storage migrate first.

The image is built from the repository and has no published version tags. Note the commit you deployed (git rev-parse HEAD) so you can reproduce it or roll back.