mirror of https://github.com/docker/compose.git
363 lines
14 KiB
YAML
363 lines
14 KiB
YAML
command: docker compose
|
||
short: Docker Compose
|
||
long: |-
|
||
You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
|
||
multiple services in Docker containers.
|
||
|
||
### Use `-f` to specify the name and path of one or more Compose files
|
||
Use the `-f` flag to specify the location of a Compose configuration file.
|
||
|
||
#### Specifying multiple Compose files
|
||
You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single
|
||
configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add
|
||
to their predecessors.
|
||
|
||
For example, consider this command line:
|
||
|
||
```console
|
||
$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db
|
||
```
|
||
|
||
The `docker-compose.yml` file might specify a `webapp` service.
|
||
|
||
```yaml
|
||
services:
|
||
webapp:
|
||
image: examples/web
|
||
ports:
|
||
- "8000:8000"
|
||
volumes:
|
||
- "/data"
|
||
```
|
||
If the `docker-compose.admin.yml` also specifies this same service, any matching fields override the previous file.
|
||
New values, add to the `webapp` service configuration.
|
||
|
||
```yaml
|
||
services:
|
||
webapp:
|
||
build: .
|
||
environment:
|
||
- DEBUG=1
|
||
```
|
||
|
||
When you use multiple Compose files, all paths in the files are relative to the first configuration file specified
|
||
with `-f`. You can use the `--project-directory` option to override this base path.
|
||
|
||
Use a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the
|
||
configuration are relative to the current working directory.
|
||
|
||
The `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory
|
||
and its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.
|
||
|
||
#### Specifying a path to a single Compose file
|
||
You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either
|
||
from the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.
|
||
|
||
For an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and
|
||
have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to
|
||
get the postgres image for the db service from anywhere by using the `-f` flag as follows:
|
||
|
||
```console
|
||
$ docker compose -f ~/sandbox/rails/compose.yaml pull db
|
||
```
|
||
|
||
### Use `-p` to specify a project name
|
||
|
||
Each configuration has a project name. Compose sets the project name using
|
||
the following mechanisms, in order of precedence:
|
||
- The `-p` command line flag
|
||
- The `COMPOSE_PROJECT_NAME` environment variable
|
||
- The top level `name:` variable from the config file (or the last `name:`
|
||
from a series of config files specified using `-f`)
|
||
- The `basename` of the project directory containing the config file (or
|
||
containing the first config file specified using `-f`)
|
||
- The `basename` of the current directory if no config file is specified
|
||
Project names must contain only lowercase letters, decimal digits, dashes,
|
||
and underscores, and must begin with a lowercase letter or decimal digit. If
|
||
the `basename` of the project directory or current directory violates this
|
||
constraint, you must use one of the other mechanisms.
|
||
|
||
```console
|
||
$ docker compose -p my_project ps -a
|
||
NAME SERVICE STATUS PORTS
|
||
my_project_demo_1 demo running
|
||
|
||
$ docker compose -p my_project logs
|
||
demo_1 | PING localhost (127.0.0.1): 56 data bytes
|
||
demo_1 | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms
|
||
```
|
||
|
||
### Use profiles to enable optional services
|
||
|
||
Use `--profile` to specify one or more active profiles
|
||
Calling `docker compose --profile frontend up` will start the services with the profile `frontend` and services
|
||
without any specified profiles.
|
||
You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.
|
||
|
||
Profiles can also be set by `COMPOSE_PROFILES` environment variable.
|
||
|
||
### Configuring parallelism
|
||
|
||
Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
|
||
Calling `docker compose --parallel 1 pull` will pull the pullable images defined in the Compose file
|
||
one at a time. This can also be used to control build concurrency.
|
||
|
||
Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
|
||
|
||
### Set up environment variables
|
||
|
||
You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.
|
||
|
||
Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,
|
||
`COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag,
|
||
`COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag
|
||
and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag.
|
||
|
||
If flags are explicitly set on the command line, the associated environment variable is ignored.
|
||
|
||
Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned
|
||
containers for the project.
|
||
|
||
|
||
### Use Dry Run mode to test your command
|
||
|
||
Use `--dry-run` flag to test a command without changing your application stack state.
|
||
Dry Run mode shows you all the steps Compose applies when executing a command, for example:
|
||
```console
|
||
$ docker compose --dry-run up --build -d
|
||
[+] Pulling 1/1
|
||
✔ DRY-RUN MODE - db Pulled 0.9s
|
||
[+] Running 10/8
|
||
✔ DRY-RUN MODE - build service backend 0.0s
|
||
✔ DRY-RUN MODE - ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd 0.0s
|
||
✔ DRY-RUN MODE - ==> ==> naming to nginx-golang-mysql-backend 0.0s
|
||
✔ DRY-RUN MODE - Network nginx-golang-mysql_default Created 0.0s
|
||
✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Created 0.0s
|
||
✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Created 0.0s
|
||
✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Created 0.0s
|
||
✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Healthy 0.5s
|
||
✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Started 0.0s
|
||
✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Started Started
|
||
```
|
||
From the example above, you can see that the first step is to pull the image defined by `db` service, then build the `backend` service.
|
||
Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting.
|
||
|
||
Dry Run mode does not currently work with all commands. In particular, you cannot use Dry Run mode with a command that doesn't change the state of a Compose stack
|
||
such as `ps`, `ls`, `logs` for example.
|
||
|
||
Here the list of commands supporting `--dry-run` flag:
|
||
* build
|
||
* cp
|
||
* create
|
||
* down
|
||
* exec
|
||
* kill
|
||
* pause
|
||
* pull
|
||
* push
|
||
* remove
|
||
* restart
|
||
* run
|
||
* start
|
||
* stop
|
||
* unpause
|
||
* up
|
||
usage: docker compose
|
||
pname: docker
|
||
plink: docker.yaml
|
||
cname:
|
||
- docker compose build
|
||
- docker compose config
|
||
- docker compose cp
|
||
- docker compose create
|
||
- docker compose down
|
||
- docker compose events
|
||
- docker compose exec
|
||
- docker compose images
|
||
- docker compose kill
|
||
- docker compose logs
|
||
- docker compose ls
|
||
- docker compose pause
|
||
- docker compose port
|
||
- docker compose ps
|
||
- docker compose pull
|
||
- docker compose push
|
||
- docker compose restart
|
||
- docker compose rm
|
||
- docker compose run
|
||
- docker compose start
|
||
- docker compose stop
|
||
- docker compose top
|
||
- docker compose unpause
|
||
- docker compose up
|
||
- docker compose version
|
||
clink:
|
||
- docker_compose_build.yaml
|
||
- docker_compose_config.yaml
|
||
- docker_compose_cp.yaml
|
||
- docker_compose_create.yaml
|
||
- docker_compose_down.yaml
|
||
- docker_compose_events.yaml
|
||
- docker_compose_exec.yaml
|
||
- docker_compose_images.yaml
|
||
- docker_compose_kill.yaml
|
||
- docker_compose_logs.yaml
|
||
- docker_compose_ls.yaml
|
||
- docker_compose_pause.yaml
|
||
- docker_compose_port.yaml
|
||
- docker_compose_ps.yaml
|
||
- docker_compose_pull.yaml
|
||
- docker_compose_push.yaml
|
||
- docker_compose_restart.yaml
|
||
- docker_compose_rm.yaml
|
||
- docker_compose_run.yaml
|
||
- docker_compose_start.yaml
|
||
- docker_compose_stop.yaml
|
||
- docker_compose_top.yaml
|
||
- docker_compose_unpause.yaml
|
||
- docker_compose_up.yaml
|
||
- docker_compose_version.yaml
|
||
options:
|
||
- option: ansi
|
||
value_type: string
|
||
default_value: auto
|
||
description: |
|
||
Control when to print ANSI control characters ("never"|"always"|"auto")
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: compatibility
|
||
value_type: bool
|
||
default_value: "false"
|
||
description: Run compose in backward compatibility mode
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: dry-run
|
||
value_type: bool
|
||
default_value: "false"
|
||
description: Execute command in dry run mode
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: env-file
|
||
value_type: stringArray
|
||
default_value: '[]'
|
||
description: Specify an alternate environment file.
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: file
|
||
shorthand: f
|
||
value_type: stringArray
|
||
default_value: '[]'
|
||
description: Compose configuration files
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: no-ansi
|
||
value_type: bool
|
||
default_value: "false"
|
||
description: Do not print ANSI control characters (DEPRECATED)
|
||
deprecated: false
|
||
hidden: true
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: parallel
|
||
value_type: int
|
||
default_value: "-1"
|
||
description: Control max parallelism, -1 for unlimited
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: profile
|
||
value_type: stringArray
|
||
default_value: '[]'
|
||
description: Specify a profile to enable
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: project-directory
|
||
value_type: string
|
||
description: |-
|
||
Specify an alternate working directory
|
||
(default: the path of the, first specified, Compose file)
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: project-name
|
||
shorthand: p
|
||
value_type: string
|
||
description: Project name
|
||
deprecated: false
|
||
hidden: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: verbose
|
||
value_type: bool
|
||
default_value: "false"
|
||
description: Show more output
|
||
deprecated: false
|
||
hidden: true
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: version
|
||
shorthand: v
|
||
value_type: bool
|
||
default_value: "false"
|
||
description: Show the Docker Compose version information
|
||
deprecated: false
|
||
hidden: true
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
- option: workdir
|
||
value_type: string
|
||
description: |-
|
||
DEPRECATED! USE --project-directory INSTEAD.
|
||
Specify an alternate working directory
|
||
(default: the path of the, first specified, Compose file)
|
||
deprecated: false
|
||
hidden: true
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
deprecated: false
|
||
experimental: false
|
||
experimentalcli: false
|
||
kubernetes: false
|
||
swarm: false
|
||
|