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

Change links and add versioning information 

Signed-off-by: aevesdocker <allie.sadler@docker.com>
This commit is contained in:
aevesdocker 2024-05-01 12:07:06 +01:00 committed by Nicolas De loof
parent fe42107f41
commit 0d4edbbd19
5 changed files with 3585 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

474
docs/Compose file reference (legacy)/compose-versioning.md Normal file
View File

@ -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

227
docs/Compose file reference/version-2.md → docs/Compose file reference (legacy)/version-2.md
View File

@ -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
@ -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
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
@ -205,7 +233,7 @@ build:
> In your Dockerfile, if you specify `ARG` before the `FROM` instruction,
> `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
> 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.
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
is `default`. On Windows, acceptable values are `default`, `process` and
`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.
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
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.
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
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.
```yaml
@ -387,7 +415,7 @@ command: bundle exec thin -p 3000
```
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
command: ["bundle", "exec", "thin", "-p", "3000"]
@ -480,7 +508,7 @@ services:
>
> `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
> 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.
> 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
[dockerfile](../../reference/dockerfile.md#entrypoint):
[dockerfile](https://docs.docker.com/reference/dockerfile#entrypoint):
```yaml
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.
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
@ -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
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
[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.
A full example:
@ -790,7 +818,7 @@ used.
Configure a check that's run to determine whether or not containers for this
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.
```yaml
@ -879,7 +907,7 @@ services:
> 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
> 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
@ -888,12 +916,12 @@ services:
Specify a container’s isolation technology. On Linux, the only supported value
is `default`. On Windows, acceptable values are `default`, `process` and
`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.
### 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.
@ -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,
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
[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
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.
@ -1282,7 +1310,7 @@ web:
Specify the default number of containers to deploy for this service. Whenever
you run `docker-compose up`, Compose creates or removes containers to match
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
web:
@ -1395,7 +1423,7 @@ userns_mode: "host"
```
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.
### volumes
@ -1483,7 +1511,7 @@ volumes:
> When creating bind mounts, using the long syntax requires the
> referenced folder to be created beforehand. Using the short syntax
> 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.
### volume\_driver
@ -1504,7 +1532,7 @@ volume_driver: mydriver
> 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.
### 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
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.
>
@ -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
reused across multiple services (without relying on `volumes_from`), and are
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.
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.
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.
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.
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
explanation of Compose's use of Docker networking features, see the
[Networking guide](../networking.md).
[Networking guide](https://docs.docker.com/compose/networking).
### driver
@ -1862,7 +1890,7 @@ you can set this option to `true`.
> Added in [version 2.1](compose-versioning.md#version-21) file format.
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.
It's recommended that you use reverse-DNS notation to prevent your labels from
@ -1958,10 +1986,151 @@ networks:
## 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
> 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
```

2913
docs/Compose file reference (legacy)/version-3.md Normal file
View File

File diff suppressed because it is too large Load Diff

0
docs/Compose file reference/version-3.md
View File

14
docs/README.md
View File

@ -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!