Upgrades and versioning
How to upgrade a self-hosted instance, what happens to the database on the way, and what to expect from releases before 1.0.
Upgrade
Read the release notes
Look for new migrations, new required settings and breaking changes. Before 1.0, breaking changes can happen in any release.
Back up
Take a Postgres snapshot (or confirm point-in-time recovery is on) and make sure your OPENDASH_KEK backup is current.
Pull and restart
With published images, change the tags in OPENDASH_WEB_IMAGE and OPENDASH_WORKER_IMAGE, then:
docker compose pull && docker compose up -dFrom a clone:
git pull && docker compose up -d --buildThe setup service applies new migrations first, under an advisory lock, and web and worker start only after it succeeds.
Upgrading past migration 0090: stop, migrate, start
Migration 0090 replaces the old dashboards with the new ones and retires reports and public links. It drops tables the previous version reads, so this one upgrade can't roll: stop web and worker first (docker compose stop web worker), then pull and start as above.
It also deletes what used the old engine: old dashboards and reports, public links, routines that sent a dashboard (with their runs and sends), and dashboard attachments in conversations. Take the backup in the first step.
Why upgrades are safe to roll
- Migrations are forward-only and written to work while the previous version is still running, so a rolling deploy never has old code reading a schema it doesn't understand. The release notes say when one can't, as 0090 couldn't.
- Long backfills run as background jobs, not inside the migration, so an upgrade doesn't wait on them.
- Work survives a restart. The transcript in Postgres is canonical, jobs are fenced by attempt, and side effects (emails, Slack messages) go through an idempotent outbox, so a run interrupted by a deploy resumes rather than repeating what it already sent.
Versions and images
- Releases are tagged
v*. Images are published to GitHub Container Registry asghcr.io/getopendash/opendash-webandghcr.io/getopendash/opendash-workerfor everyv*tag and formain. - Pin a version tag in production. Running
maingets you every change as it lands. - Support: OpenDash is pre-1.0. Security fixes go into
mainand the latest release.