Upgrading
Upgrade Ory versions, zero-downtime deploy patterns, and rollback.
Upgrading
Release cadence
| Component | Cadence | Breaking-change policy |
|---|---|---|
| Avnology gateway + web + docs | Monthly minor, quarterly major | 6-month deprecation on breaking API changes |
| Ory stack (Kratos, Hydra, Keto, Oathkeeper) | Pinned per Avnology release; upgraded in lockstep | See per-release notes |
| Polis (SCIM) | Pinned per Avnology release | Usually no breaking changes |
| Postgres | LTS (17 today) for 5 years | You control the upgrade -- see below |
Monthly minor upgrade
cd avnology-id
git
Traefik re-labels containers and rolls service-by-service. Gateway, audit, risk, webhook, saml, web, docs are all stateless and roll with zero request loss. Ory components get a 30s blue-green via the start_period health check.
Major version upgrade
Read CHANGELOG.md between your current tag and target tag for breaking changes. A typical major upgrade adds one or two migrations and potentially requires an env var rename.
# 1. Snapshot the DB
docker compose exec postgres pg_dump -U avnology -Fc avnology \
> pre-upgrade-$(git describe --tags).dump
# 2. Pull the new release
git fetch --tags && git checkout v2.0.0
# 3. Diff env vars
diff .env.example .env.production
# apply any renames the changelog calls out
# 4. Roll
Ory upgrade cadence
Avnology pins Ory versions in the compose file. Do not independently bump an Ory image tag -- the pinned combination of Kratos / Hydra / Keto / Oathkeeper is tested together.
When a critical Ory CVE drops between Avnology releases, Avnology publishes a patch release within 5 business days pinning the new Ory tag. See Security for the vulnerability disclosure process.
Hydra secret rotation
HYDRA_SYSTEM_SECRET encrypts Hydra session cookies and refresh tokens. Rotate yearly. Hydra supports multi-value secrets for graceful rollover:
# Short window (5 minutes) with both secrets accepted:
HYDRA_SYSTEM_SECRET: "new-secret-hex,old-secret-hex"After the rollover window, drop the old secret:
HYDRA_SYSTEM_SECRET: "new-secret-hex"Kratos has an identical pattern with KRATOS_COOKIE_SECRET (but use single-value unless documented otherwise by an Avnology release).
Postgres major upgrade
Postgres 17 -> 18 example:
- Snapshot with pg_dump.
- Stop the stack.
- Swap
image: postgres:17-alpineforpostgres:18-alpinein the compose file. - Remove the postgres_data volume (
docker volume rm avnology_postgres_data). - Start postgres alone:
docker compose up -d postgres. - Restore from dump:
pg_restore -U avnology -d avnology /tmp/snapshot.dump. - Bring rest of stack up.
Rollback
If the new version breaks:
git checkout v1.X-1.0 # the previous tag
docker compose -f docker-compose.traefik.yml pull
docker compose -f docker-compose.traefik.yml up -dIf the upgrade included DB migrations that are not backward-compatible with the older code, restore from the pg_dump you took in step 1.
Zero-downtime patterns
For production deployments where seconds of downtime matter:
- Two Avnology stacks behind a separate load balancer. Run v1.X on stack A while you roll stack B to v1.X+1. Flip LB traffic once B is healthy. Share Postgres + Valkey + MinIO.
- Kubernetes. Helm chart tracked for post-v1.0. Follow a standard rolling update with a two-replica gateway once the chart ships.