---
obj: application
source: https://docs.docker.com/compose
repo: https://github.com/docker/compose
rev: 2024-07-15
---

# Docker Compose
Compose is a tool for defining and running multi-container [Docker](Docker.md) applications. With Compose, you use a [YAML](../files/YAML.md) file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.

## Usage
Usage: `docker-compose [-f ComposeFile] [COMMAND] [OPTION]...`

### `docker-compose up`
Create and start containers.

#### Options
| Option         | Description                                     |
| -------------- | ----------------------------------------------- |
| `--build`      | Build images before starting containers.        |
| `-d, --detach` | Detached mode: Run containers in the background |

### `docker-compose down`
Stops containers and removes containers, networks, volumes, and images created by `up`.

### `docker-compose build`
Build or rebuild services

#### Options
| Option       | Description                                          |
| ------------ | ---------------------------------------------------- |
| `--no-cache` | Do not use cache when building the image             |
| `--pull`     | Always attempt to pull a newer version of the image. |

### `docker-compose cp`
Copy files/folders between a service container and the local filesystem
Usage: `docker compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH|-`

### `docker-compose exec`
This is the equivalent of `docker exec` targeting a Compose service.

#### Options
| Option              | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `-d, --detach`      | Detached mode: Run command in the background.                    |
| `-e, --env`         | Set [environment variables](../linux/Environment%20Variables.md) |
| `-i, --interactive` | Keep STDIN open even if not attached.                            |
| `-t, --tty`         | Allocate a pseudo-TTY.                                           |
| `-u, --user`        | Run the command as this user.                                    |
| `-w, --workdir`     | Path to workdir directory for this command.                      |

### `docker-compose logs`
Displays [log](../dev/Log.md) output from services.

#### Options
| Option           | Description                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| `-f, --follow`   | Follow log output                                                                              |
| `--since ts`     | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)    |
| `-n, --tail num` | Number of lines to show from the end of the logs                                               |
| `--until`        | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) |

### `docker-compose kill`
Force stop service containers.

### `docker-compose ps`
List running containers

### `docker-compose pull`
Pull service images

### `docker-compose restart`
Restart service containers

## Docker Compose file
The Compose file is a [YAML](../files/YAML.md) file defining:
- Version (Optional)
- Services (Required)
- Networks
- Volumes
- Secrets

## Service Configuration
### `build`
Build specifies the image that should be build for the service instead of using an image directly.
`build` can be specified either as a string containing a path to the build context:
```yaml
version: "3.8"
services:
  webapp:
    build: ./dir
``````

Or, as an object with the path specified under context and optionally [Dockerfile](Dockerfile.md) and args:
```yaml
version: "3.8"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1
```

### `command`
Override the default command.
```yaml
command: bundle exec thin -p 3000
```

The command can also be a list, in a manner similar to [dockerfile](Dockerfile.md):
```yaml
command: ["bundle", "exec", "thin", "-p", "3000"]
```

### `depends_on`
`depends_on` expresses startup and shutdown dependencies between services.

```yaml
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres
```

### `devices`
`devices` defines a list of device mappings for created containers in the form of `HOST_PATH:CONTAINER_PATH\[:CGROUP_PERMISSIONS]`.
```yaml
devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"
```

### `entrypoint`
`entrypoint` declares the default entrypoint for the service container. This overrides the ENTRYPOINT instruction from the service's [Dockerfile](Dockerfile.md).

If entrypoint is non-null, Compose ignores any default command from the image, for example the CMD instruction in the [Dockerfile](Dockerfile.md).

In its short form, the value can be defined as a string:
```yaml
entrypoint: /code/entrypoint.sh
```

### `env_file`
`env_file` adds [environment variables](../linux/Environment%20Variables.md) to the container based on the file content.
```yaml
env_file: .env
```

`env_file` can also be a list. The files in the list are processed from the top down. For the same variable specified in two env files, the value from the last file in the list stands.
```yaml
env_file:
  - ./a.env
  - ./b.env
```

### `environment`
`environment` defines [environment variables](../linux/Environment%20Variables.md) set in the container. environment can use either an array or a map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure they are not converted to True or False by the [YAML](../files/YAML.md) parser.

[Environment variables](../linux/Environment%20Variables.md) can be declared by a single key (no value to equals sign). In this case Compose relies on you to resolve the value. If the value is not resolved, the variable is unset and is removed from the service container environment.

Map syntax:
```yaml
environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:
```

Array syntax:
```yaml
environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT
```

When both env_file and environment are set for a service, values set by environment have precedence.

### `healthcheck`
`healthcheck` declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the HEALTHCHECK [Dockerfile](Dockerfile.md) instruction

set by the service's [Docker](Docker.md) image. Your Compose file can override the values set in the [Dockerfile](Dockerfile.md).

```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s
```

### `image`
`image` specifies the image to start the container from. image must follow the Open Container Specification addressable image format, as `[<registry>/][<project>/]<image>[:<tag>|@<digest>`.
```yaml
image: redis
image: redis:5
image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
image: library/redis
image: docker.io/library/redis
image: my_private.registry:5000/redis
```

### `labels`
`labels` add metadata to containers. You can use either an array or a map.

It's recommended that you use reverse-[DNS](../internet/DNS.md) notation to prevent your labels from conflicting with those used by other software.
```yaml
labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"
```

### `network_mode`
`network_mode` sets a service container's network mode. Available values are platform specific, but Compose defines specific values which must be implemented as described if supported:
- `none`: Turns off all container networking.
- `host`: Gives the container raw access to the host's network interface.
- `service:{name}`: Gives the containers access to the specified service only.

```yaml
    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"
```

When set, the `networks` attribute is not allowed and Compose rejects any Compose file containing both attributes.

### `networks`
`networks` defines the networks that service containers are attached to, referencing entries under the top-level networks key.
```yaml
services:
  some-service:
    networks:
      - some-network
      - other-network
```

### `ports`
Exposes container ports.

The short syntax is a colon-separated string to set the host IP, host port, and container port in the form:

`[HOST:]CONTAINER[/PROTOCOL]` where:
- `HOST` is `[IP:](port | range)`
- `CONTAINER` is `port | range`
- `PROTOCOL` to restrict port to specified protocol. [tcp](../internet/TCP.md) and [udp](../internet/UDP.md) values are defined by the Specification.

If host IP is not set, it binds to all network interfaces. Ports can be either a single value or a range. Host and container must use equivalent ranges.

Either specify both ports `(HOST:CONTAINER)`, or just the container port. In the latter case, Compose automatically allocates any unassigned port of the host.

`HOST:CONTAINER` should always be specified as a (quoted) string, to avoid conflicts with yaml base-60 float

```yaml
ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "8000-9000:80"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"
```

### `privileged`
`privileged` configures the service container to run with elevated privileges.

### `restart`
`restart` defines the policy that the platform applies on container termination.

- `no`: The default restart policy. It does not restart the container under any circumstances.
- `always`: The policy always restarts the container until its removal.
- `on-failure`: The policy restarts the container if the exit code indicates an error.
- `unless-stopped`: The policy restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed.

```yaml
    restart: "no"
    restart: always
    restart: on-failure
    restart: unless-stopped
```

### `secrets`
`secrets` grants access to sensitive data defined by secrets on a per-service basis. Two different syntax variants are supported; the short syntax and the long syntax.

Compose reports an error if the secret doesn't exist on the platform or isn't defined in the secrets section of the Compose file.

Services can be granted access to multiple secrets. Long and short syntax for secrets may be used in the same Compose file. Defining a secret in the top-level secrets must not imply granting any service access to it. Such grant must be explicit within service specification as secrets service element.

The short syntax variant only specifies the secret name. This grants the container access to the secret and mounts it as read-only to `/run/secrets/<secret_name>` within the container. The source name and destination mountpoint are both set to the secret name.

The following example uses the short syntax to grant the frontend service access to the server-certificate secret. The value of server-certificate is set to the contents of the file `./server.cert`.
```yaml
services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert
```

The long syntax provides more granularity in how the secret is created within the service's containers.
- `source`: The name of the secret as it exists on the platform.
- `target`: The name of the file to be mounted in `/run/secrets/` in the service's task container, or absolute path of the file if an alternate location is required. Defaults to source if not specified.
- `uid` and `gid`: The numeric UID or GID that owns the file within `/run/secrets/` in the service's task containers. Default value is USER running container.
- `mode`: The permissions for the file to be mounted in `/run/secrets/` in the service's task containers, in octal notation. The default value is world-readable permissions (mode `0444`). The writable bit must be ignored if set. The executable bit may be set.

The following example sets the name of the server-certificate secret file to server.crt within the container, sets the mode to 0440 (group-readable), and sets the user and group to 103. The value of server-certificate secret is provided by the platform through a lookup and the secret's lifecycle is not directly managed by Compose.
```yaml
services:
  frontend:
    image: example/webapp
    secrets:
      - source: server-certificate
        target: server.cert
        uid: "103"
        gid: "103"
        mode: 0440
secrets:
  server-certificate:
    external: true
```

### `volumes`
`volumes` define mount host paths or named volumes that are accessible by service containers. You can use `volumes` to define multiple types of mounts; `volume`, `bind`, `tmpfs`, or `npipe`.

The short syntax uses a single string with colon-separated values to specify a volume mount `(VOLUME:CONTAINER_PATH)`, or an access mode `(VOLUME:CONTAINER_PATH:ACCESS_MODE)`.
- `VOLUME`: Can be either a host path on the platform hosting containers (bind mount) or a volume name.
- `CONTAINER_PATH`: The path in the container where the volume is mounted.
- `ACCESS_MODE`: A comma-separated , list of options:
- - `rw`: Read and write access. This is the default if none is specified.
- - `ro`: Read-only access.

```yaml
volumes:
  - ./volume:/mnt
```

## Secrets
The top-level secrets declaration defines or references sensitive data that is granted to the services in your Compose application. The source of the secret is either file or environment.

- `file`: The secret is created with the contents of the file at the specified path.
- `environment`: The secret is created with the value of an environment variable.
- `external`: If set to true, external specifies that this secret has already been created. Compose does not attempt to create it, and if it does not exist, an error occurs.

```yaml
secrets:
  server-certificate:
    file: ./server.cert
```

## Docker Compose Deploy
The Compose Deploy Specification lets you declare additional metadata on services so Compose gets relevant data to allocate adequate resources on the platform and configure them to match your needs. [Docker Swarm](Docker%20Swarm.md) respects these specifications.

### `mode`
`mode` defines the replication model used to run the service on the platform. Either `global`, exactly one container per physical node, or `replicated`, a specified number of containers. The default is `replicated`.
```yaml
services:
  frontend:
    image: example/webapp
    deploy:
      mode: global
```

### `replicas`
If the service is `replicated` (which is the default), `replicas` specifies the number of containers that should be running at any given time.
```yaml
services:
  frontend:
    image: example/webapp
    deploy:
      mode: replicated
      replicas: 6
```

### `restart_policy`
`restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose considers the restart field set by the service configuration.

- `condition`. When set to:
- - `none`, containers are not automatically restarted regardless of the exit status.
- - `on-failure`, the container is restarted if it exits due to an error, which manifests as a non-zero exit code.
- - `any` (default), containers are restarted regardless of the exit status.
- `delay`: How long to wait between restart attempts, specified as a duration. The default is 0, meaning restart attempts can occur immediately.
- `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value. For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts must be attempted.
- `window`: How long to wait before deciding if a restart has succeeded, specified as a duration (default: decide immediately).

```yaml
deploy:
  restart_policy:
    condition: on-failure
    delay: 5s
    max_attempts: 3
    window: 120s
```

### `placement`
`placement` specifies constraints and preferences for the platform to select a physical node to run service containers.
constraints

`constraints` defines a required property the platform's node must fulfill to run the service container. It can be set either by a list or a map with string values.
```yaml
deploy:
  placement:
    constraints:
      - node.labels.disk == ssd
      - node.role == manager
```

```yaml
deploy:
  placement:
    constraints:
      disktype: ssd
```

`preferences` defines a property the platform's node should fulfill to run service container. It can be set either by a list or a map with string values.

```yaml
deploy:
  placement:
    preferences:
      - datacenter=us-east
```

```yaml
deploy:
  placement:
    preferences:
      datacenter: us-east
```

### `resources`
`resources` configures physical resource constraints for container to run on platform. Those constraints can be configured as:
- `limits`: The platform must prevent the container to allocate more.
- `reservations`: The platform must guarantee the container can allocate at least the configured amount.

The following can be configured:
- `cpus`: `cpus` configures a limit or reservation for how much of the available CPU resources, as number of cores, a container can use.
- `memory`: `memory` configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a byte value.
- `pids`: `pids` tunes a container’s PIDs limit, set as an integer.

```yml
deploy:
  resources:
    limits:
      cpus: 0.5
      memory: 128MiB
    reservations:
      cpus: 0.3
      memory: 64MiB
```
