Upgrading

Before#

1. Read the release notes on GitHub releases for migration notes and changed environment variables.
2. Back up PostgreSQL and object storage (Backups).
3. Confirm the new images exist in your registry for every service you run.

Order#

1. Migrate — run the worker image with SPRING_PROFILES_ACTIVE=migrate (or, in compose, let the worker migrate at startup). Wait for exit code 0.
2. Worker — roll the worker Deployment. New workers register collections and pick up the migrated schema.
3. Gateway, auth, ai, mcp — roll the remaining services; they are independent of each other.
4. UI — roll last so the app never calls an endpoint the backend does not have yet.

Native images start in milliseconds, so rolling updates are quick; keep at least two replicas of gateway and worker to avoid a gap.

Compatibility notes#

• Redis holds caches, counters and revocation sets; flushing it logs everyone’s cached identity out for a few minutes but loses nothing durable. Do not flush during business hours if you can avoid it.
• NATS JetStream streams are created if absent; existing streams are not modified — read release notes for stream changes.
• Cerbos policies are regenerated by the worker on start; no manual step.
• A rebuilt UI requires a fresh browser load; the PWA updates itself on the next visit.

After#

• curl …/actuator/health/liveness on gateway, worker and auth.
• Sign in; open Setup → Platform → System health and Monitoring → Health.
• kelta collections list; run a flow; open a record page.
• Update clients: kelta update; regenerate SDK types with kelta sdk types if collections changed.

Rolling back#

Migrations are forward-only. To roll back a release, redeploy the previous images and restore the database from the pre-upgrade backup if the release included a migration. A release without migrations can be rolled back by redeploying previous images alone.