Writing compose

A TurboPanel project is described by a Compose file. Not a dialect of one: the Compose Specification as published, validated against the same schema Docker uses, with one reserved extension — x-turbopanel — for the handful of things Compose has no way to say. If you can write a compose.yaml, you can write a TurboPanel project. This chapter is the reference for that document: the two editors that produce it, what the platform reads, what it adds, what it refuses, and how an environment's overlay merges over it.

Three rules

Everything else on this page follows from three rules the platform holds itself to.

1. Compose says what the workload wants. Image, command, ports, volumes, networks, health checks, deploy.replicas, deploy.resources, deploy.placement — if the Compose Specification has an expression for it, that is the expression TurboPanel reads. There is never an x- key for a question Compose already answers.
2. x-turbopanel says only what Compose cannot. One namespace, two places: the document root (principals) and each service (serviceKind, principal, hosting, source, php, cron, and a few runtime pins). A privilege decision — a Unix uid, a home directory, a password — never belongs in a document at all.
3. The platform decides how. Which server, which container name, which Docker network, which address. A document never pins those; one that tries is refused rather than quietly honoured.

One document, three views

The project editor shows the document through three lenses, and they are views of one artifact, not three files:

An unsaved draft follows you between the three tabs. Save and Discard appear only while the draft is dirty; Discard is two presses and returns to the last saved document. On the Overview a dirty draft shows the Proposed topology with a Proposed | Saved toggle.

The x-turbopanel blocks are hidden from the YAML view and re-attached on save, so the Compose tab shows plain Compose and the Services forms own the extension fields. Nothing about the stored document or its validation changes between the two.

Before you begin

• A project of the compose type — every card on the create wizard except Template and Managed produces one, and a template project becomes an ordinary compose project once created.
• For a service that runs as a Unix account — a site or a Node app — a system user declared under x-turbopanel.principals or assigned on the Bindings tab. The daemon skips a release that has nobody to run as, and the app keeps Deploy disabled until one is assigned.
• For a service built from a repository, a Git source connected under Projects → Git sources.

Add a service

The three kinds

Sites and Node apps are stripped out of the runtime compose the daemon runs; their releases are checked out, built and promoted under the account's home, and the host engine or the unit serves them. Everything else in the document — networks, volumes, the other services — deploys as ordinary Compose.

Sites: engines, files and users

A site service is served by one engine on the server, chosen with engine. Each engine runs under its own service account and serves files on the loopback address; the host's hosting Caddy fronts it.

There is no separate nginx-with-PHP engine: give a site a php block to run PHP. How that PHP is started (FastCGI, php-fpm or lsphp) is the site's PHP mode, and Apache never uses mod_php.

Who runs what. The engine process runs as its engine account and only reads the site's files. The files belong to the site owner's Linux user (the principal alias in the document), with the engine's group allowed to read. PHP runs as that same Linux user, so what a site writes, it writes as its own account. A Node app is a systemd unit that runs as its owner's Linux user. A Railpack service has no Linux user of its own: it is an ordinary container. These users are created on first deploy; the host picks their UID and GID from 15001 to 60000 (an override must be 15001 or more), with homes under /srv/users/<username>. A site and a Node app each need exactly one owner; see site_principal_ambiguous.

Where the content comes from. A site has one of two sources:

A managed directory gives up the read-only guarantee: the tree the engine executes is writable by the account that runs it. That is the right trade for WordPress and other PHP applications that write to themselves, and the wrong one for a built application. It needs a site owner's Linux user (site_managed_directory_unowned otherwise), PHP is still confined to the site's own directory by open_basedir, and connecting a repository to the site later is a field change rather than a move: remove sourceKind and add source.

Import a docker run line

Import docker run (in the compose editor toolbar) turns a docker run … command into one ordinary service — plain Compose, nothing written under x-turbopanel, validated like a hand-written document. The importer knows every option docker container run accepts; the ones Compose can express are mapped, the ones that describe the container but have no Compose expression are refused with the option named (docker_run_unsupported), and a gated field the command asks for (--privileged, --cap-add, a Docker socket mount) is flagged as a risk before the service exists. Shell syntax in the pasted line — $(…), pipes, redirection, globs — is taken as literal text and warned about, never executed.

The x-turbopanel extension

At the document root

x-turbopanel:
  principals:
    web:
      access: sftp        # none | sftp | ssh — the access the account is created with

principals declares the system users a document's services may run as, by a document-local alias. The alias is a name inside this file; the Unix account behind it — username, uid, home, keys, password — lives on a system user row the platform creates on first deploy and that you manage on the Bindings tab. An alias is never a Linux username. The account's system name follows the organization's name scheme (default partial).

On a service

services:
  shop:
    image: ghcr.io/example/shop:2.4
    x-turbopanel:
      description: Storefront
      hosting:
        - hostname: shop.example.com
          targetPort: 3000
          forceHttps: true
          tls: { mode: acme }
          bind: { scope: public }
      cron:
        - name: reindex
          schedule: "0 3 * * *"
          command: node scripts/reindex.js

A key that names a privilege — uid, gid, home, shell, keys, password — is refused with a message pointing at the row that owns it.

What is not in the extension, on purpose

Field policy — what happens to each Compose key

Every Compose key carries one of five verdicts. Nothing is dropped in silence: a key the platform does not act on is reported with the reason.

Host-level features

A gated key is one of two kinds of host-level feature. The other is a path that reaches outside the service's own directory on the server:

• a bind whose source is absolute (/, /etc, /var/run/docker.sock), starts with ~, climbs out with .., is interpolated (${…}), or mounts the service directory itself (.)
• a long-form mount of type bind, npipe, or a type the platform does not recognise
• a top-level volume whose driver_opts bind a host path or device
• configs or secrets with a file: outside the service directory, and env_file or label_file outside it
• a build context, Dockerfile or additional context outside the service directory, build.ssh, a host build network, a privileged build, or build entitlements
• extends.file and include, wherever they point

A relative bind that stays inside the service directory (./data:/data, ./config:/etc/app:ro), a named volume, an NFS volume, and a remote build context (a Git URL) are ordinary features and need nothing.

Host-level features are off by default, per organization. An organization owner turns them on under Manage Organization → Compose (PUT /organizations/:id/compose-privileged-fields); every flip is written to the organization's audit trail. With them on, only an organization manager or owner can deploy a document that uses them.

A Git-triggered deploy has no person behind it. It may deploy host-level content only after a manager or owner has deployed that same content once from the app. That deploy records an approval tied to exactly what reaches the host, so any change to those parts of the document needs a new console deploy before automated deploys resume.

The server checks again at deploy. It resolves every bind and file path to its real location on the host and refuses one that escapes the service directory through a symbolic link, even with host-level features on. It also refuses a path nested inside another writable bind, which a container could change between the check and the deploy. The deploy then fails with compose deploy refused — host paths outside this deployment: followed by each path and where it resolves.

cap_drop, ports and user are deliberately not gated.

The linter

The linter runs in the editor on every keystroke and again on every save and deploy. Save refuses errors; deploy refuses errors and treats some advisories as errors.

Merging an overlay

An environment's overlay merges over the project compose per the Compose Specification. Preview ▾ → Merged compose shows the result.

Two YAML tags change the rule for one key:

services:
  api:
    ports: !override
      - "8443:443"       # replaces the project's list instead of appending
    labels: !reset       # removes the key entirely

Variables in the document

Reference a variable as ${KEY} or ${scope.KEY}. Non-secret values are written to a generated .env beside the runtime compose; secret values never touch YAML — they compile to Compose secrets: with a file path the daemon materializes at deploy, plus a courtesy KEY_FILE variable holding that path. A binding to a managed database contributes its own locked variables under the binding's prefix.

Releases and rollback

A service with a source produces a release on every deploy: the repository is checked out at the branch's current commit, built with buildCommand, and published atomically under the site owner's home. The Releases panel on the Services tab lists them. A redeploy against an unchanged commit and unchanged compose is a no-op — the platform hashes both.

Native releases (sites and Node apps, buildKind: native) are built on the server in a scratch directory, never in the live tree, inside the build sandbox. The result is copied into releases/<id>/, sealed read-only (owned by root, mode 0550), health-checked, and made live by re-pointing the current link in one step: a failure before that step leaves the old release serving. Each release has a writable shared/ link for data that must survive releases. The newest five releases are kept, plus the live one.

Railpack releases (buildKind: railpack, container services only) build a container image from the source with Railpack instead of a directory. The release is the image tag, run by Compose like any other container; there is no site owner's Linux user and nothing is sealed.

Rollback re-publishes an earlier release without a rebuild: for a native release it re-points current, for a Railpack release it puts that image tag back into the compose. It rides an ordinary deploy, so compose, hostnames and certificates are applied as usual. A release is offered for rollback only if every server the environment deploys to has it. Rollback trusts only a release record that the daemon wrote on that server when the release was published, never the files in the site owner's home. Two consequences:

• A release published before the daemon began writing records (a daemon that predates release records) has no record on its server. A rollback to it fails with this host has no release record for it — redeploy that release; redeploy it once and it becomes a rollback target.
• A release that retention has removed from the server cannot be rolled back to, record or not (not present on this host).

Reference

Limits

Deploy-time refusals that originate in the document

These are reported by Deploy, not by Save, because they depend on the merged document, the organization or the servers. The full deploy table is in Deploying.

Errors at save

Related

• Projects and environments — the container the document lives in.
• Deploying and running an environment — placement, preview, deploy, and every refusal.
• Compose contract — the same rules from the platform's side.
• Datacenter networks — how an overlay network spans servers.