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.
The deploy folder of the orkstage
repository runs OrkStage from the published images on one host with Docker Compose: the platform
image (Control API, worker, migrations and console) and the OpenTofu runner image, both from
ghcr.io/orkstage, behind Caddy for HTTPS.
First release pending
The images are published when a version is tagged. Until the first release, build them from the
orkstage-dev workspace.
What you need
- A Linux host with Docker Engine and Compose v2, 2 vCPU and 4 GB of memory at least, used only by OrkStage: the worker starts OpenTofu containers through the Docker socket, which gives it control of the host's Docker.
- A host name that points to it, with ports 80 and 443 open (Caddy gets the certificate from Let's Encrypt).
- An OIDC provider for sign in, such as Microsoft Entra ID, Google or Keycloak. Production has no development login.
- An SMTP server for invitations and notifications.
Install
Get the files
mkdir orkstage && cd orkstage
for f in compose.yaml Caddyfile .env.example; do
curl -fsSLO "https://raw.githubusercontent.com/orkstage/orkstage/main/deploy/$f"
done
cp .env.example .envFill in .env
| Setting | Value |
|---|---|
ORKSTAGE_VERSION | The release to run, for example 0.1.0. |
ORKSTAGE_DOMAIN | The host name, for example orkstage.example.com. |
POSTGRES_PASSWORD | Letters and digits, for the bundled Postgres. |
SESSION_SECRET, ENCRYPTION_KEY | openssl rand -base64 32 for each. Keep a copy of the encryption key with your backups. |
PLATFORM_OWNER_EMAIL | Your email: your first sign in with it makes you the platform owner. |
OIDC_<NAME>_ISSUER, _CLIENT_ID, _CLIENT_SECRET | One set per sign in provider. Register https://<domain>/api/v1/auth/oidc/<name>/callback as the redirect URL. |
SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM | Your mail server. |
ORKSTAGE_LICENSE_KEY | Only with an Enterprise subscription. |
To use managed Postgres and Redis, remove COMPOSE_PROFILES=bundled and set DATABASE_URL and
REDIS_URL. Every other setting is in Configuration.
Start
docker compose up -d --waitThe migrate service applies the database migrations and the production seed (the built in
templates, the organization and the platform owner, never demo data), then the API, the worker
and the console start. Open https://<domain> and sign in.
Connect a cloud and create a profile
Register a cloud target for each account, then a profile per environment, and mark the defaults.
Upgrade
# after a backup of Postgres (see Backups and recovery)
sed -i 's/^ORKSTAGE_VERSION=.*/ORKSTAGE_VERSION=0.2.0/' .env
docker compose pull
docker compose up -d --waitmigrate applies only the pending migrations before the new API and worker start. Migrations move
forward only, so restoring the backup is the way back. Read the release notes first; see
Upgrades and migrations.
Verify the images
Every image is signed with cosign (keyless, from the release workflow) and carries an SBOM and build provenance:
cosign verify ghcr.io/orkstage/platform:0.1.0 \
--certificate-identity-regexp '^https://github.com/orkstage/orkstage-dev/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
docker buildx imagetools inspect ghcr.io/orkstage/platform:0.1.0 --format '{{ json .SBOM }}'Architecture
The OrkStage components (console, Control API, worker, Postgres, Redis), the path from template to cloud, the deployment workflow and provider adapters.
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.