Upgrades

Orbtrace upgrades are deliberately boring: pull the new image, restart, and the schema migrations run themselves. The discipline that keeps them boring is back up first and read the release notes for the version you're jumping to.

Before any upgrade

1. Back up PostgreSQL (and Doris if you keep history) — see Backup & restore. This is your rollback path.
2. Read the changelog for the target version. Breaking changes (a Doris major bump, a removed setting, a values rename) are called out there.
3. Pin the exact version you're moving to rather than latest, so every node lands on the same build.

What migrates automatically

• PostgreSQL schema — Flyway runs any new V* migrations at startup. Migrations are forward-only: a newer Orbtrace can read an older database, but not vice versa. This is why rollback means restoring a backup, not just re-deploying the old image.
• Doris schema — the migration runner (in apply mode) applies any new telemetry-schema changes before the server reports ready. In validate mode it verifies instead, and a DBA applies the change out of band.

The server doesn't bind its port until both finish, so a healthy server after upgrade means the migrations succeeded.

Docker Compose

# 1. back up (see Backup & restore)
# 2. pin the new version
export ORBTRACE_VERSION=vX.Y.Z          # in your .env
# 3. pull and recreate just the app
docker compose pull orbtrace
docker compose up -d orbtrace
# 4. watch it come back healthy
docker compose ps
docker compose logs -f orbtrace

Storage containers (Doris, Postgres, Valkey) only need recreating when a release note says so. The first boot on the new version may take longer than usual while migrations run.

Kubernetes (Helm)

helm upgrade orbtrace oci://ghcr.io/nivorbit/charts/orbtrace \
  -n orbtrace -f my-values.yaml --version <chart-version>
kubectl -n orbtrace rollout status deploy/orbtrace-app

The Deployment rolls pods one at a time; the readiness probe holds traffic off a pod until its migrations are done. Review the chart's values.yaml diff between versions for any renamed keys before you upgrade (the chart calls renames out in its Chart.yaml upgrade note).

Ansible

Bump the pinned version in your inventory/vars, then re-run the playbook — it's idempotent and will pull the new image and recreate the stack via the systemd unit:

ansible-playbook -i inventory.ini site.yml --ask-vault-pass

Rolling back

Because PostgreSQL migrations are forward-only, rollback is restore, not downgrade:

1. Re-deploy the previous Orbtrace version (the old image tag / chart version).
2. Restore the PostgreSQL backup you took before the upgrade.
3. If the upgrade also migrated Doris in an incompatible way, restore the Doris snapshot too.

Then point your Collector back and verify. This is why step 1 of every upgrade is a fresh backup.

Major Doris version cut-overs

A Doris major version change (e.g. 3.x → 4.1) is a one-way cut-over: 4.1 metadata is not readable by 3.x. These are rare and always flagged in the changelog with a dedicated migration note. Treat them as a planned maintenance window, not a routine docker compose pull.

Next: Security hardening.