Deploying

The shape of a deployment

One Linux box:

                    DNS: wildcard A record  *.example.com  ->  box
                                    |
   +-------------------------------- Caddy (:80/:443) --------------------------------+
   |  admin.example.com   -> static admin panel  (+ same-origin /api proxy)           |
   |  api.example.com     -> control API :8080   (API key required)                   |
   |  *.example.com       -> gateway :8081       (Host -> route table -> workload)    |
   |  /w/<key>            -> gateway :8081       (subroute fallback, no DNS needed)   |
   +---------------------------------------------------------------------------------+
                                    |
                        orchd (systemd) + Docker + gVisor

The control API and the gateway both bind to loopback; Caddy is the only listener on a public port. That keeps TLS, HTTP/2 and certificate storage out of the orchestrator, and means a misconfigured firewall cannot expose the control plane directly.

Everything that runs on the box is tracked in the repository under deploy/ — the Caddyfile, both systemd units, and the scripts — so the server holds no untracked code. The only things that live only on the box are the API key file and the tenant data.

What is where

Docker, gVisor (runsc) and the Caddy binary are installed by the bootstrap script from upstream, not tracked as files.

Provisioning a fresh box

# 1. sync files up (the daemon may not start yet — expected)
deploy/deploy.sh root@HOST || true

# 2. install Docker, gVisor and Caddy; generate the key; build images; start services
ssh root@HOST 'bash -s' < deploy/bootstrap.sh

Then point DNS at the box — one wildcard A record covers every workload subdomain — and the first HTTPS request to each host triggers certificate issuance, gated by /internal/tls-allow.

deploy/preflight.sh checks a box's prerequisites before you commit to it.

Deploying updates

deploy/deploy.sh root@HOST

Builds the daemon for linux/amd64, syncs configs, static files and image sources, restarts the daemon, and reloads Caddy in place. Tenant containers keep running across a restart and are re-attached — a deploy is not a fleet-wide outage.

It does not rebuild workload images. If a Dockerfile changed, rebuild it on the box (or build in CI and push to a registry, then pull from the Images page).

deploy/build-template.sh <path> [--push] builds a template's per-workspace images from its manifest — the scripted equivalent of the built image flow.

Recommended production settings

• State store: ORCHD_STATE_SQLITE=<data>/orchd.db. Atomic and crash-safe; the JSON file default is fine for development but SQLite is the right answer for a single box. An existing projects.json beside it is migrated on first boot.
• Backups: point the target at S3/R2 from Settings, and set ORCHD_BACKUP_INTERVAL. On-box backups are not off-box durability.
• API key: always set ORCHD_API_KEY_FILE. With no key the API is open.
• Rate limit: set ORCHD_RATE_LIMIT to something finite.
• Isolation: leave ORCHD_DOCKER_RUNTIME=runsc unless you have measured that you need runc's syscall performance more than you need the boundary.
• Idle timeout: the default 5 minutes is a reasonable start; workloads that must not cold-start get keep_warm.

Environment reference

Every setting is an environment variable; there is no config file.

Listeners and addressing

Substrate

Lifecycle and limits

State, data and templates

Backups and telemetry

Backup target, event webhook, metrics sink, registry prefix, instance name and templates are runtime settings, changed from the panel or PUT /v1/settings/* with no redeploy. See Adaptors.

Operating notes

• Health: GET /healthz is the only unauthenticated status endpoint and never requires a key.
• Fleet snapshot: GET /v1/info reports the driver, region, base domain, idle timeout, default limits, rate limit, backup and metrics status, and the preset list — the fastest way to confirm what a box is actually running.
• Instance name: PUT /v1/settings/name names the deployment in the panel. ORCHD is the engine; the name is per instance.
• Upgrades: the daemon restarting does not stop tenant containers, so a rolling deploy.sh is safe. Changing resource caps applies to containers created afterwards.