Debian Codegraph @

docs/reference/compose.md

raw
1 # docker compose
2
3 ```text
4 docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]
5 ```
6
7 <!---MARKER_GEN_START-->
8 Define and run multi-container applications with Docker
9
10 ### Subcommands
11
12 | Name | Description |
13 |:--------------------------------|:----------------------------------------------------------------------------------------|
14 | [`attach`](compose_attach.md) | Attach local standard input, output, and error streams to a service's running container |
15 | [`bridge`](compose_bridge.md) | Convert compose files into another model |
16 | [`build`](compose_build.md) | Build or rebuild services |
17 | [`commit`](compose_commit.md) | Create a new image from a service container's changes |
18 | [`config`](compose_config.md) | Parse, resolve and render compose file in canonical format |
19 | [`cp`](compose_cp.md) | Copy files/folders between a service container and the local filesystem |
20 | [`create`](compose_create.md) | Creates containers for a service |
21 | [`down`](compose_down.md) | Stop and remove containers, networks |
22 | [`events`](compose_events.md) | Receive real time events from containers |
23 | [`exec`](compose_exec.md) | Execute a command in a running container |
24 | [`export`](compose_export.md) | Export a service container's filesystem as a tar archive |
25 | [`images`](compose_images.md) | List images used by the created containers |
26 | [`kill`](compose_kill.md) | Force stop service containers |
27 | [`logs`](compose_logs.md) | View output from containers |
28 | [`ls`](compose_ls.md) | List running compose projects |
29 | [`pause`](compose_pause.md) | Pause services |
30 | [`port`](compose_port.md) | Print the public port for a port binding |
31 | [`ps`](compose_ps.md) | List containers |
32 | [`publish`](compose_publish.md) | Publish compose application |
33 | [`pull`](compose_pull.md) | Pull service images |
34 | [`push`](compose_push.md) | Push service images |
35 | [`restart`](compose_restart.md) | Restart service containers |
36 | [`rm`](compose_rm.md) | Removes stopped service containers |
37 | [`run`](compose_run.md) | Run a one-off command on a service |
38 | [`scale`](compose_scale.md) | Scale services |
39 | [`start`](compose_start.md) | Start services |
40 | [`stats`](compose_stats.md) | Display a live stream of container(s) resource usage statistics |
41 | [`stop`](compose_stop.md) | Stop services |
42 | [`top`](compose_top.md) | Display the running processes |
43 | [`unpause`](compose_unpause.md) | Unpause services |
44 | [`up`](compose_up.md) | Create and start containers |
45 | [`version`](compose_version.md) | Show the Docker Compose version information |
46 | [`volumes`](compose_volumes.md) | List volumes |
47 | [`wait`](compose_wait.md) | Block until containers of all (or specified) services stop. |
48 | [`watch`](compose_watch.md) | Watch build context for service and rebuild/refresh containers when files are updated |
49
50
51 ### Options
52
53 | Name | Type | Default | Description |
54 |:-----------------------|:--------------|:--------|:----------------------------------------------------------------------------------------------------|
55 | `--all-resources` | `bool` | | Include all resources, even those not used by services |
56 | `--ansi` | `string` | `auto` | Control when to print ANSI control characters ("never"\|"always"\|"auto") |
57 | `--compatibility` | `bool` | | Run compose in backward compatibility mode |
58 | `--dry-run` | `bool` | | Execute command in dry run mode |
59 | `--env-file` | `stringArray` | | Specify an alternate environment file |
60 | `-f`, `--file` | `stringArray` | | Compose configuration files |
61 | `--parallel` | `int` | `-1` | Control max parallelism, -1 for unlimited |
62 | `--profile` | `stringArray` | | Specify a profile to enable |
63 | `--progress` | `string` | | Set type of progress output (auto, tty, plain, json, quiet) |
64 | `--project-directory` | `string` | | Specify an alternate working directory<br>(default: the path of the, first specified, Compose file) |
65 | `-p`, `--project-name` | `string` | | Project name |
66
67
68 <!---MARKER_GEN_END-->
69
70 ## Examples
71
72 ### Use `-f` to specify the name and path of one or more Compose files
73 Use the `-f` flag to specify the location of a Compose [configuration file](/reference/compose-file/).
74
75 #### Specifying multiple Compose files
76 You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single
77 configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add
78 to their predecessors.
79
80 For example, consider this command line:
81
82 ```console
83 $ docker compose -f compose.yaml -f compose.admin.yaml run backup_db
84 ```
85
86 The `compose.yaml` file might specify a `webapp` service.
87
88 ```yaml
89 services:
90 webapp:
91 image: examples/web
92 ports:
93 - "8000:8000"
94 volumes:
95 - "/data"
96 ```
97 If the `compose.admin.yaml` also specifies this same service, any matching fields override the previous file.
98 New values, add to the `webapp` service configuration.
99
100 ```yaml
101 services:
102 webapp:
103 build: .
104 environment:
105 - DEBUG=1
106 ```
107
108 When you use multiple Compose files, all paths in the files are relative to the first configuration file specified
109 with `-f`. You can use the `--project-directory` option to override this base path.
110
111 Use a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the
112 configuration are relative to the current working directory.
113
114 The `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory
115 and its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.
116
117 #### Specifying a path to a single Compose file
118 You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either
119 from the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.
120
121 For an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and
122 have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to
123 get the postgres image for the db service from anywhere by using the `-f` flag as follows:
124
125 ```console
126 $ docker compose -f ~/sandbox/rails/compose.yaml pull db
127 ```
128
129 ### Use `-p` to specify a project name
130
131 Each configuration has a project name. Compose sets the project name using
132 the following mechanisms, in order of precedence:
133 - The `-p` command line flag
134 - The `COMPOSE_PROJECT_NAME` environment variable
135 - The top level `name:` variable from the config file (or the last `name:`
136 from a series of config files specified using `-f`)
137 - The `basename` of the project directory containing the config file (or
138 containing the first config file specified using `-f`)
139 - The `basename` of the current directory if no config file is specified
140 Project names must contain only lowercase letters, decimal digits, dashes,
141 and underscores, and must begin with a lowercase letter or decimal digit. If
142 the `basename` of the project directory or current directory violates this
143 constraint, you must use one of the other mechanisms.
144
145 ```console
146 $ docker compose -p my_project ps -a
147 NAME SERVICE STATUS PORTS
148 my_project_demo_1 demo running
149
150 $ docker compose -p my_project logs
151 demo_1 | PING localhost (127.0.0.1): 56 data bytes
152 demo_1 | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms
153 ```
154
155 ### Use profiles to enable optional services
156
157 Use `--profile` to specify one or more active profiles
158 Calling `docker compose --profile frontend up` starts the services with the profile `frontend` and services
159 without any specified profiles.
160 You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` is enabled.
161
162 Profiles can also be set by `COMPOSE_PROFILES` environment variable.
163
164 ### Configuring parallelism
165
166 Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
167 Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
168 one at a time. This can also be used to control build concurrency.
169
170 Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
171
172 ### Set up environment variables
173
174 You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.
175
176 Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,
177 `COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag,
178 `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag
179 and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag.
180
181 If flags are explicitly set on the command line, the associated environment variable is ignored.
182
183 Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` stops docker compose from detecting orphaned
184 containers for the project.
185
186 Setting the `COMPOSE_MENU` environment variable to `false` disables the helper menu when running `docker compose up`
187 in attached mode. Alternatively, you can also run `docker compose up --menu=false` to disable the helper menu.
188
189 ### Use Dry Run mode to test your command
190
191 Use `--dry-run` flag to test a command without changing your application stack state.
192 Dry Run mode shows you all the steps Compose applies when executing a command, for example:
193 ```console
194 $ docker compose --dry-run up --build -d
195 [+] Pulling 1/1
196 ✔ DRY-RUN MODE - db Pulled 0.9s
197 [+] Running 10/8
198 ✔ DRY-RUN MODE - build service backend 0.0s
199 ✔ DRY-RUN MODE - ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd 0.0s
200 ✔ DRY-RUN MODE - ==> ==> naming to nginx-golang-mysql-backend 0.0s
201 ✔ DRY-RUN MODE - Network nginx-golang-mysql_default Created 0.0s
202 ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Created 0.0s
203 ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Created 0.0s
204 ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Created 0.0s
205 ✔ DRY-RUN MODE - Container nginx-golang-mysql-db-1 Healthy 0.5s
206 ✔ DRY-RUN MODE - Container nginx-golang-mysql-backend-1 Started 0.0s
207 ✔ DRY-RUN MODE - Container nginx-golang-mysql-proxy-1 Started Started
208 ```
209 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.
210 Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting.
211
212 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.