OrthıD
Start free
Browse the docs
Self-hosting & operations

Upgrade

OrthID upgrades are rolling and zero-downtime by default. Read the changelog, back up, then move one minor version at a time.

A self-hosted OrthID deployment is a Helm release. Upgrading means pulling a newer chart and image, applying any database migrations, and letting Kubernetes roll the pods. This page covers how to do that safely and how to roll back if something looks wrong.

Versioning

OrthID follows semantic versioning as MAJOR.MINOR.PATCH:

  • Patch releases are bug and security fixes. They are always safe to apply and never change the database schema.
  • Minor releases add features and may add backward compatible migrations. Upgrade one minor at a time.
  • Major releases may contain breaking changes to the API or schema. Each one ships a dedicated upgrade guide.

The chart version tracks the application version, so helm search repo orthid tells you what is available.

Read the changelog first

Every release notes its migrations, deprecations and any required config changes. Read the entries between your current version and the target version before you touch the cluster - never skip across a major boundary without reading its guide.

Terminal
# What version am I on?
helm list -n orthid

# What is available?
helm repo update
helm search repo orthid/orthid --versions
Back up before every upgrade
Take a fresh, verified backup before you apply migrations. Minor and patch upgrades are reversible at the pod level, but a migration is not - a backup is your only clean way back. See Backup & restore.

Zero-downtime rolling upgrade

The chart uses a rolling update strategy with readiness probes, so old pods keep serving until new pods are healthy. Pin the target version explicitly rather than upgrading to latest:

Terminal
helm upgrade orthid orthid/orthid \
  --namespace orthid \
  --version 2.7.0 \
  --reuse-values \
  --atomic \
  --timeout 10m

# Watch the rollout
kubectl rollout status deploy/orthid-api -n orthid

--atomic rolls the release back automatically if any pod fails to become ready inside the timeout, so a bad image never takes down the running version. Because tokens are signed by keys that survive the upgrade, in-flight sessions stay valid throughout the roll.

Database migrations

Migrations are versioned and run forward only. The chart can apply them automatically as a pre-upgrade hook, or you can run them as a separate, explicit step - which is recommended in production so the schema change and the rollout are distinct, auditable actions.

Terminal
# Apply pending migrations as a one-off job, then upgrade the app
kubectl exec -n orthid deploy/orthid-api -- orthid migrate up

# Check migration status at any time
kubectl exec -n orthid deploy/orthid-api -- orthid migrate status
Migrations are backward compatible within a minor
Within a minor series, a new schema works with the immediately previous application version. That is what makes the rolling upgrade safe: pods on the old and new versions can both run against the migrated database during the roll.

Rollback

If a release misbehaves, roll the Helm release back to the previous revision. This reverts the application and config; it does not revert the database.

Terminal
# List revisions
helm history orthid -n orthid

# Roll back to the previous revision
helm rollback orthid -n orthid

For a patch or minor upgrade, the migration is backward compatible, so rolling back the app alone is enough. If you must undo a migration - typically only across a major upgrade - restore the database from the backup you took beforehand rather than trying to reverse the schema by hand.

Recommended order

  1. Read the changelog between your version and the target.
  2. Take a verified backup.
  3. Apply migrations as an explicit step.
  4. Run helm upgrade --atomic and watch the rollout.
  5. Smoke-test sign-in, token verification and the API.

Next steps