Skip to content
DashboardWebsite

Upgrade and Roll Back

Just want to do it in the dashboard? See the guide: Check migrations after an upgrade.

An upgrade replaces the images in a self-hosted instance. Core applies the release’s schema migrations at startup before serving requests. Migrations run forward, so roll back a release with migrations by restoring the backup taken before the upgrade.

  1. Read the release’s entry in Upgrade Notes. Check its breaking changes, migrations, config changes, and rollback instructions.
  2. Make sure a backup will exist. With backups enabled (Platform Admin → System → Backups), core takes one automatically before applying a migration. If the backup fails, core applies no migration and stops. With backups off, click Back up now first, or call POST /v1/admin/backups. See Backups and Restore.
  3. Note what is running: the workspace release for Docker, and the image tags for Helm.

Docker (single VM). Check out the new workspace release, bring each component to the ref it pins, then rebuild:

Terminal window
git checkout v1.3.0
make bootstrap
make up-prod

Automatic rebuild on rsync runs the same upgrade steps on each sync.

Helm. Run helm upgrade with the new chart version and image tags. See Helm deployment. One pod runs migrations while the others wait. The startupProbe allows 10 minutes; raise it for a large database.

  • Check the core logs for Migrations pending: …, an Applied migration <id> line for each migration, and then Ready.
  • In the dashboard: Platform Admin → System → Migrations. The page lists applied migrations, newest first, and how many documents each changed. pending should be empty.
  • Open the dashboard and run one review.

Find the release’s rollback instructions in the upgrade notes.

If the release has no migration, deploy the previous release: use the previous workspace release and run make up-prod for Docker, or use the previous image tags for Helm.

If the release has a migration, the previous image refuses to start on the migrated database. Its log names the migration IDs it does not know. Restore the data before deploying the previous release:

  1. Stop core and the task scheduler. Keep MongoDB running.
  2. Restore the backup taken before the upgrade, as described in Backups and Restore → Restore. If core took the backup, its trigger is migration.
  3. Deploy the previous release.

The restore loses writes made after the backup, including findings, triage, and settings.

Core stops with an error and does not record the failed migration in the ledger. Migrations can run again. Fix the cause, such as a full disk or a lost MongoDB connection, then start core again so it retries the failed migration. If it fails again, roll back.