Upgrading the hub

The short version

1. Take a backup first — backup-restore.md. Migrations are forward-only; the backup IS the rollback.
2. Point at the new image and restart:
3. selfhost: set LUMNIK_VERSION in .env (or pull latest), then deploy/selfhost/up.sh — compose recreates the hub container.
4. Helm: bump hub.image.tag, helm upgrade.
5. Flyway migrates at boot. The startup probe allows ~150s; watch docker compose -f docker-compose.selfhost.yml logs -f hub until healthy.

Rules the migrations follow

• One shared Flyway version namespace across core, connector and platform (they run in a single session) — a release never reuses a number.
• Forward-only: there are no down-migrations. Rolling back = restoring the pre-upgrade backup (and losing writes made since — hence step 1).

If the boot fails mid-migration

Flyway stops at the failing version; the hub never reports ready and old data is untouched by later migrations. Capture logs hub, restore the backup if you need service back immediately, and report the failing version.

Known scar

Changing the public origin (TLS façade hostname, port, issuer path) during an upgrade orphans JIT identities — see the scar note in backup-restore.md.