Upgrade & Migration Guide

Self-hosted MonSPHERE deployments upgrade by pulling new service images and applying any new database migrations — there's no separate "migration tool" to install.

Standard upgrade

git pull
docker compose build
docker compose up -d

Migrations run automatically on service startup, forward-only, and are idempotent (ADD COLUMN IF NOT EXISTS-style guards throughout) — re-running an upgrade that partially applied is safe.

Rebuilding after a shared package changes

Because each service compiles from the same monorepo, changing a shared internal package (auth middleware, the event bus, the quota package) affects every service binary, not just one. Always run an unfiltered docker compose build on upgrade — building only the service you think changed can leave other services on stale images that still import the old code.

Zero-downtime considerations

With a single shared PostgreSQL database, additive migrations (new nullable columns, new tables) are safe to apply before the new service code deploys. Destructive changes (dropping columns, tightening constraints) should ship in a follow-up release after the code that stops depending on the old shape is already live.

Rolling back

Docker Compose upgrades roll back by re-deploying the previous image tags; database migrations in this project are additive by convention, so a code rollback rarely requires a matching down-migration.