mirror of https://github.com/docker/docs.git
ENGDOCS-2079 (#19939)
* ENGDOCS-2079 * Fix links * Fix links * Fix links * Fix links
This commit is contained in:
Allie Sadler
GitHub
parent
feaf1d0198
commit
8f1150e24b
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -1,535 +0,0 @@
|
|||
---
|
||||
description: Compose file reference
|
||||
keywords: fig, composition, compose, versions, upgrading, docker
|
||||
title: Compose file versions and upgrading
|
||||
---
|
||||
|
||||
>**Warning**
|
||||
>
|
||||
>This page contains information on the legacy versions of Compose, also collectively referred to as Compose V1.
|
||||
>From the end of June 2023 Compose V1 won’t be supported anymore.
|
||||
>
|
||||
>The latest and recommended version of Compose is the [Compose Specification](index.md).
|
||||
>Make sure you switch to [Compose V2](/compose/compose-file/) with the `docker compose` CLI plugin or by activating the **Use Docker Compose V2** setting in Docker Desktop.
|
||||
>
|
||||
> For more information, see the [History of Compose](/compose/history/).
|
||||
{ .warning }
|
||||
|
||||
The Compose file is a [YAML](https://yaml.org) file defining services,
|
||||
networks, and volumes for a Docker application.
|
||||
|
||||
The Compose file formats are now described in these references, specific to each version.
|
||||
|
||||
| **Reference file** | **What changed in this version** |
|
||||
|:------------------------------------------------------|:---------------------------------|
|
||||
| [Version 3](compose-file-v3.md) | [Version 3 updates](#version-3) |
|
||||
| [Version 2](compose-file-v2.md) | [Version 2 updates](#version-2) |
|
||||
| Version 1 (Deprecated) | [Version 1 updates](#version-1-deprecated) |
|
||||
|
||||
The topics below explain the differences among the versions, Docker Engine
|
||||
compatibility, and [how to upgrade](#upgrading).
|
||||
|
||||
## Compatibility matrix
|
||||
|
||||
{{< include "content/compose-matrix.md" >}}
|
||||
|
||||
<!-- markdownlint-disable reference-links-images -->
|
||||
|
||||
> Looking for more detail on Docker and Compose compatibility?
|
||||
>
|
||||
> We recommend keeping up-to-date with newer releases as much as possible.
|
||||
However, if you are using an older version of Docker and want to determine which
|
||||
Compose release is compatible, refer to the [Compose release
|
||||
notes](https://github.com/docker/compose/releases/). Each set of release notes
|
||||
gives details on which versions of Docker Engine are supported, along
|
||||
with compatible Compose file format versions. (See also, the discussion in
|
||||
[issue #3404]({{% param "repo" %}}/issues/3404).)
|
||||
|
||||
<!-- markdownlint-enable reference-links-images -->
|
||||
|
||||
For details on versions and how to upgrade, see
|
||||
[Versioning](compose-versioning.md#versioning) and
|
||||
[Upgrading](compose-versioning.md#upgrading).
|
||||
|
||||
## Versioning
|
||||
|
||||
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](../../engine/swarm/index.md). 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://github.com/compose-spec/compose-spec/blob/master/spec.md). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**.
|
||||
|
||||
The [Compatibility Matrix](#compatibility-matrix) shows Compose file versions mapped to Docker Engine releases.
|
||||
|
||||
To move your project to a later version, see the [Upgrading](#upgrading)
|
||||
section.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> If you're using [multiple Compose files](../multiple-compose-files/_index.md) or
|
||||
> [extending services](../multiple-compose-files/extends.md),
|
||||
> 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](../networking.md).
|
||||
|
||||
> **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](../networking.md) 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](../multiple-compose-files/extends.md).
|
||||
- `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](../networking.md), or connect both the external container and
|
||||
your service's containers to an
|
||||
[external network](../networking.md#use-a-pre-existing-network).
|
||||
|
||||
- `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
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
title: Legacy versions
|
||||
description:
|
||||
keywords: fig, composition, compose, versions, upgrading, docker, version 3, docker compose 3
|
||||
aliases:
|
||||
- /compose/compose-file/compose-versioning/
|
||||
- /compose/compose-file/compose-file-v3/
|
||||
- /compose/compose-file/compose-file-v2/
|
||||
---
|
||||
|
||||
The legacy versions of the Compose file reference has moved to the [V1 branch of the Compose repository](https://github.com/docker/compose/tree/v1/docs). They are no longer being actively maintained.
|
||||
|
||||
The latest and recommended version of the Compose file format is defined by the [Compose Specification](_index.md). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**. For more information, see the[History and development of Docker Compose](../intro/history.md).
|
||||
|
|
@ -34,9 +34,9 @@ Compose V2 ignores the `version` top-level element in the `compose.yml` file.
|
|||
The Docker Compose CLIs are defined by specific file formats.
|
||||
|
||||
Three major versions of the Compose file format for Compose V1 were released:
|
||||
- [Compose file format 1](../compose-file/compose-versioning.md##version-1-to-2x) with Compose 1.0.0 in 2014
|
||||
- [Compose file format 2.x](../compose-file/compose-file-v2.md) with Compose 1.6.0 in 2016
|
||||
- [Compose file format 3.x](../compose-file/compose-file-v3.md) with Compose 1.10.0 in 2017
|
||||
- Compose file format 1 with Compose 1.0.0 in 2014
|
||||
- Compose file format 2.x with Compose 1.6.0 in 2016
|
||||
- Compose file format 3.x with Compose 1.10.0 in 2017
|
||||
|
||||
Compose file format 1 is substantially different to all the following formats as it lacks a top-level `services` key.
|
||||
Its usage is historical and files written in this format don't run with Compose V2.
|
||||
|
|
|
|||
|
|
@ -2209,7 +2209,7 @@ naming scheme accordingly before upgrading.
|
|||
|
||||
- Added support for `extra_hosts` in build configuration
|
||||
|
||||
- Added support for the [long syntax](compose-file/compose-file-v3.md#long-syntax-3) for volume entries, as previously introduced in the 3.2 format.
|
||||
- Added support for the [long syntax](compose-file/legacy-versions.md) for volume entries, as previously introduced in the 3.2 format.
|
||||
Using this syntax will create [mounts](../storage/bind-mounts.md) instead of volumes.
|
||||
|
||||
#### Compose file version 2.1 and up
|
||||
|
|
@ -3145,7 +3145,7 @@ naming scheme accordingly before upgrading.
|
|||
You don't have to use it - your existing Compose files will run on Compose
|
||||
1.6 exactly as they do today.
|
||||
|
||||
Check the [upgrade guide](../compose/compose-file/compose-versioning.md#upgrading)
|
||||
Check the [upgrade guide](../compose/compose-file/legacy-versions.md)
|
||||
for full details.
|
||||
|
||||
- Support for networking has exited experimental status and is the recommended
|
||||
|
|
|
|||
|
|
@ -133,7 +133,7 @@ Docker configs.
|
|||
|
||||
The `docker stack` command supports defining configs in a Compose file.
|
||||
However, the `configs` key is not supported for `docker compose`. See
|
||||
[the Compose file reference](../../compose/compose-file/compose-file-v3.md#configs) for details.
|
||||
[the Compose file reference](../../compose/compose-file/legacy-versions.md) for details.
|
||||
|
||||
### Simple example: Get started with configs
|
||||
|
||||
|
|
|
|||
|
|
@ -143,7 +143,7 @@ a similar way, see
|
|||
|
||||
Both the `docker-compose` and `docker stack` commands support defining secrets
|
||||
in a compose file. See
|
||||
[the Compose file reference](../../compose/compose-file/compose-file-v3.md#secrets) for details.
|
||||
[the Compose file reference](../../compose/compose-file/legacy-versions.md) for details.
|
||||
|
||||
### Simple example: Get started with secrets
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ title: Deploy a stack to a swarm
|
|||
|
||||
When running Docker Engine in swarm mode, you can use `docker stack deploy` to
|
||||
deploy a complete application stack to the swarm. The `deploy` command accepts
|
||||
a stack description in the form of a [Compose file](../../compose/compose-file/compose-file-v3.md).
|
||||
a stack description in the form of a [Compose file](../../compose/compose-file/legacy-versions.md).
|
||||
|
||||
{{< include "swarm-compose-compat.md" >}}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,77 +0,0 @@
|
|||
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
|
||||
```
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
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.
|
||||
|
||||
The latest Compose file format is defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md) and is implemented by Docker Compose **1.27.0+**.
|
||||
|
|
@ -1,66 +0,0 @@
|
|||
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](/compose/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/compose-file/compose-versioning/#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.
|
||||
```
|
||||
|
|
@ -593,12 +593,12 @@ You aren't going to cover any of these advanced use cases here.
|
|||
|
||||
### Variable substitution in Docker Compose
|
||||
|
||||
One of the really cool features of Docker Compose is [variable substitution](../../compose/compose-file/compose-file-v3.md#variable-substitution). You can see some examples in the Compose file, `environment` section. By means of an example:
|
||||
One of the really cool features of Docker Compose is [variable substitution](../../compose/compose-file/12-interpolation.md). You can see some examples in the Compose file, `environment` section. By means of an example:
|
||||
|
||||
* `PGUSER=${PGUSER:-totoro}` means that inside the container, the environment variable `PGUSER` shall be set to the same value as it has on the host machine where Docker Compose is run. If there is no environment variable with this name on the host machine, the variable inside the container gets the default value of `totoro`.
|
||||
* `PGPASSWORD=${PGPASSWORD:?database password not set}` means that if the environment variable `PGPASSWORD` isn't set on the host, Docker Compose will display an error. This is OK, because you don't want to hard-code default values for the password. You set the password value in the `.env` file, which is local to your machine. It is always a good idea to add `.env` to `.gitignore` to prevent the secrets being checked into the version control.
|
||||
|
||||
Other ways of dealing with undefined or empty values exist, as documented in the [variable substitution](../../compose/compose-file/compose-file-v3.md#variable-substitution) section of the Docker documentation.
|
||||
Other ways of dealing with undefined or empty values exist, as documented in the [variable substitution](../../compose/compose-file/12-interpolation.md) section of the Docker documentation.
|
||||
|
||||
### Validating Docker Compose configuration
|
||||
|
||||
|
|
@ -722,7 +722,7 @@ Such distributed set-up offers interesting possibilities, such as applying Chaos
|
|||
If you are interested in experimenting with CockroachDB clusters, check out:
|
||||
|
||||
* [Start a CockroachDB Cluster in Docker](https://www.cockroachlabs.com/docs/v20.2/start-a-local-cluster-in-docker-mac.html) article; and
|
||||
* Documentation for Docker Compose keywords [`deploy`](../../compose/compose-file/compose-file-v3.md#deploy) and [`replicas`](../../compose/compose-file/compose-file-v3.md#replicas).
|
||||
* Documentation for Docker Compose keywords [`deploy`](../../compose/compose-file/legacy-versions.md) and [`replicas`](../../compose/compose-file/legacy-versions.md).
|
||||
|
||||
### Other databases
|
||||
|
||||
|
|
|
|||
|
|
@ -418,9 +418,9 @@ volumes:
|
|||
```
|
||||
|
||||
For more information about using volumes of the `bind` type with Compose, see
|
||||
[Compose reference on volumes](../compose/compose-file/compose-file-v3.md#volumes).
|
||||
[Compose reference on volumes](../compose/compose-file/05-services.md#volumes).
|
||||
and
|
||||
[Compose reference on volume configuration](../compose/compose-file/compose-file-v3.md#volume-configuration-reference).
|
||||
[Compose reference on volume configuration](../compose/compose-file/05-services.md#volumes).
|
||||
|
||||
## Next steps
|
||||
|
||||
|
|
|
|||
|
|
@ -1008,14 +1008,8 @@ Reference:
|
|||
title: Compose Deploy Specification
|
||||
- path: /compose/compose-file/develop/
|
||||
title: Compose Develop Specification
|
||||
- sectiontitle: Legacy versions
|
||||
section:
|
||||
- path: /compose/compose-file/compose-versioning/
|
||||
title: About versions and upgrading
|
||||
- path: /compose/compose-file/compose-file-v3/
|
||||
title: Version 3
|
||||
- path: /compose/compose-file/compose-file-v2/
|
||||
title: Version 2
|
||||
- path: /compose/compose-file/legacy-versions/
|
||||
title: Legacy versions
|
||||
- path: /glossary/
|
||||
title: Glossary
|
||||
- sectiontitle: Samples
|
||||
|
|
|
|||
Loading…
Reference in New Issue