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 orchestrator folder: the image tarball (or registry access), docker-compose.core.yml, deploy/caddy/Caddyfile, .env.example, core-schema.sql, and the backup.ps1, restore.ps1 and compose-common.ps1 scripts. Verify the files against SHA256SUMS.
  • 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#

BashCopy
sudo 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.

.envINICopy
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#

BashCopy
docker 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:

BashCopy
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#

BashCopy
docker 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#

  1. Change the bootstrap administrator's password (avatar ▸ Security). See Sign in and secure your account.
  2. Open the app launcher ▸ Admin and select Create tenant. The tenant's short name becomes part of every URL in it. See Platform administration.
  3. In the tenant, create a workspace and invite your first users. See Workspaces and tenants and Manage access.
  4. Remove the three VELOPHEX_BOOTSTRAP_* lines from .env and run docker compose -f docker-compose.core.yml up -d api.

Verify#

BashCopy
curl -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