Upgrading OrcheStack

A single command — ./upgrade.sh — moves an OrcheStack install to the latest release. This page covers what the script does, what survives the upgrade, and how to roll back if something breaks.

The quick path

From inside your runtime install directory (the one that has docker-compose.yml and .env):

cd orchestack-runtime-X.Y.Z
./upgrade.sh

That's it. The script handles everything below. You don't normally need to read the rest of this page unless something goes wrong, or you want to know what's happening under the hood.

Why upgrades have two parts

An OrcheStack release ships in two artefacts, and an upgrade has to pull both:

Docker images — orchestack-auth, orchestack-orchestrator, orchestack-dashboard, orchestack-airflow, orchestack-ge. Pulled with docker compose pull.
The runtime bundle — docker-compose.yml, the per-service compose snippets in services/, Traefik config in traefik/, postgres init SQL in postgres-init/. Lives in the release tarball on GitHub, NOT inside any image.

docker compose pull alone only handles the images. Running it without re-extracting the bundle leaves you on the old compose files, which is how operators have ended up with already-fixed bugs re-appearing after they thought they'd upgraded. The bundled upgrade.sh exists to do both halves correctly in one go.

What `upgrade.sh` does, step by step

Pre-flight check. Verifies it's running from inside an install directory (has docker-compose.yml and .env), and that Docker is running. Bails early with a clear error if not.
Backs up your .env to .env.bak.<timestamp>. Your passwords, repo URLs (with PATs), and custom settings are preserved verbatim.
Downloads the latest release tarball from https://github.com/tripleaceme/orchestack-public/releases/latest/download/orchestack-runtime.tar.gz to a staging directory.
Replaces runtime config files in place: docker-compose.yml, services/, traefik/, postgres-init/, INSTALL.md, VERSION, upgrade.sh itself, and .env.example. Your .env is left alone.
Pulls new Docker images — docker compose pull. Can take several minutes on first pull of heavy images like orchestack-airflow (~2.4 GB).
Restarts the stack — docker compose up -d. Containers recreate against the new images and new compose config.

What survives an upgrade

The upgrade replaces config, never touches state:

Your .env — passwords, repo URLs with PATs, custom variables. All preserved.
The OrcheStack platform database — user accounts, roles, audit log, installed-services registry. Lives in the orchestack-postgres-data Docker volume.
Per-service state — Metabase dashboards, Airflow DAG metadata + connections, dbt project files, MinIO buckets, OpenMetadata catalog. Each lives in its own named Docker volume which the upgrade doesn't touch.
Operator-added files — anything you added to the install directory that the bundle doesn't ship is left alone.

What doesn't survive a fresh-start reinstall

The upgrade itself preserves state. But if you ever need a totally clean install:

docker compose down -v

The -v flag drops every named volume — that wipes the platform DB, every service's state, every credential. Run this only when you intentionally want a from-scratch install. The upgrade script never uses this flag.

Manual equivalent

If you prefer not to run the script (or you're upgrading from a version that didn't ship one), here's what it does in plain Docker commands:

# 1. Back up .env
cp .env /tmp/orchestack-env.bak

# 2. Download the latest runtime bundle
curl -fsSL -o /tmp/runtime.tar.gz \
  https://github.com/tripleaceme/orchestack-public/releases/latest/download/orchestack-runtime.tar.gz

# 3. Extract to staging
tar xzf /tmp/runtime.tar.gz -C /tmp

# 4. Replace runtime config files
cp /tmp/orchestack-runtime-*/{docker-compose.yml,INSTALL.md,upgrade.sh,VERSION,.env.example} ./
cp -R /tmp/orchestack-runtime-*/services/. ./services/
cp -R /tmp/orchestack-runtime-*/traefik/. ./traefik/
cp -R /tmp/orchestack-runtime-*/postgres-init/. ./postgres-init/
chmod +x ./upgrade.sh

# 5. Pull new images + restart
docker compose pull
docker compose up -d

Verifying the upgrade

After the script completes, give the control plane ~30 seconds to settle, then check:

Version — cat VERSION should show the new release.
Control plane health — docker ps --filter "name=orchestack" --format "{{.Names}}: {{.Status}}". Every orchestack-* container should report healthy or Up (Traefik shows just Up — it has no healthcheck).
Dashboard loads — visit http://localhost/app/ and sign in with your existing operator account. The platform DB is preserved, so your account works as before.
Services start — Open a previously-running service from the dashboard. The compose snippets for managed services were updated as part of the bundle, so any fixes in service config take effect on the next start.

Versioning

OrcheStack follows semantic versioning (MAJOR.MINOR.PATCH). Operator-facing images use :latest in .env.example by default — every release re-tags :latest in addition to the semver tag, so an upgrade naturally moves you to the latest published release of the line you're on. If you need to pin to a specific version, set AUTH_TAG, ORCHESTRATOR_TAG, DASHBOARD_TAG, AIRFLOW_TAG, and GE_TAG in your .env to the semver string (e.g. AIRFLOW_TAG=0.1.1).

Release notes for every version are at github.com/tripleaceme/orchestack-public/releases. The CHANGELOG covers every fix and change in detail. Read both before upgrading across MINOR or MAJOR boundaries — PATCH upgrades within a MINOR are designed to be drop-in.

Rollback

If the upgrade breaks something, you have two recovery paths.

Roll back images only (config breaking change)

If the new image is the culprit but the new compose config is fine, pin the image tags in .env to the previous version:

AUTH_TAG=0.1.0
ORCHESTRATOR_TAG=0.1.0
DASHBOARD_TAG=0.1.0
AIRFLOW_TAG=0.1.0
GE_TAG=0.1.0

Then docker compose pull && docker compose up -d. The platform DB and volumes are unchanged, so your data + accounts come back as they were.

Full rollback (re-extract a prior bundle)

If the new compose config is incompatible with your setup, you need to put the old bundle back:

# 1. Download the prior release's bundle (replace X.Y.Z with the version you want)
curl -fsSL -o /tmp/runtime-old.tar.gz \
  https://github.com/tripleaceme/orchestack-public/releases/download/vX.Y.Z/orchestack-runtime.tar.gz

# 2. Extract over the install dir
tar xzf /tmp/runtime-old.tar.gz -C /tmp
cp /tmp/orchestack-runtime-X.Y.Z/docker-compose.yml ./
cp -R /tmp/orchestack-runtime-X.Y.Z/services/. ./services/

# 3. Restore the .env image-tag pins (Edit .env and set every *_TAG to vX.Y.Z)
# 4. Pull + restart
docker compose pull
docker compose up -d

Rollbacks are uncommon — PATCH releases are explicitly designed to be drop-in safe. If you've rolled back, please open an issue with the version pair and what broke, so we can fix it for the next release.

Before any MAJOR upgrade, take a backup

PATCH and MINOR upgrades within the same MAJOR are designed to be drop-in safe. MAJOR upgrades (1.x → 2.x, etc.) may include irreversible schema migrations to the platform DB.

Always take a backup before a MAJOR upgrade — see Backup & restore for the procedure.

← Previous Backup & restore Next Troubleshooting →