mirror of https://github.com/docker/compose.git
Change links and add versioning information
Signed-off-by: aevesdocker <allie.sadler@docker.com>
This commit is contained in:
aevesdocker
Nicolas De loof
parent
fe42107f41
commit
0d4edbbd19
|
|
@ -0,0 +1,474 @@
|
||||||
|
There are three legacy versions of the Compose file format:
|
||||||
|
|
||||||
|
- Version 1. This is specified by omitting a `version` key at the root of the YAML.
|
||||||
|
|
||||||
|
- Version 2.x. This is specified with a `version: '2'` or `version: '2.1'`, etc., entry at the root of the YAML.
|
||||||
|
|
||||||
|
- Version 3.x, designed to be cross-compatible between Compose and the Docker Engine's
|
||||||
|
[swarm mode](https://docs.docker.com/engine/swarm/). This is specified with a `version: '3'` or `version: '3.1'`, etc., entry at the root of the YAML.
|
||||||
|
|
||||||
|
The latest and recommended version of the Compose file format is defined by the [Compose Specification](https://docs.docker.com/compose/compose-file/). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**.
|
||||||
|
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
>
|
||||||
|
> If you're using [multiple Compose files](https://docs.docker.com/compose/multiple-compose-files/) or
|
||||||
|
> [extending services](https://docs.docker.com/compose/multiple-compose-files/extends/),
|
||||||
|
> each file must be of the same version - you cannot, for example,
|
||||||
|
> mix version 1 and 2 in a single project.
|
||||||
|
|
||||||
|
Several things differ depending on which version you use:
|
||||||
|
|
||||||
|
- The structure and permitted configuration keys
|
||||||
|
- The minimum Docker Engine version you must be running
|
||||||
|
- Compose's behaviour with regards to networking
|
||||||
|
|
||||||
|
These differences are explained below.
|
||||||
|
|
||||||
|
### Version 2
|
||||||
|
|
||||||
|
Compose files using the version 2 syntax must indicate the version number at
|
||||||
|
the root of the document. All [services](compose-file-v2.md#service-configuration-reference)
|
||||||
|
must be declared under the `services` key.
|
||||||
|
|
||||||
|
Version 2 files are supported by **Compose 1.6.0+** and require a Docker Engine
|
||||||
|
of version **1.10.0+**.
|
||||||
|
|
||||||
|
Named [volumes](compose-file-v2.md#volume-configuration-reference) can be declared under the
|
||||||
|
`volumes` key, and [networks](compose-file-v2.md#network-configuration-reference) can be declared
|
||||||
|
under the `networks` key.
|
||||||
|
|
||||||
|
By default, every container joins an application-wide default network, and is
|
||||||
|
discoverable at a hostname that's the same as the service name. This means
|
||||||
|
[links](compose-file-v2.md#links) are largely unnecessary. For more details, see
|
||||||
|
[Networking in Compose](https://docs.docker.com/compose/networking/).
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
>
|
||||||
|
> With Compose version 2, when specifying the Compose file version to use, make sure to
|
||||||
|
> specify both the _major_ and _minor_ numbers. If no minor version is given,
|
||||||
|
> `0` is used by default and not the latest minor version. As a result, features added in later versions will not be supported. For example:
|
||||||
|
>
|
||||||
|
> ```yaml
|
||||||
|
> version: "2"
|
||||||
|
> ```
|
||||||
|
>
|
||||||
|
> is equivalent to:
|
||||||
|
>
|
||||||
|
> ```yaml
|
||||||
|
> version: "2.0"
|
||||||
|
> ```
|
||||||
|
|
||||||
|
Simple example:
|
||||||
|
|
||||||
|
version: "{{% param "compose_file_v2" %}}"
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
ports:
|
||||||
|
- "8000:5000"
|
||||||
|
volumes:
|
||||||
|
- .:/code
|
||||||
|
redis:
|
||||||
|
image: redis
|
||||||
|
|
||||||
|
A more extended example, defining volumes and networks:
|
||||||
|
|
||||||
|
version: "{{% param "compose_file_v2" %}}"
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
ports:
|
||||||
|
- "8000:5000"
|
||||||
|
volumes:
|
||||||
|
- .:/code
|
||||||
|
networks:
|
||||||
|
- front-tier
|
||||||
|
- back-tier
|
||||||
|
redis:
|
||||||
|
image: redis
|
||||||
|
volumes:
|
||||||
|
- redis-data:/var/lib/redis
|
||||||
|
networks:
|
||||||
|
- back-tier
|
||||||
|
volumes:
|
||||||
|
redis-data:
|
||||||
|
driver: local
|
||||||
|
networks:
|
||||||
|
front-tier:
|
||||||
|
driver: bridge
|
||||||
|
back-tier:
|
||||||
|
driver: bridge
|
||||||
|
|
||||||
|
Several other options were added to support networking, such as:
|
||||||
|
|
||||||
|
* [`aliases`](compose-file-v2.md#aliases)
|
||||||
|
|
||||||
|
* The [`depends_on`](compose-file-v2.md#depends_on) option can be used in place of links to indicate dependencies
|
||||||
|
between services and startup order.
|
||||||
|
|
||||||
|
version: "{{% param "compose_file_v2" %}}"
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
depends_on:
|
||||||
|
- db
|
||||||
|
- redis
|
||||||
|
redis:
|
||||||
|
image: redis
|
||||||
|
db:
|
||||||
|
image: postgres
|
||||||
|
|
||||||
|
* [`ipv4_address`, `ipv6_address`](compose-file-v2.md#ipv4_address-ipv6_address)
|
||||||
|
|
||||||
|
[Variable substitution](compose-file-v2.md#variable-substitution) also was added in Version 2.
|
||||||
|
|
||||||
|
### Version 2.1
|
||||||
|
|
||||||
|
An upgrade of [version 2](#version-2) that introduces new parameters only
|
||||||
|
available with Docker Engine version **1.12.0+**. Version 2.1 files are
|
||||||
|
supported by **Compose 1.9.0+**.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`link_local_ips`](compose-file-v2.md#link_local_ips)
|
||||||
|
- [`isolation`](compose-file-v2.md#isolation-1) in build configurations and
|
||||||
|
service definitions
|
||||||
|
- `labels` for [volumes](compose-file-v2.md#volume-configuration-reference),
|
||||||
|
[networks](compose-file-v2.md#network-configuration-reference), and
|
||||||
|
[build](compose-file-v3.md#build)
|
||||||
|
- `name` for [volumes](compose-file-v2.md#volume-configuration-reference)
|
||||||
|
- [`userns_mode`](compose-file-v2.md#userns_mode)
|
||||||
|
- [`healthcheck`](compose-file-v2.md#healthcheck)
|
||||||
|
- [`sysctls`](compose-file-v2.md#sysctls)
|
||||||
|
- [`pids_limit`](compose-file-v2.md#pids_limit)
|
||||||
|
- [`oom_kill_disable`](compose-file-v2.md#cpu-and-other-resources)
|
||||||
|
- [`cpu_period`](compose-file-v2.md#cpu-and-other-resources)
|
||||||
|
|
||||||
|
### Version 2.2
|
||||||
|
|
||||||
|
An upgrade of [version 2.1](#version-21) that introduces new parameters only
|
||||||
|
available with Docker Engine version **1.13.0+**. Version 2.2 files are
|
||||||
|
supported by **Compose 1.13.0+**. This version also allows you to specify
|
||||||
|
default scale numbers inside the service's configuration.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`init`](compose-file-v2.md#init)
|
||||||
|
- [`scale`](compose-file-v2.md#scale)
|
||||||
|
- [`cpu_rt_runtime` and `cpu_rt_period`](compose-file-v2.md#cpu_rt_runtime-cpu_rt_period)
|
||||||
|
- [`network`](compose-file-v2.md#network) for [build configurations](compose-file-v2.md#build)
|
||||||
|
|
||||||
|
### Version 2.3
|
||||||
|
|
||||||
|
An upgrade of [version 2.2](#version-22) that introduces new parameters only
|
||||||
|
available with Docker Engine version **17.06.0+**. Version 2.3 files are
|
||||||
|
supported by **Compose 1.16.0+**.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`target`](compose-file-v2.md#target), [`extra_hosts`](compose-file-v2.md#extra_hosts-1) and
|
||||||
|
[`shm_size`](compose-file-v2.md#shm_size) for [build configurations](compose-file-v2.md#build)
|
||||||
|
- `start_period` for [`healthchecks`](compose-file-v2.md#healthcheck)
|
||||||
|
- ["Long syntax" for volumes](compose-file-v2.md#long-syntax)
|
||||||
|
- [`runtime`](compose-file-v2.md#runtime) for service definitions
|
||||||
|
- [`device_cgroup_rules`](compose-file-v2.md#device_cgroup_rules)
|
||||||
|
|
||||||
|
### Version 2.4
|
||||||
|
|
||||||
|
An upgrade of [version 2.3](#version-23) that introduces new parameters only
|
||||||
|
available with Docker Engine version **17.12.0+**. Version 2.4 files are
|
||||||
|
supported by **Compose 1.21.0+**.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`platform`](compose-file-v2.md#platform) for service definitions
|
||||||
|
- Support for extension fields at the root of service, network, and volume
|
||||||
|
definitions
|
||||||
|
|
||||||
|
### Version 3
|
||||||
|
|
||||||
|
Designed to be cross-compatible between Compose and the Docker Engine's
|
||||||
|
[swarm mode](/engine/swarm/), version 3 removes several options and adds
|
||||||
|
several more.
|
||||||
|
|
||||||
|
- Removed: `volume_driver`, `volumes_from`, `cpu_shares`, `cpu_quota`,
|
||||||
|
`cpuset`, `mem_limit`, `memswap_limit`, `extends`, `group_add`. See
|
||||||
|
the [upgrading](#upgrading) guide for how to migrate away from these.
|
||||||
|
|
||||||
|
- Added: [deploy](compose-file-v3.md#deploy)
|
||||||
|
|
||||||
|
If only the major version is given (`version: '3'`),
|
||||||
|
the latest minor version is used by default.
|
||||||
|
|
||||||
|
### Version 3.1
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters only
|
||||||
|
available with Docker Engine version **1.13.1+**, and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`secrets`](compose-file-v3.md#secrets)
|
||||||
|
|
||||||
|
### Version 3.2
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters only
|
||||||
|
available with Docker Engine version **17.04.0+**, and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`cache_from`](compose-file-v3.md#cache_from) in [build configurations](compose-file-v3.md#build)
|
||||||
|
- Long syntax for [ports](compose-file-v3.md#ports) and [volume mounts](compose-file-v3.md#volumes)
|
||||||
|
- [`attachable`](compose-file-v3.md#attachable) network driver option
|
||||||
|
- [deploy `endpoint_mode`](compose-file-v3.md#endpoint_mode)
|
||||||
|
- [deploy placement `preference`](compose-file-v3.md#placement)
|
||||||
|
|
||||||
|
### Version 3.3
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters only
|
||||||
|
available with Docker Engine version **17.06.0+**, and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [build `labels`](compose-file-v3.md#build)
|
||||||
|
- [`credential_spec`](compose-file-v3.md#credential_spec)
|
||||||
|
- [`configs`](compose-file-v3.md#configs)
|
||||||
|
|
||||||
|
### Version 3.4
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters. It is
|
||||||
|
only available with Docker Engine version **17.09.0** and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`target`](compose-file-v3.md#target) and [`network`](compose-file-v3.md#network) in
|
||||||
|
[build configurations](compose-file-v3.md#build)
|
||||||
|
- `start_period` for [`healthchecks`](compose-file-v3.md#healthcheck)
|
||||||
|
- `order` for [update configurations](compose-file-v3.md#update_config)
|
||||||
|
- `name` for [volumes](compose-file-v3.md#volume-configuration-reference)
|
||||||
|
|
||||||
|
### Version 3.5
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters. It is
|
||||||
|
only available with Docker Engine version **17.12.0** and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`isolation`](compose-file-v3.md#isolation) in service definitions
|
||||||
|
- `name` for networks, secrets and configs
|
||||||
|
- `shm_size` in [build configurations](compose-file-v3.md#build)
|
||||||
|
|
||||||
|
### Version 3.6
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters. It is
|
||||||
|
only available with Docker Engine version **18.02.0** and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`tmpfs` size](compose-file-v3.md#long-syntax-3) for `tmpfs`-type mounts
|
||||||
|
|
||||||
|
### Version 3.7
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters. It is
|
||||||
|
only available with Docker Engine version **18.06.0** and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`init`](compose-file-v3.md#init) in service definitions
|
||||||
|
- [`rollback_config`](compose-file-v3.md#rollback_config) in deploy configurations
|
||||||
|
- Support for extension fields at the root of service, network, volume, secret
|
||||||
|
and config definitions
|
||||||
|
|
||||||
|
### Version 3.8
|
||||||
|
|
||||||
|
An upgrade of [version 3](#version-3) that introduces new parameters. It is
|
||||||
|
only available with Docker Engine version **19.03.0** and higher.
|
||||||
|
|
||||||
|
Introduces the following additional parameters:
|
||||||
|
|
||||||
|
- [`max_replicas_per_node`](compose-file-v3.md#max_replicas_per_node) in placement
|
||||||
|
configurations
|
||||||
|
- `template_driver` option for [config](compose-file-v3.md#configs-configuration-reference)
|
||||||
|
and [secret](compose-file-v3.md#secrets-configuration-reference) configurations. This
|
||||||
|
option is only supported when deploying swarm services using
|
||||||
|
`docker stack deploy`.
|
||||||
|
- `driver` and `driver_opts` option for [secret](compose-file-v3.md#secrets-configuration-reference)
|
||||||
|
configurations. This option is only supported when deploying swarm services
|
||||||
|
using `docker stack deploy`.
|
||||||
|
|
||||||
|
### Version 1 (Deprecated)
|
||||||
|
|
||||||
|
Compose versions below 1.6.x are
|
||||||
|
|
||||||
|
Compose files that do not declare a version are considered "version 1". In those
|
||||||
|
files, all the [services](compose-file-v3.md#service-configuration-reference) are
|
||||||
|
declared at the root of the document.
|
||||||
|
|
||||||
|
Version 1 is supported by Compose up to 1.6.x** and has been deprecated.
|
||||||
|
|
||||||
|
Version 1 files cannot declare named
|
||||||
|
[volumes](compose-file-v3.md#volume-configuration-reference), [networks](compose-file-v3.md#network-configuration-reference) or
|
||||||
|
[build arguments](compose-file-v3.md#args).
|
||||||
|
|
||||||
|
Compose does not take advantage of [networking](https://docs.docker.com/compose/networking/) when you
|
||||||
|
use version 1: every container is placed on the default `bridge` network and is
|
||||||
|
reachable from every other container at its IP address. You need to use
|
||||||
|
`links` to enable discovery between containers.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
ports:
|
||||||
|
- "8000:5000"
|
||||||
|
volumes:
|
||||||
|
- .:/code
|
||||||
|
links:
|
||||||
|
- redis
|
||||||
|
redis:
|
||||||
|
image: redis
|
||||||
|
|
||||||
|
## Upgrading
|
||||||
|
|
||||||
|
### Version 2.x to 3.x
|
||||||
|
|
||||||
|
Between versions 2.x and 3.x, the structure of the Compose file is the same, but
|
||||||
|
several options have been removed:
|
||||||
|
|
||||||
|
- `volume_driver`: Instead of setting the volume driver on the service, define
|
||||||
|
a volume using the
|
||||||
|
[top-level `volumes` option](compose-file-v3.md#volume-configuration-reference)
|
||||||
|
and specify the driver there.
|
||||||
|
|
||||||
|
version: "3.8"
|
||||||
|
services:
|
||||||
|
db:
|
||||||
|
image: postgres
|
||||||
|
volumes:
|
||||||
|
- data:/var/lib/postgresql/data
|
||||||
|
volumes:
|
||||||
|
data:
|
||||||
|
driver: mydriver
|
||||||
|
|
||||||
|
- `volumes_from`: To share a volume between services, define it using the
|
||||||
|
[top-level `volumes` option](compose-file-v3.md#volume-configuration-reference)
|
||||||
|
and reference it from each service that shares it using the
|
||||||
|
[service-level `volumes` option](compose-file-v3.md#driver).
|
||||||
|
|
||||||
|
- `cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`: These
|
||||||
|
have been replaced by the [resources](compose-file-v3.md#resources) key under
|
||||||
|
`deploy`. `deploy` configuration only takes effect when using
|
||||||
|
`docker stack deploy`, and is ignored by `docker-compose`.
|
||||||
|
|
||||||
|
- `extends`: This option has been removed for `version: "3.x"` Compose files.
|
||||||
|
For more information on `extends`, see
|
||||||
|
[Extending services](https://docs.docker.com/compose/multiple-compose-files/extends/).
|
||||||
|
- `group_add`: This option has been removed for `version: "3.x"` Compose files.
|
||||||
|
- `pids_limit`: This option has not been introduced in `version: "3.x"` Compose files.
|
||||||
|
- `link_local_ips` in `networks`: This option has not been introduced in
|
||||||
|
`version: "3.x"` Compose files.
|
||||||
|
|
||||||
|
#### Compatibility mode
|
||||||
|
|
||||||
|
`docker-compose` 1.20.0 introduces a new `--compatibility` flag designed to
|
||||||
|
help developers transition to version 3 more easily. When enabled,
|
||||||
|
`docker-compose` reads the `deploy` section of each service's definition and
|
||||||
|
attempts to translate it into the equivalent version 2 parameter. Currently,
|
||||||
|
the following deploy keys are translated:
|
||||||
|
|
||||||
|
- [resources](compose-file-v3.md#resources) limits and memory reservations
|
||||||
|
- [replicas](compose-file-v3.md#replicas)
|
||||||
|
- [restart_policy](compose-file-v3.md#restart_policy) `condition` and `max_attempts`
|
||||||
|
|
||||||
|
All other keys are ignored and produce a warning if present. You can review
|
||||||
|
the configuration that will be used to deploy by using the `--compatibility`
|
||||||
|
flag with the `config` command.
|
||||||
|
|
||||||
|
> Do not use this in production
|
||||||
|
>
|
||||||
|
> We recommend against using `--compatibility` mode in production. The
|
||||||
|
> resulting configuration is only an approximate using non-Swarm mode
|
||||||
|
> properties, it may produce unexpected results.
|
||||||
|
|
||||||
|
### Version 1 to 2.x
|
||||||
|
|
||||||
|
In the majority of cases, moving from version 1 to 2 is a very simple process:
|
||||||
|
|
||||||
|
1. Indent the whole file by one level and put a `services:` key at the top.
|
||||||
|
2. Add a `version: '2'` line at the top of the file.
|
||||||
|
|
||||||
|
It's more complicated if you're using particular configuration features:
|
||||||
|
|
||||||
|
- `dockerfile`: This now lives under the `build` key:
|
||||||
|
|
||||||
|
build:
|
||||||
|
context: .
|
||||||
|
dockerfile: Dockerfile-alternate
|
||||||
|
|
||||||
|
- `log_driver`, `log_opt`: These now live under the `logging` key:
|
||||||
|
|
||||||
|
logging:
|
||||||
|
driver: syslog
|
||||||
|
options:
|
||||||
|
syslog-address: "tcp://192.168.0.42:123"
|
||||||
|
|
||||||
|
- `links` with environment variables: environment variables created by
|
||||||
|
links, such as `CONTAINERNAME_PORT`, ` have been deprecated for some time. In the new Docker network system,
|
||||||
|
they have been removed. You should either connect directly to the
|
||||||
|
appropriate hostname or set the relevant environment variable yourself,
|
||||||
|
using the link hostname:
|
||||||
|
|
||||||
|
web:
|
||||||
|
links:
|
||||||
|
- db
|
||||||
|
environment:
|
||||||
|
- DB_PORT=tcp://db:5432
|
||||||
|
|
||||||
|
- `external_links`: Compose uses Docker networks when running version 2
|
||||||
|
projects, so links behave slightly differently. In particular, two
|
||||||
|
containers must be connected to at least one network in common in order to
|
||||||
|
communicate, even if explicitly linked together.
|
||||||
|
|
||||||
|
Either connect the external container to your app's
|
||||||
|
[default network](https://docs.docker.com/compose/networking/), or connect both the external container and
|
||||||
|
your service's containers to an
|
||||||
|
[external network](https://docs.docker.com/compose/networking/).
|
||||||
|
|
||||||
|
- `net`: This is now replaced by [network_mode](compose-file-v3.md#network_mode):
|
||||||
|
|
||||||
|
net: host -> network_mode: host
|
||||||
|
net: bridge -> network_mode: bridge
|
||||||
|
net: none -> network_mode: none
|
||||||
|
|
||||||
|
If you're using `net: "container:[service name]"`, you must now use
|
||||||
|
`network_mode: "service:[service name]"` instead.
|
||||||
|
|
||||||
|
net: "container:web" -> network_mode: "service:web"
|
||||||
|
|
||||||
|
If you're using `net: "container:[container name/id]"`, the value does not
|
||||||
|
need to change.
|
||||||
|
|
||||||
|
net: "container:cont-name" -> network_mode: "container:cont-name"
|
||||||
|
net: "container:abc12345" -> network_mode: "container:abc12345"
|
||||||
|
|
||||||
|
- `volumes` with named volumes: these must now be explicitly declared in a
|
||||||
|
top-level `volumes` section of your Compose file. If a service mounts a
|
||||||
|
named volume called `data`, you must declare a `data` volume in your
|
||||||
|
top-level `volumes` section. The whole file might look like this:
|
||||||
|
|
||||||
|
version: "{{% param "compose_file_v2" %}}"
|
||||||
|
services:
|
||||||
|
db:
|
||||||
|
image: postgres
|
||||||
|
volumes:
|
||||||
|
- data:/var/lib/postgresql/data
|
||||||
|
volumes:
|
||||||
|
data: {}
|
||||||
|
|
||||||
|
By default, Compose creates a volume whose name is prefixed with your
|
||||||
|
project name. If you want it to just be called `data`, declare it as
|
||||||
|
external:
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
data:
|
||||||
|
external: true
|
||||||
|
|
@ -1,4 +1,6 @@
|
||||||
These topics describe version 2 of the Compose file format.
|
This page describes version 2 of the Compose file format.
|
||||||
|
|
||||||
|
This is legacy content. The latest Compose file format is defined by the [Compose Specification](https://docs.docker.com/compose/compose-file/) and is implemented by Docker Compose **1.27.0+**.
|
||||||
|
|
||||||
## Compose and Docker compatibility matrix
|
## Compose and Docker compatibility matrix
|
||||||
|
|
||||||
|
|
@ -6,7 +8,33 @@ There are several versions of the Compose file format – 1, 2, 2.x, and 3.x. Th
|
||||||
table below is a quick look. For full details on what each version includes and
|
table below is a quick look. For full details on what each version includes and
|
||||||
how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
|
how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
|
||||||
|
|
||||||
{{< include "content/compose-matrix.md" >}}
|
This table shows which Compose file versions support specific Docker releases.
|
||||||
|
|
||||||
|
| **Compose file format** | **Docker Engine release** |
|
||||||
|
| ------------------- | ------------------ |
|
||||||
|
| Compose specification | 19.03.0+ |
|
||||||
|
| 3.8 | 19.03.0+ |
|
||||||
|
| 3.7 | 18.06.0+ |
|
||||||
|
| 3.6 | 18.02.0+ |
|
||||||
|
| 3.5 | 17.12.0+ |
|
||||||
|
| 3.4 | 17.09.0+ |
|
||||||
|
| 3.3 | 17.06.0+ |
|
||||||
|
| 3.2 | 17.04.0+ |
|
||||||
|
| 3.1 | 1.13.1+ |
|
||||||
|
| 3.0 | 1.13.0+ |
|
||||||
|
| 2.4 | 17.12.0+ |
|
||||||
|
| 2.3 | 17.06.0+ |
|
||||||
|
| 2.2 | 1.13.0+ |
|
||||||
|
| 2.1 | 1.12.0+ |
|
||||||
|
| 2.0 | 1.10.0+ |
|
||||||
|
|
||||||
|
In addition to Compose file format versions shown in the table, the Compose
|
||||||
|
itself is on a release schedule, as shown in [Compose
|
||||||
|
releases](https://github.com/docker/compose/releases/), but file format versions
|
||||||
|
do not necessarily increment with each release. For example, Compose file format
|
||||||
|
3.0 was first introduced in [Compose release
|
||||||
|
1.10.0](https://github.com/docker/compose/releases/tag/1.10.0), and versioned
|
||||||
|
gradually in subsequent releases.
|
||||||
|
|
||||||
## Service configuration reference
|
## Service configuration reference
|
||||||
|
|
||||||
|
|
@ -205,7 +233,7 @@ build:
|
||||||
> In your Dockerfile, if you specify `ARG` before the `FROM` instruction,
|
> In your Dockerfile, if you specify `ARG` before the `FROM` instruction,
|
||||||
> `ARG` is not available in the build instructions under `FROM`.
|
> `ARG` is not available in the build instructions under `FROM`.
|
||||||
> If you need an argument to be available in both places, also specify it under
|
> If you need an argument to be available in both places, also specify it under
|
||||||
> the `FROM` instruction. Refer to the [understand how ARGS and FROM interact](../../reference/dockerfile.md#understand-how-arg-and-from-interact)
|
> the `FROM` instruction. Refer to the [understand how ARGS and FROM interact](https://docs.docker.com/reference/dockerfile#understand-how-arg-and-from-interact)
|
||||||
> section in the documentation for usage details.
|
> section in the documentation for usage details.
|
||||||
|
|
||||||
You can omit the value when specifying a build argument, in which case its value
|
You can omit the value when specifying a build argument, in which case its value
|
||||||
|
|
@ -261,7 +289,7 @@ An entry with the ip address and hostname is created in `/etc/hosts` inside cont
|
||||||
Specify a build’s container isolation technology. On Linux, the only supported value
|
Specify a build’s container isolation technology. On Linux, the only supported value
|
||||||
is `default`. On Windows, acceptable values are `default`, `process` and
|
is `default`. On Windows, acceptable values are `default`, `process` and
|
||||||
`hyperv`. Refer to the
|
`hyperv`. Refer to the
|
||||||
[Docker Engine docs](../../reference/cli/docker/container/run.md#isolation)
|
[Docker Engine docs](https://docs.docker.com/reference/cli/docker/container/run#isolation)
|
||||||
for details.
|
for details.
|
||||||
|
|
||||||
If unspecified, Compose will use the `isolation` value found in the service's definition
|
If unspecified, Compose will use the `isolation` value found in the service's definition
|
||||||
|
|
@ -271,7 +299,7 @@ to determine the value to use for builds.
|
||||||
|
|
||||||
> Added in [version 2.1](compose-versioning.md#version-21) file format
|
> Added in [version 2.1](compose-versioning.md#version-21) file format
|
||||||
|
|
||||||
Add metadata to the resulting image using [Docker labels](../../config/labels-custom-metadata.md).
|
Add metadata to the resulting image using [Docker labels](https://docs.docker.com/config/labels-custom-metadata).
|
||||||
You can use either an array or a dictionary.
|
You can use either an array or a dictionary.
|
||||||
|
|
||||||
It's recommended that you use reverse-DNS notation to prevent your labels from
|
It's recommended that you use reverse-DNS notation to prevent your labels from
|
||||||
|
|
@ -347,7 +375,7 @@ build:
|
||||||
> Added in [version 2.3](compose-versioning.md#version-23) file format
|
> Added in [version 2.3](compose-versioning.md#version-23) file format
|
||||||
|
|
||||||
Build the specified stage as defined inside the `Dockerfile`. See the
|
Build the specified stage as defined inside the `Dockerfile`. See the
|
||||||
[multi-stage build docs](../../build/building/multi-stage.md) for
|
[multi-stage build docs](https://docs.docker.com/build/building/multi-stage) for
|
||||||
details.
|
details.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
|
@ -387,7 +415,7 @@ command: bundle exec thin -p 3000
|
||||||
```
|
```
|
||||||
|
|
||||||
The command can also be a list, in a manner similar to
|
The command can also be a list, in a manner similar to
|
||||||
[dockerfile](../../reference/dockerfile.md#cmd):
|
[dockerfile](https://docs.docker.com/reference/dockerfile#cmd):
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
command: ["bundle", "exec", "thin", "-p", "3000"]
|
command: ["bundle", "exec", "thin", "-p", "3000"]
|
||||||
|
|
@ -480,7 +508,7 @@ services:
|
||||||
>
|
>
|
||||||
> `depends_on` does not wait for `db` and `redis` to be "ready" before
|
> `depends_on` does not wait for `db` and `redis` to be "ready" before
|
||||||
> starting `web` - only until they have been started. If you need to wait
|
> starting `web` - only until they have been started. If you need to wait
|
||||||
> for a service to be ready, see [Controlling startup order](../startup-order.md)
|
> for a service to be ready, see [Controlling startup order](https://docs.docker.com/compose/startup-order/)
|
||||||
> for more on this problem and strategies for solving it.
|
> for more on this problem and strategies for solving it.
|
||||||
|
|
||||||
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
||||||
|
|
@ -562,7 +590,7 @@ entrypoint: /code/entrypoint.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
The entrypoint can also be a list, in a manner similar to
|
The entrypoint can also be a list, in a manner similar to
|
||||||
[dockerfile](../../reference/dockerfile.md#entrypoint):
|
[dockerfile](https://docs.docker.com/reference/dockerfile#entrypoint):
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]
|
entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]
|
||||||
|
|
@ -718,7 +746,7 @@ indefinitely. Compose does not support circular references and `docker-compose`
|
||||||
returns an error if it encounters one.
|
returns an error if it encounters one.
|
||||||
|
|
||||||
For more on `extends`, see the
|
For more on `extends`, see the
|
||||||
[the extends documentation](../multiple-compose-files/extends.md)
|
[the extends documentation](https://docs.docker.com/compose/multiple-compose-files/extends)
|
||||||
|
|
||||||
### external_links
|
### external_links
|
||||||
|
|
||||||
|
|
@ -766,7 +794,7 @@ host system to be added. An example of where this is useful is when multiple
|
||||||
containers (running as different users) need to all read or write the same
|
containers (running as different users) need to all read or write the same
|
||||||
file on the host system. That file can be owned by a group shared by all the
|
file on the host system. That file can be owned by a group shared by all the
|
||||||
containers, and specified in `group_add`. See the
|
containers, and specified in `group_add`. See the
|
||||||
[Docker documentation](../../reference/cli/docker/container/run.md#additional-groups) for more
|
[Docker documentation](https://docs.docker.com/reference/cli/docker/container/run#additional-groups) for more
|
||||||
details.
|
details.
|
||||||
|
|
||||||
A full example:
|
A full example:
|
||||||
|
|
@ -790,7 +818,7 @@ used.
|
||||||
|
|
||||||
Configure a check that's run to determine whether or not containers for this
|
Configure a check that's run to determine whether or not containers for this
|
||||||
service are "healthy". See the docs for the
|
service are "healthy". See the docs for the
|
||||||
[HEALTHCHECK Dockerfile instruction](../../reference/dockerfile.md#healthcheck)
|
[HEALTHCHECK Dockerfile instruction](https://docs.docker.com/reference/dockerfile#healthcheck)
|
||||||
for details on how healthchecks work.
|
for details on how healthchecks work.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
|
@ -879,7 +907,7 @@ services:
|
||||||
> The default init binary that is used is [Tini](https://github.com/krallin/tini),
|
> The default init binary that is used is [Tini](https://github.com/krallin/tini),
|
||||||
> and is installed in `/usr/libexec/docker-init` on the daemon host. You can
|
> and is installed in `/usr/libexec/docker-init` on the daemon host. You can
|
||||||
> configure the daemon to use a custom init binary through the
|
> configure the daemon to use a custom init binary through the
|
||||||
> [`init-path` configuration option](../../reference/cli/dockerd.md#daemon-configuration-file).
|
> [`init-path` configuration option](https://docs.docker.com/reference/cli/dockerd#daemon-configuration-file).
|
||||||
|
|
||||||
### isolation
|
### isolation
|
||||||
|
|
||||||
|
|
@ -888,12 +916,12 @@ services:
|
||||||
Specify a container’s isolation technology. On Linux, the only supported value
|
Specify a container’s isolation technology. On Linux, the only supported value
|
||||||
is `default`. On Windows, acceptable values are `default`, `process` and
|
is `default`. On Windows, acceptable values are `default`, `process` and
|
||||||
`hyperv`. Refer to the
|
`hyperv`. Refer to the
|
||||||
[Docker Engine docs](../../reference/cli/docker/container/run.md#isolation)
|
[Docker Engine docs](https://docs.docker.com/reference/cli/docker/container/run#isolation)
|
||||||
for details.
|
for details.
|
||||||
|
|
||||||
### labels
|
### labels
|
||||||
|
|
||||||
Add metadata to containers using [Docker labels](../../config/labels-custom-metadata.md). You can use either an array or a dictionary.
|
Add metadata to containers using [Docker labels](https://docs.docker.com/config/labels-custom-metadata). You can use either an array or a dictionary.
|
||||||
|
|
||||||
It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.
|
It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.
|
||||||
|
|
||||||
|
|
@ -932,7 +960,7 @@ the alias, or the service name if no alias was specified.
|
||||||
|
|
||||||
Links are not required to enable services to communicate - by default,
|
Links are not required to enable services to communicate - by default,
|
||||||
any service can reach any other service at that service’s name. (See also, the
|
any service can reach any other service at that service’s name. (See also, the
|
||||||
[Links topic in Networking in Compose](../networking.md#link-containers).)
|
[Links topic in Networking in Compose](https://docs.docker.com/compose/networking#link-containers).)
|
||||||
|
|
||||||
Links also express dependency between services in the same way as
|
Links also express dependency between services in the same way as
|
||||||
[depends_on](#depends_on), so they determine the order of service startup.
|
[depends_on](#depends_on), so they determine the order of service startup.
|
||||||
|
|
@ -956,7 +984,7 @@ logging:
|
||||||
|
|
||||||
The `driver` name specifies a logging driver for the service's
|
The `driver` name specifies a logging driver for the service's
|
||||||
containers, as with the ``--log-driver`` option for docker run
|
containers, as with the ``--log-driver`` option for docker run
|
||||||
([documented here](../../config/containers/logging/configure.md)).
|
([documented here](https://docs.docker.com/config/containers/logging/configure)).
|
||||||
|
|
||||||
The default value is json-file.
|
The default value is json-file.
|
||||||
|
|
||||||
|
|
@ -1282,7 +1310,7 @@ web:
|
||||||
Specify the default number of containers to deploy for this service. Whenever
|
Specify the default number of containers to deploy for this service. Whenever
|
||||||
you run `docker-compose up`, Compose creates or removes containers to match
|
you run `docker-compose up`, Compose creates or removes containers to match
|
||||||
the specified number. This value can be overridden using the
|
the specified number. This value can be overridden using the
|
||||||
[`--scale`](../../reference/cli/docker/compose/up.md)
|
[`--scale`](https://docs.docker.com/reference/cli/docker/compose/up)
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
web:
|
web:
|
||||||
|
|
@ -1395,7 +1423,7 @@ userns_mode: "host"
|
||||||
```
|
```
|
||||||
|
|
||||||
Disables the user namespace for this service, if Docker daemon is configured with user namespaces.
|
Disables the user namespace for this service, if Docker daemon is configured with user namespaces.
|
||||||
See [dockerd](../../engine/security/userns-remap.md#disable-namespace-remapping-for-a-container) for
|
See [dockerd](https://docs.docker.com/engine/security/userns-remap#disable-namespace-remapping-for-a-container) for
|
||||||
more information.
|
more information.
|
||||||
|
|
||||||
### volumes
|
### volumes
|
||||||
|
|
@ -1483,7 +1511,7 @@ volumes:
|
||||||
> When creating bind mounts, using the long syntax requires the
|
> When creating bind mounts, using the long syntax requires the
|
||||||
> referenced folder to be created beforehand. Using the short syntax
|
> referenced folder to be created beforehand. Using the short syntax
|
||||||
> creates the folder on the fly if it doesn't exist.
|
> creates the folder on the fly if it doesn't exist.
|
||||||
> See the [bind mounts documentation](../../storage/bind-mounts.md#differences-between--v-and---mount-behavior)
|
> See the [bind mounts documentation](https://docs.docker.com/storage/bind-mounts#differences-between--v-and---mount-behavior)
|
||||||
> for more information.
|
> for more information.
|
||||||
|
|
||||||
### volume\_driver
|
### volume\_driver
|
||||||
|
|
@ -1504,7 +1532,7 @@ volume_driver: mydriver
|
||||||
> entry in the [top-level `volumes` option](#volume-configuration-reference).
|
> entry in the [top-level `volumes` option](#volume-configuration-reference).
|
||||||
|
|
||||||
|
|
||||||
See [Docker Volumes](../../storage/volumes.md) and
|
See [Docker Volumes](https://docs.docker.com/storage/volumes) and
|
||||||
[Volume Plugins](/engine/extend/plugins_volume/) for more information.
|
[Volume Plugins](/engine/extend/plugins_volume/) for more information.
|
||||||
|
|
||||||
### volumes_from
|
### volumes_from
|
||||||
|
|
@ -1545,7 +1573,7 @@ restart: "unless-stopped"
|
||||||
### cpu_count, cpu_percent, cpu\_shares, cpu\_period, cpu\_quota, cpus, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, mem\_reservation, oom_kill_disable, oom_score_adj, privileged, read\_only, shm\_size, stdin\_open, tty, user, working\_dir
|
### cpu_count, cpu_percent, cpu\_shares, cpu\_period, cpu\_quota, cpus, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, mem\_reservation, oom_kill_disable, oom_score_adj, privileged, read\_only, shm\_size, stdin\_open, tty, user, working\_dir
|
||||||
|
|
||||||
Each of these is a single value, analogous to its
|
Each of these is a single value, analogous to its
|
||||||
[docker run](../../reference/cli/docker/container/run.md#runtime-constraints-on-resources) counterpart.
|
[docker run](https://docs.docker.com/reference/cli/docker/container/run#runtime-constraints-on-resources) counterpart.
|
||||||
|
|
||||||
> Added in [version 2.2](compose-versioning.md#version-22) file format.
|
> Added in [version 2.2](compose-versioning.md#version-22) file format.
|
||||||
>
|
>
|
||||||
|
|
@ -1623,10 +1651,10 @@ While it is possible to declare [volumes](#volumes) on the fly as part of the
|
||||||
service declaration, this section allows you to create named volumes that can be
|
service declaration, this section allows you to create named volumes that can be
|
||||||
reused across multiple services (without relying on `volumes_from`), and are
|
reused across multiple services (without relying on `volumes_from`), and are
|
||||||
easily retrieved and inspected using the docker command line or API.
|
easily retrieved and inspected using the docker command line or API.
|
||||||
See the [docker volume](../../reference/cli/docker/volume/create.md)
|
See the [docker volume](https://docs.docker.com/reference/cli/docker/volume/create)
|
||||||
subcommand documentation for more information.
|
subcommand documentation for more information.
|
||||||
|
|
||||||
See [use volumes](../../storage/volumes.md) and [volume plugins](/engine/extend/plugins_volume/)
|
See [use volumes](https://docs.docker.com/storage/volumes) and [volume plugins](/engine/extend/plugins_volume/)
|
||||||
for general information on volumes.
|
for general information on volumes.
|
||||||
|
|
||||||
Here's an example of a two-service setup where a database's data directory is
|
Here's an example of a two-service setup where a database's data directory is
|
||||||
|
|
@ -1729,7 +1757,7 @@ volumes:
|
||||||
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
||||||
|
|
||||||
Add metadata to containers using
|
Add metadata to containers using
|
||||||
[Docker labels](../../config/labels-custom-metadata.md). You can use either
|
[Docker labels](https://docs.docker.com/config/labels-custom-metadata). You can use either
|
||||||
an array or a dictionary.
|
an array or a dictionary.
|
||||||
|
|
||||||
It's recommended that you use reverse-DNS notation to prevent your labels from
|
It's recommended that you use reverse-DNS notation to prevent your labels from
|
||||||
|
|
@ -1778,7 +1806,7 @@ volumes:
|
||||||
|
|
||||||
The top-level `networks` key lets you specify networks to be created. For a full
|
The top-level `networks` key lets you specify networks to be created. For a full
|
||||||
explanation of Compose's use of Docker networking features, see the
|
explanation of Compose's use of Docker networking features, see the
|
||||||
[Networking guide](../networking.md).
|
[Networking guide](https://docs.docker.com/compose/networking).
|
||||||
|
|
||||||
### driver
|
### driver
|
||||||
|
|
||||||
|
|
@ -1862,7 +1890,7 @@ you can set this option to `true`.
|
||||||
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
||||||
|
|
||||||
Add metadata to containers using
|
Add metadata to containers using
|
||||||
[Docker labels](../../config/labels-custom-metadata.md). You can use either
|
[Docker labels](https://docs.docker.com/config/labels-custom-metadata). You can use either
|
||||||
an array or a dictionary.
|
an array or a dictionary.
|
||||||
|
|
||||||
It's recommended that you use reverse-DNS notation to prevent your labels from
|
It's recommended that you use reverse-DNS notation to prevent your labels from
|
||||||
|
|
@ -1958,10 +1986,151 @@ networks:
|
||||||
|
|
||||||
## Variable substitution
|
## Variable substitution
|
||||||
|
|
||||||
{{< include "content/compose-var-sub.md" >}}
|
Your configuration options can contain environment variables. Compose uses the
|
||||||
|
variable values from the shell environment in which `docker compose` is run. For
|
||||||
|
example, suppose the shell contains `POSTGRES_VERSION=9.3` and you supply this
|
||||||
|
configuration:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
db:
|
||||||
|
image: "postgres:${POSTGRES_VERSION}"
|
||||||
|
```
|
||||||
|
|
||||||
|
When you run `docker compose up` with this configuration, Compose looks for the
|
||||||
|
`POSTGRES_VERSION` environment variable in the shell and substitutes its value
|
||||||
|
in. For this example, Compose resolves the `image` to `postgres:9.3` before
|
||||||
|
running the configuration.
|
||||||
|
|
||||||
|
If an environment variable is not set, Compose substitutes with an empty
|
||||||
|
string. In the example above, if `POSTGRES_VERSION` is not set, the value for
|
||||||
|
the `image` option is `postgres:`.
|
||||||
|
|
||||||
|
You can set default values for environment variables using a
|
||||||
|
`.env` file, which Compose automatically looks for in
|
||||||
|
project directory (parent folder of your Compose file).
|
||||||
|
Values set in the shell environment override those set in the `.env` file.
|
||||||
|
|
||||||
|
> Note when using docker stack deploy
|
||||||
|
>
|
||||||
|
> The `.env file` feature only works when you use the `docker compose up` command
|
||||||
|
> and does not work with `docker stack deploy`.
|
||||||
|
{ .important }
|
||||||
|
|
||||||
|
Both `$VARIABLE` and `${VARIABLE}` syntax are supported. Additionally when using
|
||||||
|
the [2.1 file format](compose-versioning.md#version-21), it is possible to
|
||||||
|
provide inline default values using typical shell syntax:
|
||||||
|
|
||||||
|
- `${VARIABLE:-default}` evaluates to `default` if `VARIABLE` is unset or
|
||||||
|
empty in the environment.
|
||||||
|
- `${VARIABLE-default}` evaluates to `default` only if `VARIABLE` is unset
|
||||||
|
in the environment.
|
||||||
|
|
||||||
|
Similarly, the following syntax allows you to specify mandatory variables:
|
||||||
|
|
||||||
|
- `${VARIABLE:?err}` exits with an error message containing `err` if
|
||||||
|
`VARIABLE` is unset or empty in the environment.
|
||||||
|
- `${VARIABLE?err}` exits with an error message containing `err` if
|
||||||
|
`VARIABLE` is unset in the environment.
|
||||||
|
|
||||||
|
Other extended shell-style features, such as `${VARIABLE/foo/bar}`, are not
|
||||||
|
supported.
|
||||||
|
|
||||||
|
You can use a `$$` (double-dollar sign) when your configuration needs a literal
|
||||||
|
dollar sign. This also prevents Compose from interpolating a value, so a `$$`
|
||||||
|
allows you to refer to environment variables that you don't want processed by
|
||||||
|
Compose.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
|
||||||
|
```
|
||||||
|
|
||||||
|
If you forget and use a single dollar sign (`$`), Compose interprets the value
|
||||||
|
as an environment variable and warns you:
|
||||||
|
|
||||||
|
```console
|
||||||
|
The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.
|
||||||
|
```
|
||||||
|
|
||||||
## Extension fields
|
## Extension fields
|
||||||
|
|
||||||
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
> Added in [version 2.1](compose-versioning.md#version-21) file format.
|
||||||
|
|
||||||
{{< include "content/compose-extfields-sub.md" >}}
|
It is possible to re-use configuration fragments using extension fields. Those
|
||||||
|
special fields can be of any format as long as they are located at the root of
|
||||||
|
your Compose file and their name start with the `x-` character sequence.
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
>
|
||||||
|
> Starting with the 3.7 format (for the 3.x series) and 2.4 format
|
||||||
|
> (for the 2.x series), extension fields are also allowed at the root
|
||||||
|
> of service, volume, network, config and secret definitions.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: "{{% param "compose_file_v3" %}}"
|
||||||
|
x-custom:
|
||||||
|
items:
|
||||||
|
- a
|
||||||
|
- b
|
||||||
|
options:
|
||||||
|
max-size: '12m'
|
||||||
|
name: "custom"
|
||||||
|
```
|
||||||
|
|
||||||
|
The contents of those fields are ignored by Compose, but they can be
|
||||||
|
inserted in your resource definitions using [YAML anchors](https://yaml.org/spec/1.2/spec.html#id2765878).
|
||||||
|
For example, if you want several of your services to use the same logging
|
||||||
|
configuration:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
logging:
|
||||||
|
options:
|
||||||
|
max-size: '12m'
|
||||||
|
max-file: '5'
|
||||||
|
driver: json-file
|
||||||
|
```
|
||||||
|
|
||||||
|
You may write your Compose file as follows:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: "{{% param "compose_file_v3" %}}"
|
||||||
|
x-logging:
|
||||||
|
&default-logging
|
||||||
|
options:
|
||||||
|
max-size: '12m'
|
||||||
|
max-file: '5'
|
||||||
|
driver: json-file
|
||||||
|
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
image: myapp/web:latest
|
||||||
|
logging: *default-logging
|
||||||
|
db:
|
||||||
|
image: mysql:latest
|
||||||
|
logging: *default-logging
|
||||||
|
```
|
||||||
|
|
||||||
|
It is also possible to partially override values in extension fields using
|
||||||
|
the [YAML merge type](https://yaml.org/type/merge.html). For example:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: "{{% param "compose_file_v3" %}}"
|
||||||
|
x-volumes:
|
||||||
|
&default-volume
|
||||||
|
driver: foobar-storage
|
||||||
|
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
image: myapp/web:latest
|
||||||
|
volumes: ["vol1", "vol2", "vol3"]
|
||||||
|
volumes:
|
||||||
|
vol1: *default-volume
|
||||||
|
vol2:
|
||||||
|
<< : *default-volume
|
||||||
|
name: volume02
|
||||||
|
vol3:
|
||||||
|
<< : *default-volume
|
||||||
|
driver: default
|
||||||
|
name: volume-local
|
||||||
|
```
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,14 +0,0 @@
|
||||||
# The docs have been moved!
|
|
||||||
|
|
||||||
The documentation for Compose has been merged into
|
|
||||||
[the general documentation repo](https://github.com/docker/docker.github.io).
|
|
||||||
|
|
||||||
The docs for Compose are now here:
|
|
||||||
https://github.com/docker/docker.github.io/tree/master/compose
|
|
||||||
|
|
||||||
Please submit pull requests for unreleased features/changes on the `master` branch (https://github.com/docker/docker.github.io/tree/master), please prefix the PR title with `[WIP]` to indicate that it relates to an unreleased change.
|
|
||||||
|
|
||||||
If you submit a PR to this codebase that has a docs impact, create a second docs PR on `docker.github.io`. Use the docs PR template provided.
|
|
||||||
|
|
||||||
As always, the docs remain open-source and we appreciate your feedback and
|
|
||||||
pull requests!
|
|
||||||
Loading…
Reference in New Issue