Control Plane Deployment

The TurboPanel control plane is the 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 per surface: /api/client/v1/openapi.json + /api/client/v1/reference (client API), /api/admin/v1/openapi.json + /api/admin/v1/reference (superadmin)

Relationship to daemon

On the control plane host, a co-located daemon installs and updates the control plane, 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 listeners

Self-hosted Caddy listens on :8443. Every hostname is served there, and the certificate is chosen by the name. The Platform CA is still minted, and it stays the catch-all leaf.

The Caddyfile is rendered by the daemon's instance-launch role into /etc/turbopanel/caddy/Caddyfile on every converge. Change names in Admin → Access → Hostnames, then apply. The rendered file is not hand-edited.

Port 80 is opened on hosting Caddy for that window, then closed. When another process holds it, the apply fails with port 80 is held by <process>. The flow is in Hostnames and TLS.

TURBOPANEL_TLS_PUBLIC=1 is set when any hostname is Let's Encrypt, or when the operator marks TLS public. A name that presents a Let's Encrypt or uploaded leaf gets a 404 from GET /api/daemon/v1/instance/ca. The daemon then uses the system trust store, or the uploaded issuer for a private pair, and the install command omits --insecure-tls for a publicly trusted leaf. An unlisted name on :8443 still receives the Platform CA bundle.

turbopanel_tls_mode is a label derived from the hostname list (self_signed, upload, or lets_encrypt). It does not choose a different 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), one compiled instance binary, /opt/turbopanel/bin/turbopanel, beside the daemon (its DuckDB library in /opt/turbopanel/lib; the email consumer runs inside it, there is no separate mailer process), 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. When the chosen channel has no release yet, the command stops with "does TurboPanel/turbopanel have a <channel> release yet?".

curl -fsSL turbopanel.sh | sh

The first admin (hosted)

A self-hosted control plane creates its first superadmin in the install wizard, from host PAM. The TurboPanel High Availability (Workers) control plane has no wizard: signup is off unless TURBOPANEL_IS_SIGNUP_ENABLED says otherwise, and no route ever grants a role. So a freshly migrated TurboPanel High Availability database has no way in — and the tier catalogue needs a superadmin to enter it. Once, from the turbopanel checkout, over the same database URL pnpm migrate uses:

CLOUDFLARE_ENV=live TURBOPANEL_DATABASE_URL=… pnpm bootstrap:superadmin -- --email you@example.com

It promotes an existing account and nothing else: it refuses when the database already has a superadmin, never creates a user or sets a password, and — with CLOUDFLARE_ENV set — refuses a database that is not that environment's Hyperdrive origin. Add --dry-run to see what it would do. If the account does not exist yet it says so and stops: enable signup on that environment, sign up as that address, run it again, then turn signup back off. Every later admin is promoted from the console.

Overview and operator responsibilities: Self-hosted.

TurboPanel High Availability (private alpha — waitlist)

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

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

Maintainers deploy the Workers bundle from the control plane 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 control plane reads at boot — required, defaulted, and silently degrading — is Control plane configuration. The most common ones:

Key environment variables (control plane)

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

Admin → Access

/admin opens Access. /admin/networking redirects there. The area is how people and machines reach this control plane. Organization TLS stays on the organization.

Per-hostname sources need a co-located daemon that can render them (instance-cert-sources-per-hostname, daemon 0.1.1 or newer). Older daemons keep the rows visible and leave the sources disabled until that daemon is updated.

Admin → Updates is the managed platform upgrade. On self-hosted it runs this host's daemon, then the control plane, then the other servers, and the other servers wait until the first two are on target. On TurboPanel High Availability the control plane line is Managed by TurboPanel and only daemons roll out. Detail: Upgrade and rollback.

API entrypoints

HTTPS entrypoint (self-hosted): https://<host>:8443. Every hostname is served there. The certificate is chosen by the name. Trust the Platform CA for a name that presents that leaf.

Communication patterns

• Browser → Caddy → control plane: REST and cookies on /api/client/v1/*
• Daemon → control plane: 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 control plane; 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 app, 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 server installer
• Security — TLS, auth, and hardening
• Deployment troubleshooting — Runtime issues
• Instance API architecture — Code layout