| 1 |
command: docker compose |
| 2 |
short: Docker Compose |
| 3 |
long: Define and run multi-container applications with Docker |
| 4 |
usage: docker compose |
| 5 |
pname: docker |
| 6 |
plink: docker.yaml |
| 7 |
cname: |
| 8 |
- docker compose attach |
| 9 |
- docker compose bridge |
| 10 |
- docker compose build |
| 11 |
- docker compose commit |
| 12 |
- docker compose config |
| 13 |
- docker compose cp |
| 14 |
- docker compose create |
| 15 |
- docker compose down |
| 16 |
- docker compose events |
| 17 |
- docker compose exec |
| 18 |
- docker compose export |
| 19 |
- docker compose images |
| 20 |
- docker compose kill |
| 21 |
- docker compose logs |
| 22 |
- docker compose ls |
| 23 |
- docker compose pause |
| 24 |
- docker compose port |
| 25 |
- docker compose ps |
| 26 |
- docker compose publish |
| 27 |
- docker compose pull |
| 28 |
- docker compose push |
| 29 |
- docker compose restart |
| 30 |
- docker compose rm |
| 31 |
- docker compose run |
| 32 |
- docker compose scale |
| 33 |
- docker compose start |
| 34 |
- docker compose stats |
| 35 |
- docker compose stop |
| 36 |
- docker compose top |
| 37 |
- docker compose unpause |
| 38 |
- docker compose up |
| 39 |
- docker compose version |
| 40 |
- docker compose volumes |
| 41 |
- docker compose wait |
| 42 |
- docker compose watch |
| 43 |
clink: |
| 44 |
- docker_compose_attach.yaml |
| 45 |
- docker_compose_bridge.yaml |
| 46 |
- docker_compose_build.yaml |
| 47 |
- docker_compose_commit.yaml |
| 48 |
- docker_compose_config.yaml |
| 49 |
- docker_compose_cp.yaml |
| 50 |
- docker_compose_create.yaml |
| 51 |
- docker_compose_down.yaml |
| 52 |
- docker_compose_events.yaml |
| 53 |
- docker_compose_exec.yaml |
| 54 |
- docker_compose_export.yaml |
| 55 |
- docker_compose_images.yaml |
| 56 |
- docker_compose_kill.yaml |
| 57 |
- docker_compose_logs.yaml |
| 58 |
- docker_compose_ls.yaml |
| 59 |
- docker_compose_pause.yaml |
| 60 |
- docker_compose_port.yaml |
| 61 |
- docker_compose_ps.yaml |
| 62 |
- docker_compose_publish.yaml |
| 63 |
- docker_compose_pull.yaml |
| 64 |
- docker_compose_push.yaml |
| 65 |
- docker_compose_restart.yaml |
| 66 |
- docker_compose_rm.yaml |
| 67 |
- docker_compose_run.yaml |
| 68 |
- docker_compose_scale.yaml |
| 69 |
- docker_compose_start.yaml |
| 70 |
- docker_compose_stats.yaml |
| 71 |
- docker_compose_stop.yaml |
| 72 |
- docker_compose_top.yaml |
| 73 |
- docker_compose_unpause.yaml |
| 74 |
- docker_compose_up.yaml |
| 75 |
- docker_compose_version.yaml |
| 76 |
- docker_compose_volumes.yaml |
| 77 |
- docker_compose_wait.yaml |
| 78 |
- docker_compose_watch.yaml |
| 79 |
options: |
| 80 |
- option: all-resources |
| 81 |
value_type: bool |
| 82 |
default_value: "false" |
| 83 |
description: Include all resources, even those not used by services |
| 84 |
deprecated: false |
| 85 |
hidden: false |
| 86 |
experimental: false |
| 87 |
experimentalcli: false |
| 88 |
kubernetes: false |
| 89 |
swarm: false |
| 90 |
- option: ansi |
| 91 |
value_type: string |
| 92 |
default_value: auto |
| 93 |
description: | |
| 94 |
Control when to print ANSI control characters ("never"|"always"|"auto") |
| 95 |
deprecated: false |
| 96 |
hidden: false |
| 97 |
experimental: false |
| 98 |
experimentalcli: false |
| 99 |
kubernetes: false |
| 100 |
swarm: false |
| 101 |
- option: compatibility |
| 102 |
value_type: bool |
| 103 |
default_value: "false" |
| 104 |
description: Run compose in backward compatibility mode |
| 105 |
deprecated: false |
| 106 |
hidden: false |
| 107 |
experimental: false |
| 108 |
experimentalcli: false |
| 109 |
kubernetes: false |
| 110 |
swarm: false |
| 111 |
- option: dry-run |
| 112 |
value_type: bool |
| 113 |
default_value: "false" |
| 114 |
description: Execute command in dry run mode |
| 115 |
deprecated: false |
| 116 |
hidden: false |
| 117 |
experimental: false |
| 118 |
experimentalcli: false |
| 119 |
kubernetes: false |
| 120 |
swarm: false |
| 121 |
- option: env-file |
| 122 |
value_type: stringArray |
| 123 |
default_value: '[]' |
| 124 |
description: Specify an alternate environment file |
| 125 |
deprecated: false |
| 126 |
hidden: false |
| 127 |
experimental: false |
| 128 |
experimentalcli: false |
| 129 |
kubernetes: false |
| 130 |
swarm: false |
| 131 |
- option: file |
| 132 |
shorthand: f |
| 133 |
value_type: stringArray |
| 134 |
default_value: '[]' |
| 135 |
description: Compose configuration files |
| 136 |
deprecated: false |
| 137 |
hidden: false |
| 138 |
experimental: false |
| 139 |
experimentalcli: false |
| 140 |
kubernetes: false |
| 141 |
swarm: false |
| 142 |
- option: no-ansi |
| 143 |
value_type: bool |
| 144 |
default_value: "false" |
| 145 |
description: Do not print ANSI control characters (DEPRECATED) |
| 146 |
deprecated: false |
| 147 |
hidden: true |
| 148 |
experimental: false |
| 149 |
experimentalcli: false |
| 150 |
kubernetes: false |
| 151 |
swarm: false |
| 152 |
- option: parallel |
| 153 |
value_type: int |
| 154 |
default_value: "-1" |
| 155 |
description: Control max parallelism, -1 for unlimited |
| 156 |
deprecated: false |
| 157 |
hidden: false |
| 158 |
experimental: false |
| 159 |
experimentalcli: false |
| 160 |
kubernetes: false |
| 161 |
swarm: false |
| 162 |
- option: profile |
| 163 |
value_type: stringArray |
| 164 |
default_value: '[]' |
| 165 |
description: Specify a profile to enable |
| 166 |
deprecated: false |
| 167 |
hidden: false |
| 168 |
experimental: false |
| 169 |
experimentalcli: false |
| 170 |
kubernetes: false |
| 171 |
swarm: false |
| 172 |
- option: progress |
| 173 |
value_type: string |
| 174 |
description: Set type of progress output (auto, tty, plain, json, quiet) |
| 175 |
deprecated: false |
| 176 |
hidden: false |
| 177 |
experimental: false |
| 178 |
experimentalcli: false |
| 179 |
kubernetes: false |
| 180 |
swarm: false |
| 181 |
- option: project-directory |
| 182 |
value_type: string |
| 183 |
description: |- |
| 184 |
Specify an alternate working directory |
| 185 |
(default: the path of the, first specified, Compose file) |
| 186 |
deprecated: false |
| 187 |
hidden: false |
| 188 |
experimental: false |
| 189 |
experimentalcli: false |
| 190 |
kubernetes: false |
| 191 |
swarm: false |
| 192 |
- option: project-name |
| 193 |
shorthand: p |
| 194 |
value_type: string |
| 195 |
description: Project name |
| 196 |
deprecated: false |
| 197 |
hidden: false |
| 198 |
experimental: false |
| 199 |
experimentalcli: false |
| 200 |
kubernetes: false |
| 201 |
swarm: false |
| 202 |
- option: verbose |
| 203 |
value_type: bool |
| 204 |
default_value: "false" |
| 205 |
description: Show more output |
| 206 |
deprecated: false |
| 207 |
hidden: true |
| 208 |
experimental: false |
| 209 |
experimentalcli: false |
| 210 |
kubernetes: false |
| 211 |
swarm: false |
| 212 |
- option: version |
| 213 |
shorthand: v |
| 214 |
value_type: bool |
| 215 |
default_value: "false" |
| 216 |
description: Show the Docker Compose version information |
| 217 |
deprecated: false |
| 218 |
hidden: true |
| 219 |
experimental: false |
| 220 |
experimentalcli: false |
| 221 |
kubernetes: false |
| 222 |
swarm: false |
| 223 |
- option: workdir |
| 224 |
value_type: string |
| 225 |
description: |- |
| 226 |
DEPRECATED! USE --project-directory INSTEAD. |
| 227 |
Specify an alternate working directory |
| 228 |
(default: the path of the, first specified, Compose file) |
| 229 |
deprecated: false |
| 230 |
hidden: true |
| 231 |
experimental: false |
| 232 |
experimentalcli: false |
| 233 |
kubernetes: false |
| 234 |
swarm: false |
| 235 |
examples: |- |
| 236 |
### Use `-f` to specify the name and path of one or more Compose files |
| 237 |
Use the `-f` flag to specify the location of a Compose [configuration file](/reference/compose-file/). |
| 238 |
|
| 239 |
#### Specifying multiple Compose files |
| 240 |
You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single |
| 241 |
configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add |
| 242 |
to their predecessors. |
| 243 |
|
| 244 |
For example, consider this command line: |
| 245 |
|
| 246 |
```console |
| 247 |
$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db |
| 248 |
``` |
| 249 |
|
| 250 |
The `compose.yaml` file might specify a `webapp` service. |
| 251 |
|
| 252 |
```yaml |
| 253 |
services: |
| 254 |
webapp: |
| 255 |
image: examples/web |
| 256 |
ports: |
| 257 |
- "8000:8000" |
| 258 |
volumes: |
| 259 |
- "/data" |
| 260 |
``` |
| 261 |
If the `compose.admin.yaml` also specifies this same service, any matching fields override the previous file. |
| 262 |
New values, add to the `webapp` service configuration. |
| 263 |
|
| 264 |
```yaml |
| 265 |
services: |
| 266 |
webapp: |
| 267 |
build: . |
| 268 |
environment: |
| 269 |
- DEBUG=1 |
| 270 |
``` |
| 271 |
|
| 272 |
When you use multiple Compose files, all paths in the files are relative to the first configuration file specified |
| 273 |
with `-f`. You can use the `--project-directory` option to override this base path. |
| 274 |
|
| 275 |
Use a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the |
| 276 |
configuration are relative to the current working directory. |
| 277 |
|
| 278 |
The `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory |
| 279 |
and its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file. |
| 280 |
|
| 281 |
#### Specifying a path to a single Compose file |
| 282 |
You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either |
| 283 |
from the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file. |
| 284 |
|
| 285 |
For an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and |
| 286 |
have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to |
| 287 |
get the postgres image for the db service from anywhere by using the `-f` flag as follows: |
| 288 |
|
| 289 |
```console |
| 290 |
$ docker compose -f ~/sandbox/rails/compose.yaml pull db |
| 291 |
``` |
| 292 |
|
| 293 |
### Use `-p` to specify a project name |
| 294 |
|
| 295 |
Each configuration has a project name. Compose sets the project name using |
| 296 |
the following mechanisms, in order of precedence: |
| 297 |
- The `-p` command line flag |
| 298 |
- The `COMPOSE_PROJECT_NAME` environment variable |
| 299 |
- The top level `name:` variable from the config file (or the last `name:` |
| 300 |
from a series of config files specified using `-f`) |
| 301 |
- The `basename` of the project directory containing the config file (or |
| 302 |
containing the first config file specified using `-f`) |
| 303 |
- The `basename` of the current directory if no config file is specified |
| 304 |
Project names must contain only lowercase letters, decimal digits, dashes, |
| 305 |
and underscores, and must begin with a lowercase letter or decimal digit. If |
| 306 |
the `basename` of the project directory or current directory violates this |
| 307 |
constraint, you must use one of the other mechanisms. |
| 308 |
|
| 309 |
```console |
| 310 |
$ docker compose -p my_project ps -a |
| 311 |
NAME SERVICE STATUS PORTS |
| 312 |
my_project_demo_1 demo running |
| 313 |
|
| 314 |
$ docker compose -p my_project logs |
| 315 |
demo_1 | PING localhost (127.0.0.1): 56 data bytes |
| 316 |
demo_1 | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms |
| 317 |
``` |
| 318 |
|
| 319 |
### Use profiles to enable optional services |
| 320 |
|
| 321 |
Use `--profile` to specify one or more active profiles |
| 322 |
Calling `docker compose --profile frontend up` starts the services with the profile `frontend` and services |
| 323 |
without any specified profiles. |
| 324 |
You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` is enabled. |
| 325 |
|
| 326 |
Profiles can also be set by `COMPOSE_PROFILES` environment variable. |
| 327 |
|
| 328 |
### Configuring parallelism |
| 329 |
|
| 330 |
Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls. |
| 331 |
Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file |
| 332 |
one at a time. This can also be used to control build concurrency. |
| 333 |
|
| 334 |
Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable. |
| 335 |
|
| 336 |
### Set up environment variables |
| 337 |
|
| 338 |
You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags. |
| 339 |
|
| 340 |
Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag, |
| 341 |
`COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag, |
| 342 |
`COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag |
| 343 |
and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag. |
| 344 |
|
| 345 |
If flags are explicitly set on the command line, the associated environment variable is ignored. |
| 346 |
|
| 347 |
Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` stops docker compose from detecting orphaned |
| 348 |
containers for the project. |
| 349 |
|
| 350 |
Setting the `COMPOSE_MENU` environment variable to `false` disables the helper menu when running `docker compose up` |
| 351 |
in attached mode. Alternatively, you can also run `docker compose up --menu=false` to disable the helper menu. |
| 352 |
|
| 353 |
### Use Dry Run mode to test your command |
| 354 |
|
| 355 |
Use `--dry-run` flag to test a command without changing your application stack state. |
| 356 |
Dry Run mode shows you all the steps Compose applies when executing a command, for example: |
| 357 |
```console |
| 358 |
$ docker compose --dry-run up --build -d |
| 359 |
[+] Pulling 1/1 |
| 360 |
✔ DRY-RUN MODE - db Pulled 0.9s |
| 361 |
[+] Running 10/8 |
| 362 |
✔ DRY-RUN MODE - build service backend 0.0s |
| 363 |
✔ DRY-RUN MODE - ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd 0.0s |
| 364 |
✔ DRY-RUN MODE - ==> ==> naming to nginx-golang-mysql-backend 0.0s |
| 365 |
✔ DRY-RUN MODE - Network nginx-golang-mysql_default Created 0.0s |
| 366 |
✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Created 0.0s |
| 367 |
✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Created 0.0s |
| 368 |
✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Created 0.0s |
| 369 |
✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Healthy 0.5s |
| 370 |
✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Started 0.0s |
| 371 |
✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Started Started |
| 372 |
``` |
| 373 |
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. |
| 374 |
Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting. |
| 375 |
|
| 376 |
Dry Run mode works with almost all commands. 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. |
| 377 |
deprecated: false |
| 378 |
hidden: false |
| 379 |
experimental: false |
| 380 |
experimentalcli: false |
| 381 |
kubernetes: false |
| 382 |
swarm: false |
| 383 |
|