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 console 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.

Import a docker run line

Services → Import from docker run 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.

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.

The gate is per organization and off by default. An owner turns it on through PUT /organizations/:id/compose-privileged-fields; every flip is written to the organization's audit trail. cap_drop, volumes, 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 promoted atomically under the account's home. The Releases panel on the Services tab lists them; Rollback re-points the service at an earlier release without a rebuild. A redeploy against an unchanged commit and unchanged compose is a no-op — the platform hashes both.

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 fleet. 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.