Upgrades and migrations
Upgrade OrkStage on your own infrastructure. Rebuild images, apply Prisma migrations, update the OpenTofu runner and move instances to new template versions.
An installation from the published images upgrades by
changing ORKSTAGE_VERSION, pulling and starting again. The procedure below is for the
orkstage-dev Compose stack, built from source.
Platform upgrade
Back up Postgres
Take a database backup first (see Backups and recovery). Migrations only move forward.
Get the new code and rebuild
git pull
docker compose --profile platform buildApply migrations and restart
docker compose --profile platform --profile aws-emulator up -d --waitThe migrate service runs prisma migrate deploy, which applies only pending migrations, then the
idempotent seed, and exits. The api, worker and web services start only after it succeeds. On
an installation without containers, run pnpm db:deploy && pnpm db:seed instead.
Deployments in progress survive a worker restart: BullMQ delivers the job again, and the deployment resumes from its persisted steps. Even so, upgrade while no deployment is running when you can.
Database migrations
Migrations live in packages/database/prisma/migrations. Prisma generates them from
schema.prisma during development (pnpm db:migrate). The append only trigger on the audit table is
part of a migration, so never edit it by hand.
OpenTofu and modules
The runner image pins the OpenTofu version (1.12.7) and contains the modules. To upgrade them,
change TOFU_IMAGE on purpose, or rebuild orkstage/tofu-runner:local. The modules have their own
repository, orkstage-modules, with their own versions. Once its runner image is published, the
platform pins TOFU_IMAGE=ghcr.io/orkstage/tofu-runner:vX.Y.Z, and each change to infrastructure
code becomes a deliberate upgrade.
A module change alters the plan of existing resources. The next deployment of each instance shows the change as a provider plan, and destructive changes in production wait for approval.
Template upgrades
Instances never move to a new template version on their own. Publish the new version, then use Upgrade template on each instance, review the plan and deploy.
Compatibility
The template schema has a version (apiVersion: platform/v1). Changes to the API that break clients
will come with a new /api/v2 route group. After the split, a compatibility matrix in orkstage-dev
will list the tested combination of platform, console, CLI and modules for each release.
Security hardening
Security controls built into OrkStage, a hardening checklist for hosting it yourself, the known gaps and how to report a vulnerability.
Backups and recovery
What to back up when you host OrkStage (Postgres, OpenTofu state, secrets), how to recover, and what OrkStage does for the backups of managed instances.