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.
OrkStage does not ship a backup tool for its own control plane yet. You back up the stores it depends on, and this page lists them.
The control plane
| Store | What it holds | How to protect it |
|---|---|---|
| Postgres | Tenants, users, templates, instances, known resource state, deployments, the audit log, webhook secrets (encrypted) and API key hashes | This is the one store you must back up. Use the automated backups and point in time recovery of your managed database, or run pg_dump on a schedule. |
| Redis | Queues, concurrency slots and simulation state | You can lose it. Jobs carry only ids, and deployments resume from Postgres. Persistence (appendonly yes in the Compose file) shortens recovery. |
| OpenTofu state | One state file per AWS resource, in S3 in each customer account | The state bucket must have versioning, so you can restore an earlier version of a state file. |
| Secrets | SESSION_SECRET, ENCRYPTION_KEY, the license key and OIDC client secrets | Keep them in your secret store. If you lose ENCRYPTION_KEY, the stored webhook signing secrets become unreadable, and you must rotate them. |
docker compose exec -T postgres \
pg_dump -U platform -Fc platform > orkstage-$(date +%F).dumpTest your restores. Until you have restored a backup, you do not know that it works.
Recovery
- Restore Postgres to a new database and point
DATABASE_URLat it. - Start the API and the worker with the same
ENCRYPTION_KEYandSESSION_SECRET. If the session secret changed, users must sign in again. - Deployments that were running resume from their persisted steps. OrkStage does not apply converged resources again.
- The health monitor and the drift scan read actual state from the providers again, so the known state catches up with reality.
Instances OrkStage manages
- Templates declare database backups (
backup.enabled, andretentionDaysup to 35). Theproduction-backupspolicy fails any production database without them. On AWS, these settings set the RDS automated backup retention. - The tenant plan caps retention (
backupRetentionDays). - The destroy workflow has a backup phase that checks the backup policy. It does not yet verify that a backup exists and can be restored.
- A backups API (last successful backup, restore to a new instance) is on the roadmap.
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.
Observability
Follow an OrkStage installation through JSON logs with correlation ids, health endpoints, deployment events and the audit log. Metrics and tracing are planned.