docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ENDOCS-2254 (#21205) 

* ENDOCS-2254

* formatting
This commit is contained in:
Allie Sadler 2024-10-23 09:22:45 +01:00 committed by GitHub
parent 04fabb3c6d
commit e328d00b20
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 150 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

308
content/manuals/compose/how-tos/multiple-compose-files/merge.md
View File

@ -67,25 +67,167 @@ webapp:
- "/data"
environment:
- DEBUG=1
- ANOTHER_VARIABLE=value
```
> [!IMPORTANT]
>
> When you use multiple Compose files, you must make sure all paths in the
files are relative to the base Compose file (the first Compose file specified
## Merging rules
- Paths are evaluated relative to the base file. When you use multiple Compose files, you must make sure all paths in the files are relative to the base Compose file (the first Compose file specified
with `-f`). This is required because override files need not be valid
Compose files. Override files can contain small fragments of configuration.
Tracking which fragment of a service is relative to which path is difficult and
confusing, so to keep paths easier to understand, all paths must be defined
relative to the base file.
>[!TIP]
>
> You can use `docker compose config` to review your merged configuration and avoid path-related issues.
- Compose copies configurations from the original service over to the local one.
If a configuration option is defined in both the original service and the local
service, the local value replaces or extends the original value.
- For single-value options like `image`, `command` or `mem_limit`, the new value replaces the old value.
original service:
```yaml
services:
myservice:
# ...
command: python app.py
```
local service:
```yaml
services:
myservice:
# ...
command: python otherapp.py
```
result:
```yaml
services:
myservice:
# ...
command: python otherapp.py
```
- For the multi-value options `ports`, `expose`, `external_links`, `dns`, `dns_search`, and `tmpfs`, Compose concatenates both sets of values:
original service:
```yaml
services:
myservice:
# ...
expose:
- "3000"
```
local service:
```yaml
services:
myservice:
# ...
expose:
- "4000"
- "5000"
```
result:
```yaml
services:
myservice:
# ...
expose:
- "3000"
- "4000"
- "5000"
```
- In the case of `environment`, `labels`, `volumes`, and `devices`, Compose "merges" entries together with locally defined values taking precedence. For `environment` and `labels`, the environment variable or label name determines which value is used:
original service:
```yaml
services:
myservice:
# ...
environment:
- FOO=original
- BAR=original
```
local service:
```yaml
services:
myservice:
# ...
environment:
- BAR=local
- BAZ=local
```
result:
```yaml
services:
myservice:
# ...
environment:
- FOO=original
- BAR=local
- BAZ=local
```
- Entries for `volumes` and `devices` are merged using the mount path in the container:
original service:
```yaml
services:
myservice:
# ...
volumes:
- ./original:/foo
- ./original:/bar
```
local service:
```yaml
services:
myservice:
# ...
volumes:
- ./local:/bar
- ./local:/baz
```
result:
```yaml
services:
myservice:
# ...
volumes:
- ./original:/foo
- ./local:/bar
- ./local:/baz
```
For more merging rules, see [Merge and override](/reference/compose-file/merge.md) in the Compose Specification.
### Additional information
- Using `-f` is optional. If not provided, Compose searches the working directory and its parent directories for a `compose.yml` and a `compose.override.yml` file. You must supply at least the `compose.yml` file. If both files exist on the same directory level, Compose combines them into a single configuration.
- 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.
- You can use a `-f` with `-` (dash) as the filename to read the configuration from `stdin`. For example:
```console
$ docker compose -f - <<EOF
@ -129,156 +271,6 @@ relative to the base file.
Status: Downloaded newer image for postgres:latest
```
## Merging rules
Compose copies configurations from the original service over to the local one.
If a configuration option is defined in both the original service and the local
service, the local value replaces or extends the original value.
For single-value options like `image`, `command` or `mem_limit`, the new value
replaces the old value.
original service:
```yaml
services:
myservice:
# ...
command: python app.py
```
local service:
```yaml
services:
myservice:
# ...
command: python otherapp.py
```
result:
```yaml
services:
myservice:
# ...
command: python otherapp.py
```
For the multi-value options `ports`, `expose`, `external_links`, `dns`,
`dns_search`, and `tmpfs`, Compose concatenates both sets of values:
original service:
```yaml
services:
myservice:
# ...
expose:
- "3000"
```
local service:
```yaml
services:
myservice:
# ...
expose:
- "4000"
- "5000"
```
result:
```yaml
services:
myservice:
# ...
expose:
- "3000"
- "4000"
- "5000"
```
In the case of `environment`, `labels`, `volumes`, and `devices`, Compose
"merges" entries together with locally defined values taking precedence. For
`environment` and `labels`, the environment variable or label name determines
which value is used:
original service:
```yaml
services:
myservice:
# ...
environment:
- FOO=original
- BAR=original
```
local service:
```yaml
services:
myservice:
# ...
environment:
- BAR=local
- BAZ=local
```
result:
```yaml
services:
myservice:
# ...
environment:
- FOO=original
- BAR=local
- BAZ=local
```
Entries for `volumes` and `devices` are merged using the mount path in the
container:
original service:
```yaml
services:
myservice:
# ...
volumes:
- ./original:/foo
- ./original:/bar
```
local service:
```yaml
services:
myservice:
# ...
volumes:
- ./local:/bar
- ./local:/baz
```
result:
```yaml
services:
myservice:
# ...
volumes:
- ./original:/foo
- ./local:/bar
- ./local:/baz
```
For more merging rules, see [Merge and override](/reference/compose-file/merge.md) in the Compose Specification.
## Example
A common use case for multiple files is changing a development Compose app
@ -335,7 +327,7 @@ services:
When you run `docker compose up` it reads the overrides automatically.
To use this Compose app in a production environment, another override file is created, which might be stored in a different git
repo or managed by a different team.
repository or managed by a different team.
`compose.prod.yml`