Skip to main content

Upgrades

How to upgrade a self-hosted Compass install: normal image updates 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 — 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.

Database migrations​

Current releases do not ship a server-side migration runner or pending database migrations. Normal upgrades only replace the running images. Back up before an upgrade as usual; a future data repair will ship with its own operator runbook rather than silently running during deployment.

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.

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.