Docker Compose deployment
Profiles, services, volumes and networks of the OrkStage Compose stack, how the worker starts OpenTofu runners, and what to change before you share it.
docker-compose.yml in the orkstage-dev workspace
runs the whole platform from one shared image, built from the repositories checked out as
submodules. It is the way to evaluate OrkStage and to develop it. For a production host, use the
published images instead. Run the commands on this page from the
orkstage-dev checkout.
Profiles
| Profile | Adds | Shortcut |
|---|---|---|
| (none) | Postgres 18, Redis 8, Mailpit | pnpm local:up (you then run the apps on the host) |
aws-emulator | MiniStack, a local AWS on port 4566 | pnpm local:aws |
platform | migrate, api, worker, web, tofu-runner | pnpm platform:up (also starts aws-emulator) |
observability | An OpenTelemetry collector that prints the telemetry it receives (ports 4317 and 4318) |
docker compose --profile platform --profile aws-emulator up -d --build --waitServices
| Service | Image | Notes |
|---|---|---|
migrate | orkstage/platform:local | Runs once: prisma migrate deploy, then the idempotent seed. The other platform services wait for it. |
api | orkstage/platform:local | Port 4000. Its health check calls /api/v1/readyz, which tests the database and Redis. |
worker | orkstage/platform:local | Runs as root only so it can use the Docker socket to start OpenTofu containers. |
web | orkstage/platform:local | Port 3000. Reaches the API at API_INTERNAL_URL=http://api:4000. |
tofu-runner | orkstage/tofu-runner:local | Built, never left running: OpenTofu 1.12.7 with the modules baked in. |
postgres, redis, mailpit | Upstream images | Data lives in the pgdata and redisdata volumes. |
ministack | ministackorg/ministack (pinned by digest) | Needs the Docker socket. Its state lives in the ministack volume. |
One image (infra/docker/platform.Dockerfile) holds the API, the worker, the console and the
migration tooling. Each service starts it with a different command.
How the worker runs OpenTofu
The worker reaches Docker through /var/run/docker.sock and starts orkstage/tofu-runner:local
containers on the Compose network. These variables wire it up:
| Variable | Value in Compose | Why |
|---|---|---|
TOFU_IMAGE | orkstage/tofu-runner:local | Runner image with the modules baked in. |
TOFU_MODULES_IN_IMAGE | true | Do not mount modules from the worker's filesystem. |
TOFU_WORK_DIR | /var/lib/orkstage/tofu | Location of the working directories inside the worker. |
TOFU_WORK_VOLUME | orkstage-tofu-work | The same directory as a named volume. The Docker daemon cannot see paths inside the worker container, so runners mount the volume instead. |
TOFU_PLUGIN_CACHE_VOLUME | orkstage-tofu-plugins | Provider plugin cache shared by all runners. |
TOFU_DOCKER_NETWORK | orkstage_default | Lets runners reach MiniStack by name. |
Inside the network, MiniStack answers at http://ministack:4566 (AWS_EMULATOR_ENDPOINT). Links in
the console still point to http://localhost:4566.
Names kept on purpose
The Compose project is still named orkstage, the working name of the platform before the
OrkStage rebrand. Keeping it leaves existing volumes and the orkstage_default network
attached.
Before running it beyond your machine
The Compose file is set up for local use. Before other people use the installation, change at least the following.
Production mode
Set NODE_ENV=production and AUTH_DEV_LOGIN_ENABLED=false, and configure an
OIDC provider. In production, the API and the
worker refuse to start while the dev login is enabled.
Secrets
Generate SESSION_SECRET (at least 32 random characters) and ENCRYPTION_KEY (32 bytes, base64:
openssl rand -base64 32). Pass both from your secret store, not from the Compose file. In
production, startup fails without them.
Postgres and Redis
Point DATABASE_URL and REDIS_URL at managed instances, or at instances you back up yourself, and
plan your backups.
TLS and public URLs
Put the console and the API behind a proxy that terminates TLS. Set WEB_PUBLIC_URL and
API_PUBLIC_URL to their https:// addresses. In production mode, cookies are marked Secure.
Remove the emulator
Drop the aws-emulator profile and connect real AWS accounts.
Isolate the runner
The Docker socket gives the worker control of the host's Docker daemon. Run the worker on a dedicated host. A runner based on ECS RunTask or Kubernetes Jobs is on the roadmap.
Published images (ghcr.io/orkstage/platform, ghcr.io/orkstage/console,
ghcr.io/orkstage/tofu-runner) are planned, and so is infrastructure code that runs the control plane
itself on AWS (ECS Fargate, RDS, ElastiCache, ALB). Today you build the images from source.
Production install
Run OrkStage on your own server from the published images, with HTTPS, single sign on, Postgres and Redis, and upgrade it by changing one version number.
Configuration reference
Every OrkStage environment variable with its type, default and effect, from core settings and OIDC to the OpenTofu runner, email, secrets and licensing.