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

compose-file: reformat and rewrite some tips/notes 

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2020-03-17 11:34:58 +01:00
parent dc2ae46f92
commit 4cf38f289f
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
3 changed files with 338 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
_includes/content/compose-var-sub.md
View File

@ -21,8 +21,10 @@ You can set default values for environment variables using a
[`.env` file](../env-file.md), which Compose automatically looks for. Values
set in the shell environment override those set in the `.env` file.
> **Important**: The `.env file` feature only works when you use the
> `docker-compose up` command and does not work with `docker stack deploy`.
> 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

196
compose/compose-file/compose-file-v2.md
View File

@ -145,8 +145,7 @@ This results in an image named `webapp` and tagged `tag`, built from `./dir`.
#### context
> [Version 2 file format](compose-versioning.md#version-2) and up. In version 1, just use
> [build](#build).
> Added in [version 2.0](compose-versioning.md#version-2) file format.
Either a path to a directory containing a Dockerfile, or a url to a git repository.
@ -177,7 +176,7 @@ build:
#### args
> [Version 2 file format](compose-versioning.md#version-2) and up.
> Added in [version 2.0](compose-versioning.md#version-2) file format.
Add build arguments, which are environment variables accessible only during the
build process.
@ -211,10 +210,13 @@ build:
- gitcommithash=cdc3b19
```
> **Note**: In your Dockerfile, if you specify `ARG` before the `FROM` instruction,
> Scope of build-args
>
> 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.
> See [Understand how ARGS and FROM interact](/engine/reference/builder/#understand-how-arg-and-from-interact) for usage details.
> 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](/engine/reference/builder/#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
at build time is the value in the environment where Compose is running.
@ -225,8 +227,11 @@ args:
- gitcommithash
```
> **Note**: YAML boolean values (`true`, `false`, `yes`, `no`, `on`, `off`) must
> be enclosed in quotes, so that the parser interprets them as strings.
> Tip when using boolean values
>
> YAML boolean values (`"true"`, `"false"`, `"yes"`, `"no"`, `"on"`,
> `"off"`) must be enclosed in quotes, so that the parser interprets them as
> strings.
#### cache_from
@ -261,7 +266,7 @@ An entry with the ip address and hostname is created in `/etc/hosts` inside cont
#### isolation
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Specify a build’s container isolation technology. On Linux, the only supported value
is `default`. On Windows, acceptable values are `default`, `process` and
@ -422,7 +427,7 @@ cpu_rt_period: 11000
### device_cgroup_rules
> [Added in version 2.3 file format](compose-versioning.md#version-23).
> Added in [version 2.3](compose-versioning.md#version-23) file format.
Add rules to the cgroup allowed devices list.
@ -444,7 +449,7 @@ devices:
### depends_on
> [Version 2 file format](compose-versioning.md#version-2) and up.
> Added in [version 2.0](compose-versioning.md#version-2) file format.
Express dependency between services. Service dependencies cause the following
behaviors:
@ -473,12 +478,14 @@ services:
image: postgres
```
> **Note**: `depends_on` does not wait for `db` and `redis` to be "ready" before
> **Note**
>
> `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](/compose/startup-order.md)
> for more on this problem and strategies for solving it.
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
A healthcheck indicates that you want a dependency to wait
for another container to be "healthy" (as indicated by a successful state from
@ -569,10 +576,12 @@ entrypoint:
- vendor/bin/phpunit
```
> **Note**: Setting `entrypoint` both overrides any default entrypoint set
> on the service's image with the `ENTRYPOINT` Dockerfile instruction, *and*
> clears out any default command on the image - meaning that if there's a `CMD`
> instruction in the Dockerfile, it is ignored.
> **Note**
>
> Setting `entrypoint` both overrides any default entrypoint set on the service's
> image with the `ENTRYPOINT` Dockerfile instruction, *and* clears out any default
> command on the image - meaning that if there's a `CMD` instruction in the
> Dockerfile, it is ignored.
### env_file
@ -605,10 +614,12 @@ also ignored.
RACK_ENV=development
```
> **Note**: If your service specifies a [build](#build) option, variables
> defined in environment files are _not_ automatically visible during the
> build. Use the [args](#args) sub-option of `build` to define build-time
> environment variables.
> **Note**
>
> If your service specifies a [build](#build) option, variables defined in
> environment files are _not_ automatically visible during the build. Use
> the [args](#args) sub-option of `build` to define build-time environment
> variables.
The value of `VAL` is used as is and not modified at all. For example if the
value is surrounded by quotes (as is often the case of shell variables), the
@ -668,10 +679,12 @@ environment:
- SESSION_SECRET
```
> **Note**: If your service specifies a [build](#build) option, variables
> defined in `environment` are _not_ automatically visible during the
> build. Use the [args](#args) sub-option of `build` to define build-time
> environment variables.
> **Note**
>
> If your service specifies a [build](#build) option, variables defined in
> `environment` are _not_ automatically visible during the build. Use the
> [args](#args) sub-option of `build` to define build-time environment
> variables.
### expose
@ -729,15 +742,12 @@ external_links:
- project_db_1:postgresql
```
> **Notes:**
> **Note**
>
> If you're using the [version 2 or above file format](compose-versioning.md#version-2),
> the externally-created containers must be connected to at least one of the same
> networks as the service that is linking to them. [Links](compose-file-v2#links)
> are a legacy option. We recommend using [networks](#networks) instead.
>
> This option is ignored when [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
### extra_hosts
@ -784,7 +794,7 @@ used.
### healthcheck
> [Version 2.1 file format](compose-versioning.md#version-21) and up.
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Configure a check that's run to determine whether or not containers for this
service are "healthy". See the docs for the
@ -803,8 +813,9 @@ healthcheck:
`interval`, `timeout` and `start_period` are specified as
[durations](#specifying-durations).
> **Note**: `start_period` is only supported for [version 2.3 file format](compose-versioning.md#version-23)
> and higher.
> Added in [version 2.3](compose-versioning.md#version-23) file format.
>
> The `start_period` option was added in file format 2.3.
`test` must be either a string or a list. If it's a list, the first item must be
either `NONE`, `CMD` or `CMD-SHELL`. If it's a string, it's equivalent to
@ -860,7 +871,7 @@ options and tags it with the specified tag.
### init
> [Added in version 2.2 file format](compose-versioning.md#version-22).
> Added in [version 2.2](compose-versioning.md#version-22) file format.
Run an init inside the container that forwards signals and reaps processes.
Set this option to `true` to enable this feature for the service.
@ -880,7 +891,7 @@ services:
### isolation
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Specify a container’s isolation technology. On Linux, the only supported value
is `default`. On Windows, acceptable values are `default`, `process` and
@ -967,9 +978,11 @@ driver: "syslog"
driver: "none"
```
> **Note**: Only the `json-file` and `journald` drivers make the logs available
> directly from `docker-compose up` and `docker-compose logs`. Using any other
> driver does not print any logs.
> **Note**
>
> Only the `json-file` and `journald` drivers make the logs available directly
> from `docker-compose up` and `docker-compose logs`. Using any other driver
> does not print any logs.
Specify logging options for the logging driver with the ``options`` key, as with the ``--log-opt`` option for `docker run`.
@ -983,7 +996,9 @@ options:
### network_mode
> [Version 2 file format](compose-versioning.md#version-2) and up. Replaces the version 1 [net](compose-file-v1.md#net) option.
> Changed in [version 2](compose-versioning.md#version-2) file format.
>
> The `network_mode` option replaces the version 1 [net](compose-file-v1.md#net) option.
Network mode. Use the same values as the docker client `--network` parameter, plus
the special form `service:[service name]`.
@ -1006,7 +1021,9 @@ net: "container:[container name/id]"
### networks
> [Version 2 file format](compose-versioning.md#version-2) and up. Replaces the version 1 [net](compose-file-v1.md#net) option.
> Changed in [version 2](compose-versioning.md#version-2) file format.
>
> The `networks` option replaces the version 1 [net](compose-file-v1.md#net) option.
Networks to join, referencing entries under the
[top-level `networks` key](#network-configuration-reference).
@ -1025,7 +1042,11 @@ Aliases (alternative hostnames) for this service on the network. Other container
Since `aliases` is network-scoped, the same service can have different aliases on different networks.
> **Note**: A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name resolves to is not guaranteed.
> **Note**
>
> A network-wide alias can be shared by multiple containers, and even by multiple
> services. If it is, then exactly which container the name resolves to is not
> guaranteed.
The general format is shown here.
@ -1115,7 +1136,7 @@ networks:
#### link_local_ips
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Specify a list of link-local IPs. Link-local IPs are special IPs which belong
to a well known subnet and are purely managed by the operator, usually
@ -1168,8 +1189,9 @@ networks:
app_net_3:
```
> **Note**: If multiple networks have the same priority, the connection order
> is undefined.
> **Note**
>
> If multiple networks have the same priority, the connection order is undefined.
### pid
@ -1192,12 +1214,13 @@ on sharing between container and the host operating system the PID address
space. Containers launched with this flag can access and manipulate
other containers in the bare-metal machine's namespace and vice versa.
> **Note**: the `service:` and `container:` forms require
> [version 2.1](compose-versioning.md#version-21) or above
> Added in [version 2.1](compose-versioning.md#version-21) file format.
>
> The `service:` and `container:` forms require [version 2.1](compose-versioning.md#version-21) or above
### pids_limit
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Tunes a container's PIDs limit. Set to `-1` for unlimited PIDs.
@ -1207,7 +1230,7 @@ pids_limit: 10
### platform
> [Added in version 2.4 file format](compose-versioning.md#version-24).
> Added in [version 2.4](compose-versioning.md#version-24) file format.
Target platform containers for this service will run on, using the
`os[/arch[/variant]]` syntax, e.g.
@ -1230,7 +1253,9 @@ on which platform the service's build will be performed.
Expose ports. Either specify both ports (`HOST:CONTAINER`), or just the container
port (an ephemeral host port is chosen).
> **Note**: When mapping ports in the `HOST:CONTAINER` format, you may experience
> **Note**
>
> When mapping ports in the `HOST:CONTAINER` format, you may experience
> erroneous results when using a container port lower than 60, because YAML
> parses numbers in the format `xx:yy` as a base-60 value. For this reason,
> we recommend always explicitly specifying your port mappings as strings.
@ -1250,7 +1275,7 @@ ports:
### runtime
> [Added in version 2.3 file format](compose-versioning.md#version-23)
> Added in [version 2.3](compose-versioning.md#version-23) file format.
Specify which runtime to use for the service's containers. Default runtime
and available runtimes are listed in the output of `docker info`.
@ -1264,7 +1289,7 @@ web:
### scale
> [Added in version 2.2 file format](compose-versioning.md#version-22)
> Added in [version 2.2](compose-versioning.md#version-22) file format.
Specify the default number of containers to deploy for this service. Whenever
you run `docker-compose up`, Compose creates or removes containers to match
@ -1318,7 +1343,7 @@ stop_signal: SIGUSR1
### storage_opt
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Set storage driver options for this service.
@ -1329,7 +1354,7 @@ storage_opt:
### sysctls
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Kernel parameters to set in the container. You can use either an array or a
dictionary.
@ -1375,7 +1400,7 @@ ulimits:
### userns_mode
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
```yaml
userns_mode: "host"
@ -1390,10 +1415,6 @@ more information.
Mount host paths or named volumes. Named volumes need to be specified with the
[top-level `volumes` key](#volume-configuration-reference).
You can mount a relative path on the host, which expands relative to
the directory of the Compose configuration file being used. Relative paths
should always begin with `.` or `..`.
#### Short syntax
The short syntax uses the generic `[SOURCE:]TARGET[:MODE]` format, where
@ -1401,6 +1422,10 @@ The short syntax uses the generic `[SOURCE:]TARGET[:MODE]` format, where
path where the volume is mounted. Standard modes are `ro` for read-only
and `rw` for read-write (default).
You can mount a relative path on the host, which expands relative to
the directory of the Compose configuration file being used. Relative paths
should always begin with `.` or `..`.
```yaml
volumes:
# Just specify a path and let the Engine create a volume
@ -1421,7 +1446,7 @@ volumes:
#### Long syntax
> [Added in version 2.3 file format](compose-versioning.md#version-23).
> Added in [version 2.3](compose-versioning.md#version-23) file format.
The long form syntax allows the configuration of additional fields that can't be
expressed in the short form.
@ -1465,7 +1490,9 @@ volumes:
mydata:
```
> **Note**: When creating bind mounts, using the long syntax requires the
> **Note**
>
> 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](/engine/admin/volumes/bind-mounts.md/#differences-between--v-and---mount-behavior)
@ -1480,7 +1507,9 @@ service.
volume_driver: mydriver
```
> **Note**: In [version 2 files](compose-versioning.md#version-2), this
> **Note**
>
> In [version 2 files](compose-versioning.md#version-2), this
> option only applies to anonymous volumes (those specified in the image,
> or specified under `volumes` without an explicit named volume or host path).
> To configure the driver for a named volume, use the `driver` key under the
@ -1504,13 +1533,11 @@ volumes_from:
- container:container_name:rw
```
> **Notes**
> Changed in [version 2](compose-versioning.md#version-2) file format.
>
>* The `container:...` formats are only supported in the
> [version 2 file format](compose-versioning.md#version-2).
>
>* In [version 1](compose-versioning.md#version-1), you can use
> container names without marking them as such:
> The `container:...` formats are only supported in the [version 2](compose-versioning.md#version-2)
> file format. In [version 1](compose-versioning.md#version-1), you can use container
> names without marking them as such:
>
> - `service_name`
> - `service_name:ro`
@ -1541,10 +1568,13 @@ restart: unless-stopped
Each of these is a single value, analogous to its
[docker run](/engine/reference/run.md#runtime-constraints-on-resources) counterpart.
> **Note**: The following options were added in [version 2.2](compose-versioning.md#version-22):
> `cpu_count`, `cpu_percent`, `cpus`.
> The following options were added in [version 2.1](compose-versioning.md#version-21):
> `oom_kill_disable`, `cpu_period`
> Added in [version 2.2](compose-versioning.md#version-22) file format.
>
> The `cpu_count`, `cpu_percent`, and `cpus` options were added in [version 2.2](compose-versioning.md#version-22).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
>
> The `oom_kill_disable` and `cpu_period` options were added in [version 2.1](compose-versioning.md#version-21).
```yaml
cpu_count: 2
@ -1710,12 +1740,14 @@ volumes:
name: actual-name-of-volume
```
> **Note**: In newer versions of Compose, the `external.name` property is
> deprecated in favor of simply using the `name` property.
> Deprecated in [version 2.1](compose-versioning.md#version-21) file format.
>
> external.name was deprecated in version 2.1 file format use `name` instead.
{: .important }
### labels
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Add metadata to containers using
[Docker labels](/engine/userguide/labels-custom-metadata.md). You can use either
@ -1740,7 +1772,7 @@ labels:
### name
> [Added in version 2.1 file format](compose-versioning.md#version-21)
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Set a custom name for this volume. The name field can be used to reference
volumes that contain special characters. The name is used as is
@ -1783,9 +1815,11 @@ The Docker Engine returns an error if the driver is not available.
driver: overlay
```
Starting in Compose file format 2.1, overlay networks are always created as
`attachable`, and this is not configurable. This means that standalone
containers can connect to overlay networks.
> Changed in [version 2.1](compose-versioning.md#version-21) file format.
>
> Starting in Compose file format 2.1, overlay networks are always created as
> `attachable`, and this is not configurable. This means that standalone
> containers can connect to overlay networks.
### driver_opts
@ -1801,7 +1835,7 @@ driver_opts:
### enable_ipv6
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Enable IPv6 networking on this network.
@ -1846,7 +1880,7 @@ you can set this option to `true`.
### labels
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Add metadata to containers using
[Docker labels](/engine/userguide/labels-custom-metadata.md). You can use either
@ -1920,7 +1954,7 @@ Not supported for version 2 `docker-compose` files. Use
### name
> [Added in version 2.1 file format](compose-versioning.md#version-21)
> Added in [version 2.1](compose-versioning.md#version-21) file format.
Set a custom name for this network. The name field can be used to reference
networks which contain special characters. The name is used as is
@ -1949,7 +1983,7 @@ networks:
## Extension fields
> [Added in version 2.1 file format](compose-versioning.md#version-21).
> Added in [version 2.1](compose-versioning.md#version-21) file format.
{% include content/compose-extfields-sub.md %}

356
compose/compose-file/index.md
View File

@ -203,9 +203,12 @@ image: webapp:tag
This results in an image named `webapp` and tagged `tag`, built from `./dir`.
> **Note**: This option is ignored when
> Note when using docker stack deploy
>
> The `build` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file. The `docker stack` command accepts only pre-built images.
> The `docker stack` command does not build images before deploying.
{: .important }
#### context
@ -270,10 +273,13 @@ build:
- gitcommithash=cdc3b19
```
> **Note**: In your Dockerfile, if you specify `ARG` before the `FROM` instruction,
> Scope of build-args
>
> 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.
> See [Understand how ARGS and FROM interact](/engine/reference/builder/#understand-how-arg-and-from-interact) for usage details.
> 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](/engine/reference/builder/#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
at build time is the value in the environment where Compose is running.
@ -284,8 +290,11 @@ args:
- gitcommithash
```
> **Note**: YAML boolean values (`true`, `false`, `yes`, `no`, `on`, `off`) must
> be enclosed in quotes, so that the parser interprets them as strings.
> Tip when using boolean values
>
> YAML boolean values (`"true"`, `"false"`, `"yes"`, `"no"`, `"on"`,
> `"off"`) must be enclosed in quotes, so that the parser interprets them as
> strings.
#### cache_from
@ -377,9 +386,11 @@ cap_drop:
- SYS_ADMIN
```
> **Note**: These options are ignored when
> Note when using docker stack deploy
>
> The `cap_add` and `cap_drop` options are ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
{: .important }
### cgroup_parent
@ -389,9 +400,11 @@ Specify an optional parent cgroup for the container.
cgroup_parent: m-executor-abcd
```
> **Note**: This option is ignored when
> Note when using docker stack deploy
>
> The `cgroup_parent` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
{: .important }
### command
@ -434,8 +447,10 @@ already been defined in Docker, either by running the `docker config create`
command or by another stack deployment. If the external config does not exist,
the stack deployment fails with a `config not found` error.
> **Note**: `config` definitions are only supported in version 3.3 and higher
> of the compose file format.
> Added in [version 3.3](compose-versioning.md#version-33) file format.
>
> `config` definitions are only supported in version 3.3 and higher of the
> compose file format.
```yaml
version: "{{ site.compose_file_v3 }}"
@ -514,14 +529,19 @@ Because Docker container names must be unique, you cannot scale a service beyond
1 container if you have specified a custom name. Attempting to do so results in
an error.
> **Note**: This option is ignored when
> Note when using docker stack deploy
>
> The `container_name` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
{: .important }
### credential_spec
> **Note**: This option was added in v3.3. Using group Managed Service Account
> (gMSA) configurations with compose files is supported in Compose version 3.8.
> Added in [version 3.3](compose-versioning.md#version-33) file format.
>
> The `credential_spec` option was added in v3.3. Using group Managed Service
> Account (gMSA) configurations with compose files is supported in file format
> version 3.8 or up.
Configure the credential spec for managed service account. This option is only
used for services using Windows containers. The `credential_spec` must be in the
@ -609,7 +629,7 @@ services:
### deploy
> **[Version 3](compose-versioning.md#version-3) only.**
> Added in [version 3](compose-versioning.md#version-3) file format.
Specify configuration related to the deployment and running of services. This
only takes effect when deploying to a [swarm](/engine/swarm/index.md) with
@ -634,9 +654,9 @@ Several sub-options are available:
#### endpoint_mode
Specify a service discovery method for external clients connecting to a swarm.
> Added in [version 3.3](compose-versioning.md#version-33) file format.
> **[Version 3.3](compose-versioning.md#version-3) only.**
Specify a service discovery method for external clients connecting to a swarm.
* `endpoint_mode: vip` - Docker assigns the service a virtual IP (VIP)
that acts as the front end for clients to reach the service on a
@ -780,10 +800,13 @@ services:
Configures resource constraints.
> **Note**: This replaces the [older resource constraint options](compose-file-v2.md#cpu-and-other-resources) for non swarm mode in
Compose files prior to version 3 (`cpu_shares`, `cpu_quota`, `cpuset`,
`mem_limit`, `memswap_limit`, `mem_swappiness`), as described in [Upgrading
version 2.x to 3.x](/compose/compose-file/compose-versioning.md#upgrading).
> Changed in compose-file version 3
>
> The `resources` section replaces the [older resource constraint options](compose-file-v2.md#cpu-and-other-resources)
> in Compose files prior to version 3 (`cpu_shares`, `cpu_quota`, `cpuset`,
> `mem_limit`, `memswap_limit`, `mem_swappiness`).
> Refer to [Upgrading version 2.x to 3.x](/compose/compose-file/compose-versioning.md#upgrading)
> to learn about differences between version 2 and 3 of the compose-file format.
Each of these is a single value, analogous to its [docker service
create](/engine/reference/commandline/service_create.md) counterpart.
@ -863,7 +886,7 @@ services:
#### rollback_config
> [Version 3.7 file format](compose-versioning.md#version-37) and up
> Added in [version 3.7](compose-versioning.md#version-37) file format.
Configures how the service should be rollbacked in case of a failing
update.
@ -888,8 +911,10 @@ updates.
- `max_failure_ratio`: Failure rate to tolerate during an update.
- `order`: Order of operations during updates. One of `stop-first` (old task is stopped before starting new one), or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`) **Note**: Only supported for v3.4 and higher.
> **Note**: `order` is only supported for v3.4 and higher of the compose
file format.
> Added in [version 3.4](compose-versioning.md#version-34) file format.
>
> The `order` option is only supported by v3.4 and higher of the compose
> file format.
```yaml
version: "{{ site.compose_file_v3 }}"
@ -922,12 +947,13 @@ The following sub-options (supported for `docker-compose up` and `docker-compose
- [security_opt](#security_opt)
- [userns_mode](#userns_mode)
>**Tip:** See the section on [how to configure volumes
for services, swarms, and docker-stack.yml
files](#volumes-for-services-swarms-and-stack-files). Volumes _are_ supported
but to work with swarms and services, they must be configured
as named volumes or associated with services that are constrained to nodes with
access to the requisite volumes.
> Tip
>
> See the section on [how to configure volumes for services, swarms, and docker-stack.yml
> files](#volumes-for-services-swarms-and-stack-files). Volumes _are_ supported
> but to work with swarms and services, they must be configured as named volumes
> or associated with services that are constrained to nodes with access to the
> requisite volumes.
### devices
@ -939,9 +965,11 @@ devices:
- "/dev/ttyUSB0:/dev/ttyUSB0"
```
> **Note**: This option is ignored when
> Note when using docker stack deploy
>
> The `devices` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
{: .important }
### dns
@ -992,10 +1020,12 @@ entrypoint:
- vendor/bin/phpunit
```
> **Note**: Setting `entrypoint` both overrides any default entrypoint set
> on the service's image with the `ENTRYPOINT` Dockerfile instruction, *and*
> clears out any default command on the image - meaning that if there's a `CMD`
> instruction in the Dockerfile, it is ignored.
> **Note**
>
> Setting `entrypoint` both overrides any default entrypoint set on the service's
> image with the `ENTRYPOINT` Dockerfile instruction, *and* clears out any default
> command on the image - meaning that if there's a `CMD` instruction in the
> Dockerfile, it is ignored.
### env_file
@ -1028,10 +1058,12 @@ also ignored.
RACK_ENV=development
```
> **Note**: If your service specifies a [build](#build) option, variables
> defined in environment files are _not_ automatically visible during the
> build. Use the [args](#args) sub-option of `build` to define build-time
> environment variables.
> **Note**
>
> If your service specifies a [build](#build) option, variables defined in
> environment files are _not_ automatically visible during the build. Use
> the [args](#args) sub-option of `build` to define build-time environment
> variables.
The value of `VAL` is used as is and not modified at all. For example if the
value is surrounded by quotes (as is often the case of shell variables), the
@ -1091,10 +1123,12 @@ environment:
- SESSION_SECRET
```
> **Note**: If your service specifies a [build](#build) option, variables
> defined in `environment` are _not_ automatically visible during the
> build. Use the [args](#args) sub-option of `build` to define build-time
> environment variables.
> **Note**
>
> If your service specifies a [build](#build) option, variables defined in
> `environment` are _not_ automatically visible during the build. Use the
> [args](#args) sub-option of `build` to define build-time environment
> variables.
### expose
@ -1121,15 +1155,17 @@ external_links:
- project_db_1:postgresql
```
> **Notes:**
> **Note**
>
> If you're using the [version 2 or above file format](compose-versioning.md#version-2),
> the externally-created containers must be connected to at least one of the same
> The externally-created containers must be connected to at least one of the same
> networks as the service that is linking to them. [Links](compose-file-v2#links)
> are a legacy option. We recommend using [networks](#networks) instead.
> Note when using docker stack deploy
>
> This option is ignored when [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
> The `external_links` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
{: .important }
### extra_hosts
@ -1150,8 +1186,6 @@ An entry with the ip address and hostname is created in `/etc/hosts` inside cont
### healthcheck
> [Version 2.1 file format](compose-versioning.md#version-21) and up.
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](/engine/reference/builder.md#healthcheck)
@ -1169,8 +1203,9 @@ healthcheck:
`interval`, `timeout` and `start_period` are specified as
[durations](#specifying-durations).
> **Note**: `start_period` is only supported for v3.4 and higher of the compose
> file format.
> Added in [version 3.4](compose-versioning.md#version-34) file format.
>
> The `start_period` option was added in file format 3.4.
`test` must be either a string or a list. If it's a list, the first item must be
either `NONE`, `CMD` or `CMD-SHELL`. If it's a string, it's equivalent to
@ -1226,7 +1261,7 @@ options and tags it with the specified tag.
### init
> [Added in version 3.7 file format](compose-versioning.md#version-37).
> Added in [version 3.7](compose-versioning.md#version-37) file format.
Run an init inside the container that forwards signals and reaps processes.
Set this option to `true` to enable this feature for the service.
@ -1274,14 +1309,17 @@ labels:
### links
>**Warning**: The `--link` flag is a legacy feature of Docker. It
may eventually be removed. Unless you absolutely need to continue using it, we
recommend that you use [user-defined networks](/engine/userguide/networking//#user-defined-networks)
to facilitate communication between two containers instead of using `--link`.
One feature that user-defined networks do not support that you can do with
`--link` is sharing environmental variables between containers. However, you can
use other mechanisms such as volumes to share environment variables between
containers in a more controlled way.
>**Warning**
>
> The `--link` flag is a legacy feature of Docker. It may eventually be removed.
> Unless you absolutely need to continue using it, we recommend that you use
> [user-defined networks](/engine/userguide/networking//#user-defined-networks)
> to facilitate communication between two containers instead of using `--link`.
>
> One feature that user-defined networks do not support that you can do with
> `--link` is sharing environmental variables between containers. However, you
> can use other mechanisms such as volumes to share environment variables between
> containers in a more controlled way.
{:.warning}
Link to containers in another service. Either specify both the service name and
@ -1305,14 +1343,17 @@ any service can reach any other service at that service’s name. (See also, the
Links also express dependency between services in the same way as
[depends_on](#depends_on), so they determine the order of service startup.
> **Notes**
> **Note**
>
> * If you define both links and [networks](#networks), services with
> links between them must share at least one network in common to
> communicate.
> * This option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
> If you define both links and [networks](#networks), services with
> links between them must share at least one network in common to
> communicate.
> Note when using docker stack deploy
>
> The `links` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
{: .important }
### logging
@ -1341,9 +1382,11 @@ driver: "syslog"
driver: "none"
```
> **Note**: Only the `json-file` and `journald` drivers make the logs available
> directly from `docker-compose up` and `docker-compose logs`. Using any other
> driver does not print any logs.
> **Note**
>
> Only the `json-file` and `journald` drivers make the logs available directly
> from `docker-compose up` and `docker-compose logs`. Using any other driver
> does not print any logs.
Specify logging options for the logging driver with the ``options`` key, as with the ``--log-opt`` option for `docker run`.
@ -1385,10 +1428,10 @@ services:
> Logging options available depend on which logging driver you use
>
> The above example for controlling log files and sizes uses options
specific to the [json-file driver](/engine/admin/logging/overview.md#json-file).
These particular options are not available on other logging drivers.
For a full list of supported logging drivers and their options, see
[logging drivers](/engine/admin/logging/overview.md).
> specific to the [json-file driver](/engine/admin/logging/overview.md#json-file).
> These particular options are not available on other logging drivers.
> For a full list of supported logging drivers and their options, refer to the
> [logging drivers](/engine/admin/logging/overview.md) documentation.
### network_mode
@ -1411,14 +1454,12 @@ network_mode: "service:[service name]"
network_mode: "container:[container name/id]"
```
> **Notes**
> **Note**
>
>* This option is ignored when
[deploying a stack in swarm
mode](/engine/reference/commandline/stack_deploy.md) with a (version 3) Compose
file.
>
>* `network_mode: "host"` cannot be mixed with [links](#links).
> * This option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md).
> * `network_mode: "host"` cannot be mixed with [links](#links).
{: .important }
### networks
@ -1439,7 +1480,11 @@ Aliases (alternative hostnames) for this service on the network. Other container
Since `aliases` is network-scoped, the same service can have different aliases on different networks.
> **Note**: A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name resolves to is not guaranteed.
> **Note**
>
> A network-wide alias can be shared by multiple containers, and even by multiple
> services. If it is, then exactly which container the name resolves to is not
> guaranteed.
The general format is shown here.
@ -1539,14 +1584,18 @@ containers in the bare-metal machine's namespace and vice versa.
Expose ports.
> **Note**: Port mapping is incompatible with `network_mode: host`
> **Note**
>
> Port mapping is incompatible with `network_mode: host`
#### Short syntax
Either specify both ports (`HOST:CONTAINER`), or just the container
port (an ephemeral host port is chosen).
> **Note**: When mapping ports in the `HOST:CONTAINER` format, you may experience
> **Note**
>
> When mapping ports in the `HOST:CONTAINER` format, you may experience
> erroneous results when using a container port lower than 60, because YAML
> parses numbers in the format `xx:yy` as a base-60 value. For this reason,
> we recommend always explicitly specifying your port mappings as strings.
@ -1583,7 +1632,9 @@ ports:
mode: host
```
> **Note**: The long syntax is new in v3.2
> Added in [version 3.2](compose-versioning.md#version-32) file format.
>
> The long syntax is new in the v3.2 file format.
### restart
@ -1597,18 +1648,23 @@ on-failure error.
restart: on-failure
restart: unless-stopped
> **Note**: This option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file. Use [restart_policy](#restart_policy) instead.
> Note when using docker stack deploy
>
> The `restart` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md).
{: .important }
### secrets
Grant access to secrets on a per-service basis using the per-service `secrets`
configuration. Two different syntax variants are supported.
> **Note**: The secret must already exist or be
> Note when using docker stack deploy
>
> The secret must already exist or be
> [defined in the top-level `secrets` configuration](#secrets-configuration-reference)
> of this stack file, or stack deployment fails.
> of the compose file, or stack deployment fails.
{: .important }
For more information on secrets, see [secrets](/engine/swarm/secrets.md).
@ -1703,9 +1759,11 @@ security_opt:
- label:role:ROLE
```
> **Note**: This option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
> Note when using docker stack deploy
>
> The `security_opt` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md).
{: .important }
### stop_grace_period
@ -1757,12 +1815,15 @@ support changing sysctls inside a container that also modify the host system.
For an overview of supported sysctls, refer to [configure namespaced kernel
parameters (sysctls) at runtime](/engine/reference/commandline/run/#configure-namespaced-kernel-parameters-sysctls-at-runtime).
> Note when using docker stack deploy
>
> This option requires Docker Engine 19.03 or up when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md).
### tmpfs
> Added in [version 3.6](compose-versioning.md#version-36) file format.
Mount a temporary file system inside the container. Can be a single value or a list.
```yaml
@ -1775,12 +1836,12 @@ tmpfs:
- /tmp
```
> **Note**: This option is ignored when
> Note when using docker stack deploy
>
> This option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3-3.5) Compose file.
> [Version 3.6 file format](compose-versioning.md#version-3) and up.
Mount a temporary file system inside the container. Size parameter specifies the size
of the tmpfs mount in bytes. Unlimited by default.
@ -1814,9 +1875,11 @@ Disables the user namespace for this service, if Docker daemon is configured wit
See [dockerd](/engine/reference/commandline/dockerd.md#disable-user-namespace-for-a-container) for
more information.
> **Note**: This option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md)
> with a (version 3) Compose file.
> Note when using docker stack deploy
>
> The `userns_mode` option is ignored when
> [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md).
{: .important }
### volumes
@ -1830,10 +1893,11 @@ volume in the [top-level `volumes` key](#volume-configuration-reference). Use
named volumes with [services, swarms, and stack
files](#volumes-for-services-swarms-and-stack-files).
> **Note**: The top-level
> [volumes](#volume-configuration-reference) key defines
> a named volume and references it from each service's `volumes` list. This replaces `volumes_from` in earlier versions of the Compose file format. See [Use volumes](/engine/admin/volumes/volumes.md) and [Volume
Plugins](/engine/extend/plugins_volume.md) for general information on volumes.
> Changed in [version 3](compose-versioning.md#version-3) file format.
>
> The top-level [volumes](#volume-configuration-reference) key defines
> a named volume and references it from each service's `volumes` list. This
> replaces `volumes_from` in earlier versions of the Compose file format.
This example shows a named volume (`mydata`) being used by the `web` service,
and a bind mount defined for a single service (first path under `db` service
@ -1868,14 +1932,18 @@ volumes:
dbdata:
```
> **Note**: See [Use volumes](/engine/admin/volumes/volumes.md) and [Volume
> Plugins](/engine/extend/plugins_volume.md) for general information on volumes.
> **Note**
>
> For general information on volumes, refer to the [use volumes](/engine/admin/volumes/volumes.md)
> and [volume plugins](/engine/extend/plugins_volume.md) sections in the documentation.
#### Short syntax
Optionally specify a path on the host machine
(`HOST:CONTAINER`), or an access mode (`HOST:CONTAINER:ro`).
The short syntax uses the generic `[SOURCE:]TARGET[:MODE]` format, where
`SOURCE` can be either a host path or volume name. `TARGET` is the container
path where the volume is mounted. Standard modes are `ro` for read-only
and `rw` for read-write (default).
You can mount a relative path on the host, which expands relative to
the directory of the Compose configuration file being used. Relative paths
@ -1901,6 +1969,8 @@ volumes:
#### Long syntax
> Added in [version 3.2](compose-versioning.md#version-32) file format.
The long form syntax allows the configuration of additional fields that can't be
expressed in the short form.
@ -1945,14 +2015,21 @@ volumes:
mydata:
```
> **Note**: The long syntax is new in v3.2
> **Note**
>
> 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](/engine/admin/volumes/bind-mounts.md/#differences-between--v-and---mount-behavior)
> for more information.
#### Volumes for services, swarms, and stack files
When working with services, swarms, and `docker-stack.yml` files, keep in mind
that the tasks (containers) backing a service can be deployed on any node in a
swarm, and this may be a different node each time the service is updated.
> Note when using docker stack deploy
>
> When working with services, swarms, and `docker-stack.yml` files, keep in mind
> that the tasks (containers) backing a service can be deployed on any node in a
> swarm, and this may be a different node each time the service is updated.
In the absence of having named volumes with specified sources, Docker creates an
anonymous volume for each task backing a service. Anonymous volumes do not
@ -2160,8 +2237,10 @@ volumes:
external: true
```
> [external.name was deprecated in version 3.4 file format](compose-versioning.md#version-34)
> use `name` instead.
> Deprecated in [version 3.4](compose-versioning.md#version-34) file format.
>
> external.name was deprecated in version 3.4 file format use `name` instead.
{: .important }
You can also specify the name of the volume separately from the name used to
refer to it within the Compose file:
@ -2173,16 +2252,15 @@ volumes:
name: actual-name-of-volume
```
> External volumes are always created with docker stack deploy
> Note when using docker stack deploy
>
External volumes that do not exist _are created_ if you use [docker stack
deploy](#deploy) to launch the app in [swarm mode](/engine/swarm/index.md)
(instead of [docker compose up](/compose/reference/up.md)). In swarm mode, a
volume is automatically created when it is defined by a service. As service
tasks are scheduled on new nodes,
[swarmkit](https://github.com/docker/swarmkit/blob/master/README.md) creates the
volume on the local node. To learn more, see
[moby/moby#29976](https://github.com/moby/moby/issues/29976).
> External volumes that do not exist _are created_ if you use [docker stack
> deploy](#deploy) to launch the app in [swarm mode](/engine/swarm/index.md)
> (instead of [docker compose up](/compose/reference/up.md)). In swarm mode, a
> volume is automatically created when it is defined by a service. As service
> tasks are scheduled on new nodes, [swarmkit](https://github.com/docker/swarmkit/blob/master/README.md)
> creates the volume on the local node. To learn more, see [moby/moby#29976](https://github.com/moby/moby/issues/29976).
{: .important }
### labels
@ -2209,7 +2287,7 @@ labels:
### name
> [Added in version 3.4 file format](compose-versioning.md#version-34)
> Added in [version 3.4](compose-versioning.md#version-34) file format.
Set a custom name for this volume. The name field can be used to reference
volumes that contain special characters. The name is used as is
@ -2343,7 +2421,7 @@ driver_opts:
### attachable
> **Note**: Only supported for v3.2 and higher.
> Added in [version 3.2](compose-versioning.md#version-32) file format.
Only used when the `driver` is set to `overlay`. If set to `true`, then
standalone containers can attach to this network, in addition to services. If a
@ -2387,7 +2465,9 @@ ipam:
- subnet: 172.28.0.0/16
```
> **Note**: Additional IPAM configurations, such as `gateway`, are only honored for version 2 at the moment.
> **Note**
>
> Additional IPAM configurations, such as `gateway`, are only honored for version 2 at the moment.
### internal
@ -2453,8 +2533,10 @@ networks:
external: true
```
> [external.name was deprecated in version 3.5 file format](compose-versioning.md#version-35)
> use `name` instead.
> Deprecated in [version 3.5](compose-versioning.md#version-35) file format.
>
> external.name was deprecated in version 3.5 file format use `name` instead.
{: .important }
You can also specify the name of the network separately from the name used to
refer to it within the Compose file:
@ -2469,7 +2551,7 @@ networks:
### name
> [Added in version 3.5 file format](compose-versioning.md#version-35)
> Added in [version 3.5](compose-versioning.md#version-35) file format.
Set a custom name for this network. The name field can be used to reference
networks which contain special characters. The name is used as is
@ -2600,7 +2682,7 @@ stack.
## Extension fields
> [Added in version 3.4 file format](compose-versioning.md#version-34).
> Added in [version 3.4](compose-versioning.md#version-34) file format.
{% include content/compose-extfields-sub.md %}