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.
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,externalvolumes, a driver other thanlocaland a customname:are refused. - A mount is
name:/path,name:/path:roorname:/path:rw, or the long form withtype: volume. ${VAR}and$VARinterpolation is refused inimage,command,entrypoint,user,working_dirand environment values; write the value or use the app's environment.$$is a literal$, as in docker compose.- A
commandorentrypointstring with shell characters is refused; use the list form,["sh", "-c", "…"]. depends_onmay not reference a service that is not in the file, and may not form a cycle.restartis one ofno,always,on-failure,on-failure:<n>,unless-stopped.- An
imagewithout a registry is pulled from Docker Hub (postgres:17isdocker.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_TOKENA 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:17Set 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.