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.
-
Back up. Save the database (and the storage if it's local disk). See Backups.
-
Read the changes. Look through the repository's history since your commit, especially new migrations in
packages/db/migrationsand new environment variables. -
Pull and rebuild. Start the new image.
Terminal window git pullcd deploydocker compose up -d --build -
Let it migrate.
serve,workerandallapply pending migrations before they start serving, unless started with--no-migrate. Look at the log for the migration messages, and rundocker compose exec circi circi admin doctor.
Running migrations yourself
Section titled “Running migrations yourself”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:
docker compose run --rm circi migrate # applies migrations and exits# command: ['serve', '--no-migrate'] and ['worker', '--no-migrate'] for the long-running servicesRolling deploys
Section titled “Rolling deploys”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.
Things that sign people out or break links
Section titled “Things that sign people out or break links”- Changing
BETTER_AUTH_SECRETsigns 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 migratefirst.
Versions
Section titled “Versions”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.