Control Plane Deployment

The TurboPanel instance is the control plane API. It runs as Deno on self-hosted hosts (Unix socket + Caddy) or on Cloudflare Workers for TurboPanel High Availability. The Expo UI is served by Caddy (static export or dev proxy) or Workers assets.

Overview

Purpose

• Centralized API for organizations, servers, auth, and daemon orchestration
• Web UI (Expo web) for operators
• WebSocket hub for remote daemons (/ws/daemon/v1)
• OpenAPI + Scalar at /api/openapi.json and /api/reference

Relationship to daemon

On the control plane host, a co-located daemon installs and updates the instance, Caddy, UI, and Postgres via Ansible. Additional servers run a standalone daemon that connects back over WSS. See Daemon setup.

Architecture (self-hosted)

Deployment models

Control-plane TLS modes

Self-hosted Caddy TLS is selected by turbopanel_tls_mode (Ansible extra-var; default self_signed). The Platform CA is still minted in every mode.

TURBOPANEL_TLS_PUBLIC=1 (set automatically in lets_encrypt, or when turbopanel_tls_public is true) makes the Deno CA route 404 so daemons use the system trust store, and install commands omit --insecure-tls even on a non-443 port.

Installation paths

Pick the path that matches your goal — they do not substitute for one another. See Installation for the full decision guide.

Contributor development (available today)

For engineers working on TurboPanel source — not production self-hosted or TurboPanel High Availability.

vagrant up
vagrant ssh
dev/console

Services on a contributor dev host:

See Local development. Logs: journalctl -u turbopanel-instance -u turbopanel-caddy -u turbopanel-ui -u turbopaneld -f

Self-hosted control plane (private alpha — preview)

The same turbopanel.sh installer that enrols a daemon installs a control plane, on an explicit opt-in. It provisions a managed FHS layout on Debian — the bootstrap refuses any other distribution up front — with dedicated service users (tp, tpctrl, tpcaddy), the compiled instance and mailer under /opt/turbopanel/lib/instance, the static UI at /opt/turbopanel/share/ui, Postgres / Redis / RabbitMQ / Docker, the platform CA and a self-signed leaf, systemd units and Caddy — from the release packages on GitHub Releases, every asset verified against the release's manifest.json. Packages exist once the first v0.1.0 release is cut; until then the command refuses with "does TurboPanel/turbopanel have a release yet?".

curl -fsSL turbopanel.sh | TURBOPANEL_INSTANCE=1 sh

Overview and operator responsibilities: Self-hosted.

TurboPanel High Availability (private alpha — waitlist)

TurboPanel High Availability runs the instance on Cloudflare Workers. Remote daemons connect over HTTPS/WSS to a hosted URL. It is not yet publicly available — join the waitlist for access updates.

When access is available, operators create an organization in the hosted panel, configure Workers bindings and secrets, and enroll nodes with turbopanel.sh (manifest default host — no TURBOPANEL_HOST required).

Maintainers deploy the Workers bundle from the instance repo:

export TURBOPANEL_DATABASE_URL="postgresql://user:pass@host:5432/dbname"
# or, for CI / dashboard deploy workflows:
# export DATABASE_URL="postgresql://user:pass@host:5432/dbname"
export CLOUDFLARE_ENV=live   # or testing — must match a wrangler.jsonc env name
pnpm install
pnpm deploy

pnpm deploy runs pending migrations (via TURBOPANEL_DATABASE_URL or DATABASE_URL) then wrangler deploy --env $CLOUDFLARE_ENV --minify. The migration step uses Node only (drizzle-kit migrate + post-migration resource-registry repair) — Deno is not required on the deploy host. Configure Hyperdrive, secrets (TURBOPANEL_SECRETS), and bindings in wrangler.jsonc before deploy.

Configuration

The complete list of what a self-hosted instance reads at boot — required, defaulted, and silently degrading — is Instance configuration. The most common ones:

Key environment variables (instance)

Managed hosts inject vars via Ansible instance-launch. Workers dev uses .dev.vars in the instance checkout. Provider setup (Admin → Auth providers, env-wins, and linking rules): Accounts and access.

API entrypoints

HTTPS entrypoint (self-hosted): https://<host>:8443 by default. lets_encrypt serves https://<hostname>/ on :443.

Communication patterns

• Browser → Caddy → instance: REST and cookies on /api/client/v1/*
• Daemon → instance: WSS /ws/daemon/v1 (through Caddy or direct Unix socket when co-located)
• Dev sync / tunnel: Operator pushes daemon builds or tunnel tokens via developer API + daemon WS messages

Compose deploys (compiled runtime file)

The control plane stores a project base compose and an optional environment overlay. Merge and platform inject happen on the instance; environment.deploy then publishes a single compiled compose.yaml (role: 'runtime') that the daemon writes under <stateDir>/deployments/<projectId>/<environmentId>/ next to .env (non-secrets) and deployment.json.

Overrides between the authored project and environment layers follow the Compose Spec merge rules: mapping keys merge recursively (a later layer wins per key), most sequences — ports, volumes, env_file, and similar lists — append with attribute-specific key-based de-duplication rather than replacing the earlier layer wholesale, and command, entrypoint, and a service's healthcheck.test always fully replace rather than append. Authors who need to remove a value entirely, or force full replacement instead of the default append/merge behavior for a sequence, can use the reserved !reset (delete the key) and !override (force full replacement) YAML tags on the environment overlay.

In the organization console, Merged compose is a client-side simulation of the fully merged effective document (readability aid). Prepared compose and the live environment.deploy path show that compiled compose.yaml. See also API architecture — compiled compose.

Related documentation

• Installation paths — Decision guide for all install paths
• Accounts and access — Two-factor, passkeys, GitHub / Google sign-in, and invitations
• Self-hosted overview — Operator responsibilities
• Daemon setup — Remote node installer
• Security — TLS, auth, and hardening
• Deployment troubleshooting — Runtime issues
• Instance API architecture — Code layout