Storage, variables and secrets

Two things a compose document deliberately does not contain: where its data lives, and the values its services read at build and at runtime. Both are properties of the environment and the scopes above it, managed on their own tabs, and referenced — never copied — from the document. This chapter covers the Storage tab, the Variables panels at every scope, secrets, and the {$KEY} reference syntax that ties them into compose.

Storage

The model

A storage entry is one persistent location an environment's service mounts: a named Docker volume, a host directory, or a single file. It belongs to the environment (storage is provisioned on that environment's server), is mounted into one service at a destination path, and carries two policies:

Behind an entry are its copies — where the bytes actually are. A copy has a provider (docker for a named volume, path for a host path), a role (primary, replica, scratch, archive) and a state (pending → materializing → ready, or syncing, stale, failed, retiring). One copy is the primary; a scratch copy is never mounted. Most entries have exactly one, on the environment's server.

Add storage

Compose-declared volumes: still work exactly as in Compose; the Storage tab is for data the platform should know about — the things that survive a destroy when marked retain, and the things a redeploy on another server has to find.

Reference

Variables

The model

A variable is a key and a value at one scope. Scopes nest, and a service's effective environment is the merge from the outside in:

organization → workspace → project → environment → service → hosting

A key set at a narrower scope overrides the same key set wider. Server-scoped variables are the seventh scope, resolved per server at deploy rather than inherited down the project tree, so a value can differ by host. The console edits three of the scopes today: the project's and the environment's on their Settings tabs (Add Variable), and a hosting row's on the Hosting tab once the row is saved. Organization, workspace, service and server scopes exist in the API (POST /variables with the matching parent id) and resolve in the cascade, but have no console panel yet.

Each variable carries four switches:

Keys match [A-Za-z_][A-Za-z0-9_]*. A key a database binding owns (the connection details of a managed database bound to the environment) is locked: it shows under From connected databases, cannot be edited (binding_owned_variable), and cannot be shadowed by a variable of the same name (binding_key_conflict).

Add a variable

Referencing variables from compose

Plain Compose ${KEY} works as Docker defines it, against the generated .env. TurboPanel adds one reference form, resolved by the platform before Compose sees the document:

services:
  api:
    environment:
      DATABASE_URL: "{$DATABASE_URL}"        # nearest scope wins
      REGION: "{$organization.REGION}"       # pinned to one scope
    secrets:
      - source: api_token                    # a secret compiled to a file

{$KEY} takes the effective value from the cascade; {$scope.KEY} (organization, workspace, project, environment, service, hosting, server; org is accepted for organization) pins a scope. A reference to a secret is compiled into a Compose secrets: entry backed by a file the daemon materializes under /run/turbopanel/deployments/<project>/<environment>/secrets/, plus a courtesy <KEY>_FILE variable holding that path — interpolating a secret directly into a plain field is refused (variable_secret_interpolation), because that would write it into YAML.

Errors

Related

• Writing compose — the document that references all of this.
• Deploying and running an environment — the prepared preview that shows the resolved .env and secret paths.
• Managed databases — where binding-owned variables come from.
• Storage architecture — the platform's storage classes underneath.