Compose files

What a compose file for an app may contain, how its services get their environment, how named volumes and release-only services behave.

Last updated 18 November 2026View as Markdown

A compose app runs every service in its file on each of its machines, on one private app network. One service is the published service, reachable from outside through the app's domains; the others reach each other by service name (db resolves to the database container from inside web). A file pasted into the app is validated when the app is created or updated, before anything is saved; a file read from a repository is validated when a deployment reads it at a pinned commit, and fails that deployment. Every problem names the key and, where it can be located, the line.

What a compose file may contain

Top level: services, volumes, and name and version, which are ignored. Per service: image, command, entrypoint, environment, expose, ports, volumes, depends_on, restart, user, working_dir, and x-dcloud-release. Other x- extension fields are ignored at both levels. Anything else is refused, and the message says why:

Key Refused because
build there is no build step on this path: publish the image first and reference it with image:
container_name container names are assigned by the platform so two generations can co-exist during a rollout
env_file there is no repository checkout on the machine: put the values in the app's environment
healthcheck the platform health-checks the published service over HTTP and only then moves the domain onto it
deploy replicas and resources are set on the app
secrets, configs bind a secret to an environment variable on the app
networks, network_mode every service joins one app network automatically
extends, include, profiles, scale, links, external_links, volumes_from not supported; the file must be self-contained
privileged, cap_add, cap_drop, pid, ipc, devices, device_cgroup_rules, security_opt, userns_mode, cgroup_parent, sysctls not allowed on an app machine

Further rules, each refused with the line number:

  • ports: may not publish a host port (publishing host port 5432 is not supported), and port ranges are refused. A container port alone ("3000") is accepted. Only the published service is reachable, through the domain; services reach each other by name.
  • Volumes must be named volumes declared at the top level. Host paths (./data, /var/…), anonymous volumes, external volumes, a driver other than local and a custom name: are refused.
  • A mount is name:/path, name:/path:ro or name:/path:rw, or the long form with type: volume.
  • ${VAR} and $VAR interpolation is refused in image, command, entrypoint, user, working_dir and environment values; write the value or use the app's environment. $$ is a literal $, as in docker compose.
  • A command or entrypoint string with shell characters is refused; use the list form, ["sh", "-c", "…"].
  • depends_on may not reference a service that is not in the file, and may not form a cycle.
  • restart is one of no, always, on-failure, on-failure:<n>, unless-stopped.
  • An image without a registry is pulled from Docker Hub (postgres:17 is docker.io/library/postgres:17). An image on your registry must be in the repository the app is bound to.
  • Environment values are single-line.
  • At most 20 services, 20 named volumes, and 1000 variables per service.
  • The file is at most 128 KiB.

The environment of each service

The published service, every release-only service, and every service that runs the published service's image (any tag) receive every variable of the app, database bindings included, whatever their command. A worker or scheduler built from the same code needs nothing extra. A service with any other image, such as a stock redis or a sidecar, receives only the variables it names itself, in compose's bare form:

cache-warmer:
  image: docker.io/library/busybox:1.36
  environment:
    - API_TOKEN

A literal value written in the file always wins over the app's environment. A bare name must be a variable set in the app's environment: one the app does not define fails the deployment with The compose file asks for environment variables the app does not define: cache-warmer.API_TOKEN. A variable that only a binding generates, such as DATABASE_URL, does not count as defined here.

Named volumes

A named volume becomes a volume on the machine, created once and kept across deployments. A redeploy leaves it in place; data in it survives a push. It does not survive replacing or destroying the machine, and it is never removed: a volume dropped from the file stays on disk, and the activity says so.

Warning

Named volumes live on the machine's disk. Back the data up before you replace or destroy a machine.

Release-only services

A service with x-dcloud-release: true is never started as a long-lived container and never health-checked. It exists so that the release command can run in its image, a migrator image that the runtime image does not contain, for example:

services:
  web:
    image: org-example1234.ecr.example.com/my-app/web:abc123
    expose: ['3000']
    depends_on: [db]
  migrate:
    image: org-example1234.ecr.example.com/my-app/web:migrator-abc123
    x-dcloud-release: true
    depends_on: [db]
  db:
    image: docker.io/library/postgres:17

Set releaseService to migrate and a releaseCommand such as pnpm db:migrate && pnpm db:seed. On every deployment its image is pulled with the others, then the release command runs once in it (a container removed afterwards), on the app network, with the app's whole environment plus the service's own environment (the file's values win). Output streams to the activity feed; a non-zero exit fails the deployment before traffic moves. It runs after the services it depends_on are up, under the rules in Configure the release command and health checks.

Refused, with the line: a value other than true or false; the published service being release-only; another service depending on a release-only one; a release-only service that is not the app's release service (it would never run). An image from your registry must still be in the one repository the app is bound to, so use a tag there rather than a second repository.

Did this page help you?