Skip to main content

Upgrades

How to upgrade a self-hosted Compass install: normal image updates, when a database migration is involved, and the one-time sub-calendar v1 cutover.

Back up first, every time. See Back up & restore — ./compass update and ./compass rebuild don't snapshot your data or your old app version, so a bad upgrade has no automatic rollback otherwise.

Normal upgrades (published images)​

Most upgrades are a pull-and-restart of the published DockerHub images:

cd ~/compass
./compass update

This runs docker compose pull then docker compose up -d and waits for the backend health check. It does not touch your data volumes, and it does not run database migrations (see below) — it only replaces the running containers with newer images at whatever version compass.yaml points at.

Upgrades from your own source checkout​

If you run custom code — your own fork, or values baked into the web bundle at build time — update your git checkout and rebuild locally instead of pulling published images:

git pull
cd ~/compass
./compass rebuild

./compass rebuild builds images locally with Docker instead of pulling them. It requires the build blocks in compose.yaml to be uncommented and the full repo checkout present alongside it — see the Custom code guide. It restarts and health-checks the same way update does.

When you need to run a migration manually​

Migrations never run automatically on deploy — neither ./compass update, ./compass rebuild, nor the backend container's own startup (its entrypoint is the app server, nothing else) invokes the migration runner. If a release adds one, you run it yourself; check the release notes for whether it belongs before or after the image update.

bun run cli migrate pending   # check what's pending
bun run cli migrate up        # run everything pending

Both live in packages/scripts. The runner reads its Mongo connection from your config file — set COMPASS_CONFIG_FILE=~/compass/compass.yaml outside the dev repo — and needs to run from a machine or container that can reach the compose network, since Docker installs don't publish the Mongo port to the host.

Back up before running any migration; see Back up & restore. Migrations here are written to be additive and non-destructive (packages/scripts/src/migrations/), but the backup is still the only rollback if one behaves unexpectedly.

One current migration is cleanup rather than additive: priority-data-cleanup (2026.07.14T10.00.00) removes the now-dead priority field left over from the removed priority-tagging feature and drops its orphaned collection. It's routine — run it like any other pending migration.

Upgrading from a pre-cutover install (before v1.0.236)​

The sub-calendar v1 release (2026-07) moved events out of the legacy event collection into a calendar-owned schema behind a one-time collection rename. The migration code for that cutover shipped in releases up to v1.0.310 and was removed afterwards, so releases newer than v1.0.310 cannot migrate a pre-cutover database.

If your install has never performed the cutover, upgrade in two steps:

  1. Upgrade to v1.0.310 and complete the cutover following that version's event migration runbook.
  2. Then upgrade to the latest release as a normal upgrade and run any remaining pending migrations.

Installs that already cut over (or were first installed after v1.0.236) upgrade normally and can ignore this section.

Server hosting guide (initial setup), Monitoring (what to watch after an upgrade), and Google Calendar (if the upgrade touches Google sync configuration).

Have an idea on how we can make self-hosting easier? Let us know in this GitHub Discussion.