Install on-premises
Deploy the Orchestrator on your own Linux host with Docker Compose, TLS and your first tenant.
This guide installs the Orchestrator on one Linux host with Docker Compose. The stack runs four containers: Caddy (TLS and WebSockets), the Orchestrator (api), PostgreSQL 18 and Redis. All images are pinned by digest.
Just evaluating?
To try the platform on a Windows developer machine with Docker Desktop, run .\build\Start-Evaluation.ps1 from a checkout. It builds the image, generates secrets, starts the stack on https://localhost:8443, creates a tenant, a workspace and a machine, and prints an enrollment command. Its output is not fit for production: it uses a development certificate and writes the administrator password to .env.
Prerequisites#
- A Linux x86-64 host with at least 4 vCPU, 8 GB RAM and 40 GB of disk, plus room for the packages you will publish.
- Docker Engine 27 or later with Compose v2 (
docker compose version). - A DNS name for the Orchestrator, for example
orchestrator.example.com, pointing at the host. - TCP 443 open to users, Studio and every Robot. For an automatic Let's Encrypt certificate, TCP 80 must also be reachable from the internet.
- Outbound SMTP from the host, for invitation and password reset mail.
- The release's
orchestratorfolder: the image tarball (or registry access),docker-compose.core.yml,deploy/caddy/Caddyfile,.env.example,core-schema.sql, and thebackup.ps1,restore.ps1andcompose-common.ps1scripts. Verify the files againstSHA256SUMS. - A secret escrow for the keys you generate in step 2 (a password manager vault with two-person access, or similar).
Steps#
1. Prepare the deployment directory#
BashCopysudo mkdir -p /srv/velophex && cd /srv/velophex
cp /path/to/release/docker-compose.core.yml .
mkdir -p deploy/caddy && cp /path/to/release/deploy/caddy/Caddyfile deploy/caddy/
cp /path/to/release/.env.example .env
chmod 600 .env
Keep the Caddyfile at deploy/caddy/Caddyfile next to the compose file. If you received the image as a tarball, load it with docker load -i velophex-orchestrator-<version>.tar.
2. Fill in .env#
Generate secrets with openssl rand -base64 32 (or 24 for passwords). Compose refuses to start while a required value is missing.
VELOPHEX_IMAGE=velophex/orchestrator:<version>
VELOPHEX_POSTGRES_DB=velophex_orchestrator
VELOPHEX_POSTGRES_USER=velophex
VELOPHEX_POSTGRES_PASSWORD=<generated>
VELOPHEX_REDIS_PASSWORD=<generated>
VELOPHEX_PUBLIC_BASE_URL=https://orchestrator.example.com
VELOPHEX_SITE_ADDRESS=orchestrator.example.com
VELOPHEX_TOKEN_PEPPER=<generated>
VELOPHEX_KEK=<generated>
VELOPHEX_KEK_ID=k1
VELOPHEX_EMAIL_MODE=Smtp
VELOPHEX_EMAIL_FROM=no-reply@example.com
VELOPHEX_SMTP_HOST=smtp.example.com
VELOPHEX_SMTP_PORT=587
VELOPHEX_SMTP_ENABLE_SSL=true
VELOPHEX_SMTP_USERNAME=<user>
VELOPHEX_SMTP_PASSWORD=<password>
VELOPHEX_BOOTSTRAP_ADMIN_USERNAME=admin
VELOPHEX_BOOTSTRAP_ADMIN_EMAIL=you@example.com
VELOPHEX_BOOTSTRAP_ADMIN_PASSWORD=<strong password>
| Variable | Purpose |
|---|---|
VELOPHEX_IMAGE |
The released image tag. |
VELOPHEX_POSTGRES_* |
Database name, user and password. The password applies only when the volume is first created. |
VELOPHEX_REDIS_PASSWORD |
Redis runs with a required password. |
VELOPHEX_PUBLIC_BASE_URL |
The HTTPS origin users and Robots reach. |
VELOPHEX_SITE_ADDRESS |
The host name Caddy serves and gets a certificate for. |
VELOPHEX_TLS |
Optional: tls internal, or tls /certs/tls.crt /certs/tls.key for your own certificate. |
VELOPHEX_HTTP_PUBLISH, VELOPHEX_HTTPS_PUBLISH |
Host ports Caddy publishes (default 80 and 443). |
VELOPHEX_TRUSTED_PROXY_NETWORK |
The network the API trusts X-Forwarded-* headers from. Defaults to the stack's own network. |
VELOPHEX_TOKEN_PEPPER |
HMAC key for every stored token hash. Changing it invalidates all tokens. |
VELOPHEX_KEK, VELOPHEX_KEK_ID |
Key-encryption key that wraps every tenant's data key, and its id. |
VELOPHEX_HTTP_BIND |
Loopback address the API listens on (default 127.0.0.1:8080). |
VELOPHEX_EMAIL_*, VELOPHEX_SMTP_* |
Outbound mail. VELOPHEX_EMAIL_MODE=Log writes mail to the log instead, for commissioning only. |
VELOPHEX_BOOTSTRAP_ADMIN_* |
The first platform administrator, created on first start. |
VELOPHEX_ORG_SIGNER_THUMBPRINT |
Optional: your package-signing certificate's SHA-256 thumbprint, shown as trusted. |
VELOPHEX_OTLP_ENDPOINT |
Optional: OTLP endpoint for traces and metrics. |
VELOPHEX_*_MEMORY_LIMIT |
Optional container memory ceilings. |
Escrow the KEK and token pepper now
VELOPHEX_KEK protects every stored asset and credential. If you lose it, those secrets cannot be recovered and your backups contain only ciphertext. Put VELOPHEX_KEK, VELOPHEX_KEK_ID and VELOPHEX_TOKEN_PEPPER in your escrow before any tenant stores a credential.
Other configuration keys (for example storage or Kestrel limits) go in an optional velophex.prod.env file next to the compose file, as Section__Key=value lines.
3. Pull the images#
BashCopydocker compose -f docker-compose.core.yml pull
4. Apply the database schema#
The Orchestrator never changes its schema on start. Apply the release's idempotent core-schema.sql before the first start and before every upgrade:
set -a; . ./.env; set +a
docker compose -f docker-compose.core.yml up -d postgres
docker compose -f docker-compose.core.yml exec -T postgres \
psql -U "$VELOPHEX_POSTGRES_USER" -d "$VELOPHEX_POSTGRES_DB" -v < core-schema.sql
To use a managed PostgreSQL 18 instead of the container, allow the pg_trgm extension, set Database__ConnectionString in velophex.prod.env, scale the postgres service to zero, and run the script against your server.
5. Choose how TLS works#
| Your host name | What to set |
|---|---|
| Public and resolvable, port 80 reachable | Nothing. Caddy obtains and renews a Let's Encrypt certificate. |
| Internal name | VELOPHEX_TLS=tls internal, then trust Caddy's root certificate (in the velophex_orchestrator_caddy_data volume under /data/caddy/pki) on every client and Robot machine. |
| Your own certificate | Mount it into the Caddy container and set VELOPHEX_TLS=tls /certs/tls.crt /certs/tls.key. |
Keep the Caddy data volume. Losing it on every restart eventually hits Let's Encrypt rate limits.
Using your own load balancer
Start without Caddy (docker compose -f docker-compose.core.yml up -d postgres redis api) and point your proxy at VELOPHEX_HTTP_BIND. Your proxy must then: forward WebSocket upgrades on /api/v1/robot/gateway and /hubs/*; use an idle timeout far above the 15-second heartbeat (an hour is reasonable); disable response buffering on those routes; pass the original Host and set X-Forwarded-For and X-Forwarded-Proto; allow request bodies of at least 512 MB; and prefer client affinity for the gateway. Set VELOPHEX_TRUSTED_PROXY_NETWORK to your proxy's network in CIDR form (a single machine is its address as /32). The API refuses to start without a trusted proxy network.
6. Start the stack#
BashCopydocker compose -f docker-compose.core.yml up -d
docker compose -f docker-compose.core.yml logs -f api
The first log lines show the environment, the built-in VeloPhex package signer, and the bootstrap administrator being created.
7. Choose where package files are stored#
Sign in at https://orchestrator.example.com as the bootstrap administrator. On first sign-in, /setup asks where to store package files:
| Provider | Needs |
|---|---|
| Local folder | The velophex_orchestrator_data volume (default). Good for a single host. |
| S3-compatible (AWS S3, MinIO, Cloudflare R2, Wasabi, Ceph) | A bucket, a region or endpoint, and the container's IAM role or an access key. Most self-hosted stores need path-style addressing. |
| Azure Blob Storage | A container, and a managed identity with Storage Blob Data Contributor plus the account URL, or a connection string. |
Select Test connection; you can continue only after it passes. The provider cannot change once blobs are stored. To fix the choice in configuration instead, set Storage__Provider (fileSystem, s3 or azureBlob) and the matching Storage__S3__* or Storage__Azure__* keys; put secrets such as Storage__S3__SecretAccessKey in velophex.prod.env.
8. Create the first tenant#
- Change the bootstrap administrator's password (avatar ▸ Security). See Sign in and secure your account.
- Open the app launcher ▸ Admin and select Create tenant. The tenant's short name becomes part of every URL in it. See Platform administration.
- In the tenant, create a workspace and invite your first users. See Workspaces and tenants and Manage access.
- Remove the three
VELOPHEX_BOOTSTRAP_*lines from.envand rundocker compose -f docker-compose.core.yml up -d api.
Verify#
BashCopycurl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health/ready
You should see 200. In a browser, you should see the sign-in page at your public URL with a valid certificate, and after sign-in, your tenant and workspace. Then add a machine and enrol a Robot and run one job.
Next steps#
Prerequisites
Steps
1. Prepare the deployment directory
2. Fill in .env
3. Pull the images
4. Apply the database schema
5. Choose how TLS works
6. Start the stack
7. Choose where package files are stored
8. Create the first tenant
Verify
Next steps