OrkStageOrkStage

Quickstart

Run the full OrkStage platform locally with Docker Compose, sign in with the development login and deploy your first instance in about ten minutes.

This guide runs everything in containers: the API, the worker, the console, Postgres, Redis, a mail catcher, the OpenTofu runner image and MiniStack (a local AWS emulator). Docker is the only requirement. You need no cloud account and no Node.js on the host.

Local evaluation only

The compose stack runs with NODE_ENV=development. The development login is on, cookies are not Secure, and the worker mounts the Docker socket to start OpenTofu containers. Do not expose this stack to a network. For production, see Docker Compose deployment and Security hardening.

Requirements

  • Docker Engine or Docker Desktop with Compose v2, and about 6 GB of free memory for the full stack. MiniStack starts real containers for RDS, ElastiCache and ECS tasks.
  • These free ports: 3000 (console), 4000 (API), 4566 (MiniStack), 5432 (Postgres), 6379 (Redis), 1025 and 8025 (Mailpit).

Run the platform

Get the code

git clone --recurse-submodules https://github.com/orkstage/orkstage-dev.git
cd orkstage-dev

orkstage-dev is the workspace that brings the repositories together as git submodules: the control plane, the console, the CLI, the OpenTofu modules and this site.

Start the stack

docker compose --profile platform --profile aws-emulator up -d --build --wait

The first run builds two images from the submodules:

  • orkstage/platform:local, shared by the API, the worker, the console and the migrate job.
  • orkstage/tofu-runner:local, which contains OpenTofu 1.12.7 and the OpenTofu modules.

The migrate job runs once. It applies the database migrations, loads the demo data and exits. Running it again is safe: the seed updates existing records instead of duplicating them.

If you have pnpm installed, pnpm platform:up runs the same command.

Open the console

ServiceURL
Consolehttp://localhost:3000
Control API and OpenAPI UIhttp://localhost:4000/api/docs
MiniStack (local AWS)http://localhost:4566
Mailpit (emails)http://localhost:8025

Sign in with the development login. The seed creates three users:

EmailRole
admin@example.localPlatform owner: full access, including cloud targets and settings
operator@example.localPlatform operator: deploys, approves and manages incidents
customer@example.localCustomer owner of the tenant Acme Corp

Deploy the reference instance

The seed registers simulated AWS, Azure and OCI targets and an instance called Acme Production, built from the multicloud-reference template. Its API runs on simulated AWS ECS Fargate behind an ALB, with ECR and Route 53. Its Postgres database runs on simulated Azure Flexible Server, and its object storage on simulated OCI.

  1. Open Instances, then Acme Production.
  2. Open the Plan & cost tab. It shows the resolved resources grouped by provider, the policy results, the links between clouds and the approximate monthly cost.
  3. Click Deploy. Acme Production is a production instance, so the deployment includes an approval step. The step is skipped, with a recorded reason, when the plan has no high risk or destructive changes.
  4. Follow the steps and the event log as they update, or open Deployments for the timeline.

Try the operations loop

On a resource of a simulated instance, open Simulate and choose Mark unhealthy. Within one health check interval (30 seconds in the compose file), the instance becomes degraded, an incident opens, an email arrives in Mailpit and the private status page changes. Choose Mark healthy and the incident resolves on its own.

Deploy real AWS resources locally

The seed also creates the target Local AWS (MiniStack) and the instance Acme Staging (local AWS), built from starter-standard. That instance contains a VPC, ECR, an ALB, RDS Postgres, Valkey, SQS, two ECS Fargate services, Route 53 and ACM. Deploying it runs OpenTofu for real against MiniStack. Continue with Local AWS with MiniStack.

Logs, rebuilds and shutdown

# follow the platform services
docker compose --profile platform --profile aws-emulator logs -f api worker web

# rebuild after code changes
docker compose --profile platform build
docker compose --profile platform --profile aws-emulator up -d

# stop (volumes are kept; add -v to wipe all data)
docker compose --profile platform --profile aws-emulator down

Alternative: run the apps on the host

For hot reload during development, run only the infrastructure in Docker. Run the apps on the host with Node.js 24 and pnpm 12, from the orkstage-dev checkout:

pnpm bootstrap                # git hooks, installs and builds
pnpm local:up                 # Postgres, Redis, Mailpit
cp orkstage/.env.example orkstage/.env
pnpm db:deploy && pnpm db:seed
pnpm dev                      # API on http://localhost:4000/api/docs and the worker
pnpm dev:console              # console on http://localhost:3000, in a second terminal

See Development setup for details.

Next steps

Core concepts

The vocabulary used across these docs.

Create an instance

Go through the six steps of the instance wizard, from tenant to review.

Connect an AWS account

Deployment role with an external id, state bucket and validation.

Edit on GitHub

Introduction

OrkStage is an open source multicloud control plane. Define an environment once, place each resource on a cloud, review the plan and deploy with OpenTofu.

Choose a setup

Three ways to run OrkStage end to end, from a laptop with no cloud account to a production install with every provider, and the steps for each.

On this page

RequirementsRun the platformGet the codeStart the stackOpen the consoleDeploy the reference instanceTry the operations loopDeploy real AWS resources locallyLogs, rebuilds and shutdownAlternative: run the apps on the hostNext steps