# 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, `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:

```yaml
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:

```yaml
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](configure-release-and-health-checks.md).

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.

## Related

- [Create an app from a compose file](create-an-app-from-a-compose-file.md)
- [Deployments](deployments.md)
