diff --git a/compose/compose-file/compose-file-v1.md b/compose/compose-file/compose-file-v1.md index 9e5c1ac1de..7a3aee3c5e 100644 --- a/compose/compose-file/compose-file-v1.md +++ b/compose/compose-file/compose-file-v1.md @@ -27,7 +27,8 @@ The Version 1 Compose file is a [YAML](http://yaml.org/) file that defines [serv The default path for a Compose file is `./docker-compose.yml`. ->**Tip**: You can use either a `.yml` or `.yaml` extension for this file. They both work. +> **Tip**: You can use either a `.yml` or `.yaml` extension for this file. +> They both work. A service definition contains configuration which is applied to each container started for that service, much like passing command-line parameters to @@ -47,17 +48,19 @@ Configuration options that are applied at build time. `build` can specified as a string containing a path to the build context. - build: ./dir +```yaml +build: ./dir +``` > **Note** > -> In [version 1 file format](compose-versioning.md#version-1), -`build` is different in two ways: +> In [version 1 file format](compose-versioning.md#version-1), `build` is +> different in two ways: > ->* Only the string form (`build: .`) is allowed - not the object +> * Only the string form (`build: .`) is allowed - not the object > form that is allowed in Version 2 and up. > * Using `build` together with [`image`](#image) is not allowed. -Attempting to do so results in an error. +> Attempting to do so results in an error. #### dockerfile @@ -66,28 +69,33 @@ Alternate Dockerfile. Compose uses an alternate file to build with. A build path must also be specified. - build: . - dockerfile: Dockerfile-alternate +```yaml +build: . +dockerfile: Dockerfile-alternate +``` > **Note** > -> In the [version 1 file format](compose-versioning.md#version-1), `dockerfile` is different from newer versions in two ways: +> In the [version 1 file format](compose-versioning.md#version-1), `dockerfile` +> is different from newer versions in two ways: > ->* It appears alongside `build`, not as a sub-option: -> ->* Using `dockerfile` together with [`image`](#image) is not allowed. Attempting to do so results in an error. +> * It appears alongside `build`, not as a sub-option: +> * Using `dockerfile` together with [`image`](#image) is not allowed. +> Attempting to do so results in an error. ### cap_add, cap_drop Add or drop container capabilities. See `man 7 capabilities` for a full list. - cap_add: - - ALL +```yaml +cap_add: + - ALL - cap_drop: - - NET_ADMIN - - SYS_ADMIN +cap_drop: + - NET_ADMIN + - SYS_ADMIN +``` > **Note**: These options are ignored when > [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md) @@ -97,24 +105,32 @@ See `man 7 capabilities` for a full list. Override the default command. - command: bundle exec thin -p 3000 +```yaml +command: bundle exec thin -p 3000 +``` The command can also be a list, in a manner similar to [dockerfile](/engine/reference/builder.md#cmd): - command: ["bundle", "exec", "thin", "-p", "3000"] +```yaml +command: ["bundle", "exec", "thin", "-p", "3000"] +``` ### cgroup_parent Specify an optional parent cgroup for the container. - cgroup_parent: m-executor-abcd +```yaml +cgroup_parent: m-executor-abcd +``` ### container_name Specify a custom container name, rather than a generated default name. - container_name: my-web-container +```yaml +container_name: my-web-container +``` 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 @@ -125,43 +141,59 @@ results in an error. List of device mappings. Uses the same format as the `--device` docker client create option. - devices: - - "/dev/ttyUSB0:/dev/ttyUSB0" +```yaml +devices: + - "/dev/ttyUSB0:/dev/ttyUSB0" +``` ### dns Custom DNS servers. Can be a single value or a list. - dns: 8.8.8.8 - dns: - - 8.8.8.8 - - 9.9.9.9 +```yaml +dns: 8.8.8.8 +``` + +```yaml +dns: + - 8.8.8.8 + - 9.9.9.9 +``` ### dns_search Custom DNS search domains. Can be a single value or a list. - dns_search: example.com - dns_search: - - dc1.example.com - - dc2.example.com +```yaml +dns_search: example.com +``` + +```yaml +dns_search: + - dc1.example.com + - dc2.example.com +``` ### entrypoint Override the default entrypoint. - entrypoint: /code/entrypoint.sh +```yaml +entrypoint: /code/entrypoint.sh +``` The entrypoint can also be a list, in a manner similar to [dockerfile](/engine/reference/builder.md#entrypoint): - entrypoint: - - php - - -d - - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so - - -d - - memory_limit=-1 - - vendor/bin/phpunit +```yaml +entrypoint: + - php + - -d + - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so + - -d + - memory_limit=-1 + - vendor/bin/phpunit +``` > **Note**: Setting `entrypoint` both overrides any default entrypoint set > on the service's image with the `ENTRYPOINT` Dockerfile instruction, *and* @@ -175,22 +207,29 @@ Add environment variables from a file. Can be a single value or a list. If you have specified a Compose file with `docker-compose -f FILE`, paths in `env_file` are relative to the directory that file is in. -Environment variables specified in [environment](#environment) _override_ -these values. +Environment variables declared in the [environment](#environment) section +_override_ these values – this holds true even if those values are +empty or undefined. - env_file: .env +```yaml +env_file: .env +``` - env_file: - - ./common.env - - ./apps/web.env - - /opt/secrets.env +```yaml +env_file: + - ./common.env + - ./apps/web.env + - /opt/runtime_opts.env +``` Compose expects each line in an env file to be in `VAR=VAL` format. Lines beginning with `#` are processed as comments and are ignored. Blank lines are also ignored. - # Set Rails/Rack environment - RACK_ENV=development +```console +# Set Rails/Rack environment +RACK_ENV=development +``` > **Note**: If your service specifies a [build](#build) option, variables > defined in environment files are _not_ automatically visible during the @@ -217,38 +256,42 @@ services: And the following files: -```none +```console # a.env VAR=1 ``` and -```none +```console # b.env VAR=hello ``` -$VAR is `hello`. +`$VAR` is `hello`. ### environment Add environment variables. You can use either an array or a dictionary. Any -boolean values; true, false, yes no, need to be enclosed in quotes to ensure +boolean values (true, false, yes, no) need to be enclosed in quotes to ensure they are not converted to True or False by the YML parser. Environment variables with only a key are resolved to their values on the machine Compose is running on, which can be helpful for secret or host-specific values. - environment: - RACK_ENV: development - SHOW: 'true' - SESSION_SECRET: +```yaml +environment: + RACK_ENV: development + SHOW: 'true' + SESSION_SECRET: +``` - environment: - - RACK_ENV=development - - SHOW=true - - SESSION_SECRET +```yaml +environment: + - RACK_ENV=development + - SHOW=true + - SESSION_SECRET +``` > **Note**: If your service specifies a [build](#build) option, variables > defined in `environment` are _not_ automatically visible during the @@ -259,9 +302,11 @@ machine Compose is running on, which can be helpful for secret or host-specific Expose ports without publishing them to the host machine - they'll only be accessible to linked services. Only the internal port can be specified. - expose: - - "3000" - - "8000" +```yaml +expose: + - "3000" + - "8000" +``` ### extends @@ -272,9 +317,11 @@ You can use `extends` on any service together with other configuration keys. The `extends` value must be a dictionary defined with a required `service` and an optional `file` key. - extends: - file: common.yml - service: webapp +```yaml +extends: + file: common.yml + service: webapp +``` The `service` the name of the service being extended, for example `web` or `database`. The `file` is the location of a Compose configuration @@ -294,46 +341,63 @@ For more on `extends`, see the ### external_links -Link to containers started outside this `docker-compose.yml` or even outside -of Compose, especially for containers that provide shared or common services. -`external_links` follow semantics similar to `links` when specifying both the -container name and the link alias (`CONTAINER:ALIAS`). +Link to containers started outside this `docker-compose.yml` or even outside of +Compose, especially for containers that provide shared or common services. +`external_links` follow semantics similar to `links` when +specifying both the container name and the link alias (`CONTAINER:ALIAS`). - external_links: - - redis_1 - - project_db_1:mysql - - project_db_1:postgresql +```yaml +external_links: + - redis_1 + - project_db_1:mysql + - project_db_1:postgresql +``` ### extra_hosts Add hostname mappings. Use the same values as the docker client `--add-host` parameter. - extra_hosts: - - "somehost:162.242.195.82" - - "otherhost:50.31.209.229" +```yaml +extra_hosts: + - "somehost:162.242.195.82" + - "otherhost:50.31.209.229" +``` An entry with the ip address and hostname is created in `/etc/hosts` inside containers for this service, e.g: - 162.242.195.82 somehost - 50.31.209.229 otherhost +```console +162.242.195.82 somehost +50.31.209.229 otherhost +``` ### image Specify the image to start the container from. Can either be a repository/tag or a partial image ID. - image: redis - image: ubuntu:14.04 - image: tutum/influxdb - image: example-registry.com:4000/postgresql - image: a4bc65fd +```yaml +image: redis +``` +```yaml +image: ubuntu:18.04 +``` +```yaml +image: tutum/influxdb +``` +```yaml +image: example-registry.com:4000/postgresql +``` +```yaml +image: a4bc65fd +``` If the image does not exist, Compose attempts to pull it, unless you have also specified [build](#build), in which case it builds it using the specified options and tags it with the specified tag. -> **Note**: In the [version 1 file format](compose-versioning.md#version-1), using [`build`](#build) together -> with `image` is not allowed. Attempting to do so results in an error. +> **Note**: In the [version 1 file format](compose-versioning.md#version-1), +> using [`build`](#build) together with `image` is not allowed. Attempting to do +> so results in an error. ### labels @@ -341,29 +405,35 @@ Add metadata to containers using [Docker labels](/engine/userguide/labels-custom It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software. - labels: - com.example.description: "Accounting webapp" - com.example.department: "Finance" - com.example.label-with-empty-value: "" +```yaml +labels: + com.example.description: "Accounting webapp" + com.example.department: "Finance" + com.example.label-with-empty-value: "" +``` - labels: - - "com.example.description=Accounting webapp" - - "com.example.department=Finance" - - "com.example.label-with-empty-value" +```yaml +labels: + - "com.example.description=Accounting webapp" + - "com.example.department=Finance" + - "com.example.label-with-empty-value" +``` ### links Link to containers in another service. Either specify both the service name and -a link alias (`SERVICE:ALIAS`), or just the service name. +a link alias (`"SERVICE:ALIAS"`), or just the service name. > Links are a legacy option. We recommend using > [networks](#networks) instead. - web: - links: - - db - - db:database - - redis +```yaml +web: + links: + - "db" + - "db:database" + - "redis" +``` Containers for the linked service are reachable at a hostname identical to the alias, or the service name if no alias was specified. @@ -371,7 +441,9 @@ the alias, or the service name if no alias was specified. Links also express dependency between services in the same way as [depends_on](#depends_on), so they determine the order of service startup. -> **Note**: If you define both links and [networks](#networks), services with +> **Note** +> +> If you define both links and [networks](#networks), services with > links between them must share at least one network in common in order to > communicate. @@ -382,7 +454,9 @@ Links also express dependency between services in the same way as Specify a log driver. The default is `json-file`. - log_driver: syslog +```yaml +log_driver: syslog +``` ### log_opt @@ -391,8 +465,10 @@ Specify a log driver. The default is `json-file`. Specify logging options as key-value pairs. An example of `syslog` options: - log_opt: - syslog-address: "tcp://192.168.0.42:123" +```yaml +log_opt: + syslog-address: "tcp://192.168.0.42:123" +``` ### net @@ -403,14 +479,27 @@ Network mode. Use the same values as the docker client `--net` parameter. The `container:...` form can take a service name instead of a container name or id. - net: "bridge" - net: "host" - net: "none" - net: "container:[service name or container name/id]" +```yaml +net: "bridge" +``` +```yaml +net: "host" +``` +```yaml +net: "none" +``` +```yaml +net: "service:[service name]" +``` +```yaml +net: "container:[container name/id]" +``` ### pid - pid: "host" +```yaml +pid: "host" +``` Sets the PID mode to the host PID mode. This turns on sharing between container and the host operating system the PID address space. Containers @@ -427,23 +516,28 @@ port (an ephemeral host port is chosen). > 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. - ports: - - "3000" - - "3000-3005" - - "8000:8000" - - "9090-9091:8080-8081" - - "49100:22" - - "127.0.0.1:8001:8001" - - "127.0.0.1:5000-5010:5000-5010" - - "6060:6060/udp" +```yaml +ports: + - "3000" + - "3000-3005" + - "8000:8000" + - "9090-9091:8080-8081" + - "49100:22" + - "127.0.0.1:8001:8001" + - "127.0.0.1:5000-5010:5000-5010" + - "6060:6060/udp" + - "12400-12500:1240" +``` ### security_opt Override the default labeling scheme for each container. - security_opt: - - label:user:USER - - label:role:ROLE +```yaml +security_opt: + - label:user:USER + - label:role:ROLE +``` ### stop_signal @@ -451,19 +545,22 @@ Sets an alternative signal to stop the container. By default `stop` uses SIGTERM. Setting an alternative signal using `stop_signal` causes `stop` to send that signal instead. - stop_signal: SIGUSR1 +```yaml +stop_signal: SIGUSR1 +``` ### ulimits Override the default ulimits for a container. You can either specify a single limit as an integer or soft/hard limits as a mapping. - - ulimits: - nproc: 65535 - nofile: - soft: 20000 - hard: 40000 +```yaml +ulimits: + nproc: 65535 + nofile: + soft: 20000 + hard: 40000 +``` ### volumes, volume\_driver @@ -478,35 +575,38 @@ 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 `..`. - volumes: - # Just specify a path and let the Engine create a volume - - /var/lib/mysql +```yaml +volumes: + # Just specify a path and let the Engine create a volume + - /var/lib/mysql - # Specify an absolute path mapping - - /opt/data:/var/lib/mysql + # Specify an absolute path mapping + - /opt/data:/var/lib/mysql - # Path on the host, relative to the Compose file - - ./cache:/tmp/cache + # Path on the host, relative to the Compose file + - ./cache:/tmp/cache - # User-relative path - - ~/configs:/etc/configs/:ro + # User-relative path + - ~/configs:/etc/configs/:ro - # Named volume - - datavolume:/var/lib/mysql + # Named volume + - datavolume:/var/lib/mysql +``` If you do not use a host path, you may specify a `volume_driver`. - volume_driver: mydriver +```yaml +volume_driver: mydriver +``` There are several things to note, depending on which [Compose file version](compose-versioning#versioning) you're using: -- For [version 1 files](compose-versioning#version-1), both named volumes and - container volumes use the specified driver. - -- No path expansion is done if you have also specified a `volume_driver`. - For example, if you specify a mapping of `./foo:/data`, the `./foo` part - is passed straight to the volume driver without being expanded. +- For [version 1 files](compose-versioning#version-1), both named volumes and + container volumes use the specified driver. +- No path expansion is done if you have also specified a `volume_driver`. + For example, if you specify a mapping of `./foo:/data`, the `./foo` part + is passed straight to the volume driver without being expanded. See [Docker Volumes](/engine/userguide/dockervolumes.md) and [Volume Plugins](/engine/extend/plugins_volume.md) for more information. @@ -517,44 +617,46 @@ Mount all of the volumes from another service or container, optionally specifying read-only access (``ro``) or read-write (``rw``). If no access level is specified, then read-write is used. - volumes_from: - - service_name - - service_name:ro +```yaml +volumes_from: + - service_name + - service_name:ro +``` ### cpu\_shares, cpu\_quota, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, privileged, read\_only, restart, shm\_size, stdin\_open, tty, user, working\_dir Each of these is a single value, analogous to its [docker run](/engine/reference/run.md) counterpart. - cpu_shares: 73 - cpu_quota: 50000 - cpuset: 0,1 +```yaml +cpu_shares: 73 +cpu_quota: 50000 +cpuset: 0,1 - user: postgresql - working_dir: /code +user: postgresql +working_dir: /code - domainname: foo.com - hostname: foo - ipc: host - mac_address: 02:42:ac:11:65:43 +domainname: foo.com +hostname: foo +ipc: host +mac_address: 02:42:ac:11:65:43 - mem_limit: 1000000000 - memswap_limit: 2000000000 - privileged: true +mem_limit: 1000000000 +memswap_limit: 2000000000 +privileged: true - restart: always +restart: always - read_only: true - shm_size: 64M - stdin_open: true - tty: true +read_only: true +shm_size: 64M +stdin_open: true +tty: true +``` ## Compose documentation - [User guide](/compose/index.md) -- [Installing Compose](/compose/install/) +- [Installing Compose](/compose/install.md) - [Compose file versions and upgrading](compose-versioning.md) -- [Get started with Django](/compose/django/) -- [Get started with Rails](/compose/rails/) -- [Get started with WordPress](/compose/wordpress/) +- [Samples](/samples/) - [Command line reference](/compose/reference/) diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index 9a01674cb5..38c71e5be0 100644 --- a/compose/compose-file/compose-file-v2.md +++ b/compose/compose-file/compose-file-v2.md @@ -14,7 +14,7 @@ These topics describe version 2 of the Compose file format. ## Compose and Docker compatibility matrix -There are several versions of the Compose file format – 1, 2, 2.x, and 3.x The +There are several versions of the Compose file format – 1, 2, 2.x, and 3.x. The 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)**. @@ -28,9 +28,10 @@ The Compose file is a [YAML](http://yaml.org/) file defining [volumes](#volume-configuration-reference). The default path for a Compose file is `./docker-compose.yml`. ->**Tip**: You can use either a `.yml` or `.yaml` extension for this file. They both work. +> **Tip**: You can use either a `.yml` or `.yaml` extension for this file. +> They both work. -A [container](/glossary.md#container) definition contains configuration which are applied to each +A service definition contains configuration that is applied to each container started for that service, much like passing command-line parameters to `docker run`. Likewise, network and volume definitions are analogous to `docker network create` and `docker volume create`. @@ -109,22 +110,36 @@ two keys: Configuration options that are applied at build time. `build` can be specified either as a string containing a path to the build -context, or an object with the path specified under [context](#context) and -optionally [dockerfile](#dockerfile) and [args](#args). +context: +```yaml +version: "{{ site.compose_file_v2 }}" +services: + webapp: build: ./dir +``` +Or, as an object with the path specified under [context](#context) and +optionally [Dockerfile](#dockerfile) and [args](#args): + +```yaml +version: "{{ site.compose_file_v2 }}" +services: + webapp: build: context: ./dir dockerfile: Dockerfile-alternate args: buildno: 1 +``` If you specify `image` as well as `build`, then Compose names the built image with the `webapp` and optional `tag` specified in `image`: - build: ./dir - image: webapp:tag +```yaml +build: ./dir +image: webapp:tag +``` This results in an image named `webapp` and tagged `tag`, built from `./dir`. @@ -134,11 +149,13 @@ This results in an image named `webapp` and tagged `tag`, built from `./dir`. A list of images that the engine uses for cache resolution. - build: - context: . - cache_from: - - alpine:latest - - corp/web_app:3.14 +```yaml +build: + context: . + cache_from: + - alpine:latest + - corp/web_app:3.14 +``` #### context @@ -151,10 +168,13 @@ When the value supplied is a relative path, it is interpreted as relative to the location of the Compose file. This directory is also the build context that is sent to the Docker daemon. -Compose builds and tags it with a generated name, and use that image thereafter. +Compose builds and tags it with a generated name, and uses that image +thereafter. - build: - context: ./dir +```yaml +build: + context: ./dir +``` #### dockerfile @@ -163,9 +183,11 @@ Alternate Dockerfile. Compose uses an alternate file to build with. A build path must also be specified. - build: - context: . - dockerfile: Dockerfile-alternate +```yaml +build: + context: . + dockerfile: Dockerfile-alternate +``` #### args @@ -176,37 +198,46 @@ build process. First, specify the arguments in your Dockerfile: - ARG buildno - ARG gitcommithash +```dockerfile +ARG buildno +ARG gitcommithash - RUN echo "Build number: $buildno" - RUN echo "Based on commit: $gitcommithash" +RUN echo "Build number: $buildno" +RUN echo "Based on commit: $gitcommithash" +``` Then specify the arguments under the `build` key. You can pass a mapping or a list: - build: - context: . - args: - buildno: 1 - gitcommithash: cdc3b19 +```yaml +build: + context: . + args: + buildno: 1 + gitcommithash: cdc3b19 +``` - build: - context: . - args: - - buildno=1 - - gitcommithash=cdc3b19 +```yaml +build: + context: . + args: + - buildno=1 + - gitcommithash=cdc3b19 +``` > **Note**: 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. 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. - args: - - buildno - - gitcommithash +```yaml +args: + - buildno + - gitcommithash +``` > **Note**: YAML boolean values (`true`, `false`, `yes`, `no`, `on`, `off`) must > be enclosed in quotes, so that the parser interprets them as strings. @@ -215,14 +246,18 @@ at build time is the value in the environment where Compose is running. Add hostname mappings at build-time. Use the same values as the docker client `--add-host` parameter. - extra_hosts: - - "somehost:162.242.195.82" - - "otherhost:50.31.209.229" +```yaml +extra_hosts: + - "somehost:162.242.195.82" + - "otherhost:50.31.209.229" +``` An entry with the ip address and hostname is created in `/etc/hosts` inside containers for this build, e.g: - 162.242.195.82 somehost - 50.31.209.229 otherhost +```console +162.242.195.82 somehost +50.31.209.229 otherhost +``` #### isolation @@ -244,23 +279,26 @@ to determine the value to use for builds. Add metadata to the resulting image using [Docker labels](/engine/userguide/labels-custom-metadata.md). You can use either an array or a dictionary. -It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with -those used by other software. +It's recommended that you use reverse-DNS notation to prevent your labels from +conflicting with those used by other software. - build: - context: . - labels: - com.example.description: "Accounting webapp" - com.example.department: "Finance" - com.example.label-with-empty-value: "" +```yaml +build: + context: . + labels: + com.example.description: "Accounting webapp" + com.example.department: "Finance" + com.example.label-with-empty-value: "" +``` - - build: - context: . - labels: - - "com.example.description=Accounting webapp" - - "com.example.department=Finance" - - "com.example.label-with-empty-value" +```yaml +build: + context: . + labels: + - "com.example.description=Accounting webapp" + - "com.example.department=Finance" + - "com.example.label-with-empty-value" +``` #### network @@ -269,14 +307,17 @@ those used by other software. Set the network containers connect to for the `RUN` instructions during build. - build: - context: . - network: host +```yaml +build: + context: . + network: host +``` - - build: - context: . - network: custom_network_1 +```yaml +build: + context: . + network: custom_network_1 +``` #### shm_size @@ -286,14 +327,17 @@ Set the size of the `/dev/shm` partition for this build's containers. Specify as an integer value representing the number of bytes or as a string expressing a [byte value](#specifying-byte-values). - build: - context: . - shm_size: '2gb' +```yaml +build: + context: . + shm_size: '2gb' +``` - - build: - context: . - shm_size: 10000000 +```yaml +build: + context: . + shm_size: 10000000 +``` #### target @@ -303,48 +347,60 @@ Build the specified stage as defined inside the `Dockerfile`. See the [multi-stage build docs](/engine/userguide/eng-image/multistage-build.md) for details. - build: - context: . - target: prod +```yaml +build: + context: . + target: prod +``` ### cap_add, cap_drop Add or drop container capabilities. See `man 7 capabilities` for a full list. - cap_add: - - ALL +```yaml +cap_add: + - ALL - cap_drop: - - NET_ADMIN - - SYS_ADMIN +cap_drop: + - NET_ADMIN + - SYS_ADMIN +``` ### command Override the default command. - command: bundle exec thin -p 3000 +```yaml +command: bundle exec thin -p 3000 +``` The command can also be a list, in a manner similar to [dockerfile](/engine/reference/builder.md#cmd): - command: ["bundle", "exec", "thin", "-p", "3000"] +```yaml +command: ["bundle", "exec", "thin", "-p", "3000"] +``` ### cgroup_parent Specify an optional parent cgroup for the container. - cgroup_parent: m-executor-abcd +```yaml +cgroup_parent: m-executor-abcd +``` ### container_name Specify a custom container name, rather than a generated default name. - container_name: my-web-container +```yaml +container_name: my-web-container +``` -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. +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. ### cpu_rt_runtime, cpu_rt_period @@ -352,13 +408,17 @@ results in an error. Configure CPU allocation parameters using the Docker daemon realtime scheduler. - cpu_rt_runtime: '400ms' - cpu_rt_period: '1400us' +```yaml +cpu_rt_runtime: '400ms' +cpu_rt_period: '1400us' +``` - # Integer values will use microseconds as units - cpu_rt_runtime: 95000 - cpu_rt_period: 11000 +Integer values will use microseconds as units: +```yaml +cpu_rt_runtime: 95000 +cpu_rt_period: 11000 +``` ### device_cgroup_rules @@ -366,44 +426,52 @@ Configure CPU allocation parameters using the Docker daemon realtime scheduler. Add rules to the cgroup allowed devices list. - device_cgroup_rules: - - 'c 1:3 mr' - - 'a 7:* rmw' +```yaml +device_cgroup_rules: + - 'c 1:3 mr' + - 'a 7:* rmw' +``` ### devices List of device mappings. Uses the same format as the `--device` docker client create option. - devices: - - "/dev/ttyUSB0:/dev/ttyUSB0" +```yaml +devices: + - "/dev/ttyUSB0:/dev/ttyUSB0" +``` ### depends_on > [Version 2 file format](compose-versioning.md#version-2) and up. -Express dependency between services, which has two effects: +Express dependency between services. Service dependencies cause the following +behaviors: - `docker-compose up` starts services in dependency order. In the following example, `db` and `redis` are started before `web`. - -- `docker-compose up SERVICE` automatically include `SERVICE`'s - dependencies. In the following example, `docker-compose up web` also - create and start `db` and `redis`. +- `docker-compose up SERVICE` automatically includes `SERVICE`'s + dependencies. In the example below, `docker-compose up web` also + creates and starts `db` and `redis`. +- `docker-compose stop` stops services in dependency order. In the following + example, `web` is stopped before `db` and `redis`. Simple example: - version: "{{ site.compose_file_v2 }}" - services: - web: - build: . - depends_on: - - db - - redis - redis: - image: redis - db: - image: postgres +```yaml +version: "{{ site.compose_file_v2 }}" +services: + web: + build: . + depends_on: + - db + - redis + redis: + image: redis + db: + image: postgres +``` > **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 @@ -418,21 +486,23 @@ the healthcheck) before starting. Example: - version: "{{ site.compose_file_v2 }}" - services: - web: - build: . - depends_on: - db: - condition: service_healthy - redis: - condition: service_started - redis: - image: redis +```yaml +version: "{{ site.compose_file_v2 }}" +services: + web: + build: . + depends_on: db: - image: redis - healthcheck: - test: "exit 0" + condition: service_healthy + redis: + condition: service_started + redis: + image: redis + db: + image: redis + healthcheck: + test: "exit 0" +``` In the above example, Compose waits for the `redis` service to be started (legacy behavior) and the `db` service to be healthy before starting `web`. @@ -444,53 +514,73 @@ information. Custom DNS servers. Can be a single value or a list. - dns: 8.8.8.8 - dns: - - 8.8.8.8 - - 9.9.9.9 +```yaml +dns: 8.8.8.8 +``` + +```yaml +dns: + - 8.8.8.8 + - 9.9.9.9 +``` ### dns_opt List of custom DNS options to be added to the container's `resolv.conf` file. - dns_opt: - - use-vc - - no-tld-query +```yaml +dns_opt: + - use-vc + - no-tld-query +``` ### dns_search Custom DNS search domains. Can be a single value or a list. - dns_search: example.com - dns_search: - - dc1.example.com - - dc2.example.com +```yaml +dns_search: example.com +``` + +```yaml +dns_search: + - dc1.example.com + - dc2.example.com +``` ### tmpfs Mount a temporary file system inside the container. Can be a single value or a list. - tmpfs: /run - tmpfs: - - /run - - /tmp +```yaml +tmpfs: /run +``` +```yaml +tmpfs: + - /run + - /tmp +``` ### entrypoint Override the default entrypoint. - entrypoint: /code/entrypoint.sh +```yaml +entrypoint: /code/entrypoint.sh +``` The entrypoint can also be a list, in a manner similar to [dockerfile](/engine/reference/builder.md#entrypoint): - entrypoint: - - php - - -d - - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so - - -d - - memory_limit=-1 - - vendor/bin/phpunit +```yaml +entrypoint: + - php + - -d + - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so + - -d + - memory_limit=-1 + - vendor/bin/phpunit +``` > **Note**: Setting `entrypoint` both overrides any default entrypoint set > on the service's image with the `ENTRYPOINT` Dockerfile instruction, *and* @@ -508,19 +598,25 @@ Environment variables declared in the [environment](#environment) section _override_ these values – this holds true even if those values are empty or undefined. - env_file: .env +```yaml +env_file: .env +``` - env_file: - - ./common.env - - ./apps/web.env - - /opt/secrets.env +```yaml +env_file: + - ./common.env + - ./apps/web.env + - /opt/runtime_opts.env +``` Compose expects each line in an env file to be in `VAR=VAL` format. Lines -beginning with `#` are processed as comments and are ignored. Blank lines are +beginning with `#` are treated as comments and are ignored. Blank lines are also ignored. - # Set Rails/Rack environment - RACK_ENV=development +```console +# Set Rails/Rack environment +RACK_ENV=development +``` > **Note**: If your service specifies a [build](#build) option, variables > defined in environment files are _not_ automatically visible during the @@ -548,38 +644,42 @@ services: And the following files: -```none +```console # a.env VAR=1 ``` and -```none +```console # b.env VAR=hello ``` -$VAR is `hello`. +`$VAR` is `hello`. ### environment Add environment variables. You can use either an array or a dictionary. Any -boolean values; true, false, yes no, need to be enclosed in quotes to ensure +boolean values (true, false, yes, no) need to be enclosed in quotes to ensure they are not converted to True or False by the YML parser. Environment variables with only a key are resolved to their values on the machine Compose is running on, which can be helpful for secret or host-specific values. - environment: - RACK_ENV: development - SHOW: 'true' - SESSION_SECRET: +```yaml +environment: + RACK_ENV: development + SHOW: 'true' + SESSION_SECRET: +``` - environment: - - RACK_ENV=development - - SHOW=true - - SESSION_SECRET +```yaml +environment: + - RACK_ENV=development + - SHOW=true + - SESSION_SECRET +``` > **Note**: If your service specifies a [build](#build) option, variables > defined in `environment` are _not_ automatically visible during the @@ -591,9 +691,11 @@ machine Compose is running on, which can be helpful for secret or host-specific Expose ports without publishing them to the host machine - they'll only be accessible to linked services. Only the internal port can be specified. - expose: - - "3000" - - "8000" +```yaml +expose: + - "3000" + - "8000" +``` ### extends @@ -604,9 +706,11 @@ You can use `extends` on any service together with other configuration keys. The `extends` value must be a dictionary defined with a required `service` and an optional `file` key. - extends: - file: common.yml - service: webapp +```yaml +extends: + file: common.yml + service: webapp +``` The `service` the name of the service being extended, for example `web` or `database`. The `file` is the location of a Compose configuration @@ -626,32 +730,44 @@ For more on `extends`, see the ### external_links -Link to containers started outside this `docker-compose.yml` or even outside -of Compose, especially for containers that provide shared or common services. -`external_links` follow semantics similar to `links` when specifying both the -container name and the link alias (`CONTAINER:ALIAS`). +Link to containers started outside this `docker-compose.yml` or even outside of +Compose, especially for containers that provide shared or common services. +`external_links` follow semantics similar to the legacy option `links` when +specifying both the container name and the link alias (`CONTAINER:ALIAS`). - external_links: - - redis_1 - - project_db_1:mysql - - project_db_1:postgresql +```yaml +external_links: + - redis_1 + - project_db_1:mysql + - project_db_1:postgresql +``` -> **Note**: For version 2 file format, the -> externally-created containers must be connected to at least one of the same -> networks as the service which is linking to them. +> **Notes:** +> +> 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 Add hostname mappings. Use the same values as the docker client `--add-host` parameter. - extra_hosts: - - "somehost:162.242.195.82" - - "otherhost:50.31.209.229" +```yaml +extra_hosts: + - "somehost:162.242.195.82" + - "otherhost:50.31.209.229" +``` An entry with the ip address and hostname is created in `/etc/hosts` inside containers for this service, e.g: - 162.242.195.82 somehost - 50.31.209.229 otherhost +```console +162.242.195.82 somehost +50.31.209.229 otherhost +``` ### group_add @@ -666,7 +782,7 @@ details. A full example: -``` +```yaml version: "{{ site.compose_file_v2 }}" services: myservice: @@ -688,46 +804,68 @@ service are "healthy". See the docs for the [HEALTHCHECK Dockerfile instruction](/engine/reference/builder.md#healthcheck) for details on how healthchecks work. - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost"] - interval: 1m30s - timeout: 10s - retries: 3 - start_period: 40s +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost"] + interval: 1m30s + timeout: 10s + retries: 3 + start_period: 40s +``` `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. + `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 specifying `CMD-SHELL` followed by that string. - # Hit the local web app - test: ["CMD", "curl", "-f", "http://localhost"] +```yaml +# Hit the local web app +test: ["CMD", "curl", "-f", "http://localhost"] +``` - # As above, but wrapped in /bin/sh. Both forms below are equivalent. - test: ["CMD-SHELL", "curl -f http://localhost && echo 'cool, it works'"] - test: curl -f https://localhost && echo 'cool, it works' +As above, but wrapped in `/bin/sh`. Both forms below are equivalent. -To disable any default healthcheck set by the image, you can use `disable: -true`. This is equivalent to specifying `test: ["NONE"]`. +```yaml +test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] +``` - healthcheck: - disable: true +```yaml +test: curl -f https://localhost || exit 1 +``` -> **Note**: The `start_period` option is a more recent feature and is only -> available with the [2.3 file format](compose-versioning.md#version-23). +To disable any default healthcheck set by the image, you can use `disable: true`. +This is equivalent to specifying `test: ["NONE"]`. + +```yaml +healthcheck: + disable: true +``` ### image Specify the image to start the container from. Can either be a repository/tag or a partial image ID. - image: redis - image: ubuntu:14.04 - image: tutum/influxdb - image: example-registry.com:4000/postgresql - image: a4bc65fd +```yaml +image: redis +``` +```yaml +image: ubuntu:18.04 +``` +```yaml +image: tutum/influxdb +``` +```yaml +image: example-registry.com:4000/postgresql +``` +```yaml +image: a4bc65fd +``` If the image does not exist, Compose attempts to pull it, unless you have also specified [build](#build), in which case it builds it using the specified @@ -740,18 +878,19 @@ options and tags it with the specified tag. Run an init inside the container that forwards signals and reaps processes. Set this option to `true` to enable this feature for the service. - version: "{{ site.compose_file_v2 }}" - services: - web: - image: alpine:latest - init: true +```yaml +version: "{{ site.compose_file_v2 }}" +services: + web: + image: alpine:latest + init: true +``` > 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](/engine/reference/commandline/dockerd/#daemon-configuration-file). - ### isolation > [Added in version 2.1 file format](compose-versioning.md#version-21). @@ -768,15 +907,19 @@ Add metadata to containers using [Docker labels](/engine/userguide/labels-custom It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software. - labels: - com.example.description: "Accounting webapp" - com.example.department: "Finance" - com.example.label-with-empty-value: "" +```yaml +labels: + com.example.description: "Accounting webapp" + com.example.department: "Finance" + com.example.label-with-empty-value: "" +``` - labels: - - "com.example.description=Accounting webapp" - - "com.example.department=Finance" - - "com.example.label-with-empty-value" +```yaml +labels: + - "com.example.description=Accounting webapp" + - "com.example.department=Finance" + - "com.example.label-with-empty-value" +``` ### links @@ -786,31 +929,40 @@ a link alias (`"SERVICE:ALIAS"`), or just the service name. > Links are a legacy option. We recommend using > [networks](#networks) instead. - web: - links: - - "db" - - "db:database" - - "redis" +```yaml +web: + links: + - "db" + - "db:database" + - "redis" +``` Containers for the linked service are reachable at a hostname identical to 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](/compose/networking.md#links).) + Links also express dependency between services in the same way as [depends_on](#depends_on), so they determine the order of service startup. -> **Note**: If you define both links and [networks](#networks), services with -> links between them must share at least one network in common in order to +> **Note** +> +> If you define both links and [networks](#networks), services with +> links between them must share at least one network in common to > communicate. We recommend using networks instead. ### logging - Logging configuration for the service. - logging: - driver: syslog - options: - syslog-address: "tcp://192.168.0.42:123" +```yaml +logging: + driver: syslog + options: + syslog-address: "tcp://192.168.0.42:123" +``` The `driver` name specifies a logging driver for the service's containers, as with the ``--log-driver`` option for docker run @@ -818,34 +970,52 @@ containers, as with the ``--log-driver`` option for docker run The default value is json-file. - driver: "json-file" - driver: "syslog" - driver: "none" +```yaml +driver: "json-file" +``` +```yaml +driver: "syslog" +``` +```yaml +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`. Logging options are key-value pairs. An example of `syslog` options: - driver: "syslog" - options: - syslog-address: "tcp://192.168.0.42:123" +```yaml +driver: "syslog" +options: + syslog-address: "tcp://192.168.0.42:123" +``` ### network_mode > [Version 2 file format](compose-versioning.md#version-2) and up. Replaces the version 1 [net](compose-file-v1.md#net) option. -Network mode. Use the same values as the docker client `--net` parameter, plus +Network mode. Use the same values as the docker client `--network` parameter, plus the special form `service:[service name]`. - network_mode: "bridge" - network_mode: "host" - network_mode: "none" - network_mode: "service:[service name]" - network_mode: "container:[container name/id]" +```yaml +net: "bridge" +``` +```yaml +net: "host" +``` +```yaml +net: "none" +``` +```yaml +net: "service:[service name]" +``` +```yaml +net: "container:[container name/id]" +``` ### networks @@ -854,11 +1024,13 @@ the special form `service:[service name]`. Networks to join, referencing entries under the [top-level `networks` key](#network-configuration-reference). - services: - some-service: - networks: - - some-network - - other-network +```yaml +services: + some-service: + networks: + - some-network + - other-network +``` #### aliases @@ -870,76 +1042,89 @@ Since `aliases` is network-scoped, the same service can have different aliases o The general format is shown here. - services: - some-service: - networks: - some-network: - aliases: - - alias1 - - alias3 - other-network: - aliases: - - alias2 +```yaml +services: + some-service: + networks: + some-network: + aliases: + - alias1 + - alias3 + other-network: + aliases: + - alias2 +``` -In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the `legacy` network. +In the example below, three services are provided (`web`, `worker`, and `db`), +along with two networks (`new` and `legacy`). The `db` service is reachable at +the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on +the `legacy` network. - version: "{{ site.compose_file_v2 }}" +```yaml +version: "{{ site.compose_file_v2 }}" - services: - web: - build: ./web - networks: - - new +services: + web: + image: "nginx:alpine" + networks: + - new - worker: - build: ./worker - networks: - - legacy - - db: - image: mysql - networks: - new: - aliases: - - database - legacy: - aliases: - - mysql + worker: + image: "my-worker-image:latest" + networks: + - legacy + db: + image: mysql networks: new: + aliases: + - database legacy: + aliases: + - mysql + +networks: + new: + legacy: +``` #### ipv4_address, ipv6_address Specify a static IP address for containers for this service when joining the network. -The corresponding network configuration in the [top-level networks section](#network-configuration-reference) must have an `ipam` block with subnet and gateway configurations covering each static address. If IPv6 addressing is desired, the [`enable_ipv6`](#enableipv6) option must be set. +The corresponding network configuration in the +[top-level networks section](#network-configuration-reference) must have an +`ipam` block with subnet and gateway configurations covering each static address. + +> If IPv6 addressing is desired, the [`enable_ipv6`](#enableipv6) option must be set. An example: - version: "{{ site.compose_file_v2 }}" - - services: - app: - image: busybox - command: ifconfig - networks: - app_net: - ipv4_address: 172.16.238.10 - ipv6_address: 2001:3984:3989::10 +```yaml +version: "{{ site.compose_file_v2 }}" +services: + app: + image: busybox + command: ifconfig networks: app_net: - driver: bridge - enable_ipv6: true - ipam: - driver: default - config: - - subnet: 172.16.238.0/24 - gateway: 172.16.238.1 - - subnet: 2001:3984:3989::/64 - gateway: 2001:3984:3989::1 + ipv4_address: 172.16.238.10 + ipv6_address: 2001:3984:3989::10 + +networks: + app_net: + driver: bridge + enable_ipv6: true + ipam: + driver: default + config: + - subnet: 172.16.238.0/24 + gateway: 172.16.238.1 + - subnet: 2001:3984:3989::/64 + gateway: 2001:3984:3989::1 +``` #### link_local_ips @@ -952,19 +1137,21 @@ managed by docker (IPAM driver). Example usage: - version: "{{ site.compose_file_v2 }}" - services: - app: - image: busybox - command: top - networks: - app_net: - link_local_ips: - - 57.123.22.11 - - 57.123.22.13 +```yaml +version: "{{ site.compose_file_v2 }}" +services: + app: + image: busybox + command: top networks: app_net: - driver: bridge + link_local_ips: + - 57.123.22.11 + - 57.123.22.13 +networks: + app_net: + driver: bridge +``` #### priority @@ -975,31 +1162,39 @@ In the following example, the `app` service connects to `app_net_1` first as it has the highest priority. It then connects to `app_net_3`, then `app_net_2`, which uses the default priority value of `0`. - version: "{{ site.compose_file_v2 }}" - services: - app: - image: busybox - command: top - networks: - app_net_1: - priority: 1000 - app_net_2: - - app_net_3: - priority: 100 +```yaml +version: "{{ site.compose_file_v2 }}" +services: + app: + image: busybox + command: top networks: app_net_1: + priority: 1000 app_net_2: + app_net_3: + priority: 100 +networks: + app_net_1: + app_net_2: + app_net_3: +``` > **Note**: If multiple networks have the same priority, the connection order > is undefined. ### pid - pid: "host" - pid: "container:custom_container_1" - pid: "service:foobar" +```yaml +pid: "host" +``` +```yaml +pid: "container:custom_container_1" +``` +```yaml +pid: "service:foobar" +``` If set to one of the following forms: `container:`, `service:`, the service shares the PID address space of the @@ -1019,8 +1214,9 @@ other containers in the bare-metal machine's namespace and vice versa. Tunes a container's PIDs limit. Set to `-1` for unlimited PIDs. - pids_limit: 10 - +```yaml +pids_limit: 10 +``` ### platform @@ -1029,9 +1225,15 @@ Tunes a container's PIDs limit. Set to `-1` for unlimited PIDs. Target platform containers for this service will run on, using the `os[/arch[/variant]]` syntax, e.g. - platform: osx - platform: windows/amd64 - platform: linux/arm64/v8 +```yaml +platform: osx +``` +```yaml +platform: windows/amd64 +``` +```yaml +platform: linux/arm64/v8 +``` This parameter determines which version of the image will be pulled and/or on which platform the service's build will be performed. @@ -1046,16 +1248,18 @@ port (an ephemeral host port is chosen). > 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. - ports: - - "3000" - - "3000-3005" - - "8000:8000" - - "9090-9091:8080-8081" - - "49100:22" - - "127.0.0.1:8001:8001" - - "127.0.0.1:5000-5010:5000-5010" - - "6060:6060/udp" - - "12400-12500:1240" +```yaml +ports: + - "3000" + - "3000-3005" + - "8000:8000" + - "9090-9091:8080-8081" + - "49100:22" + - "127.0.0.1:8001:8001" + - "127.0.0.1:5000-5010:5000-5010" + - "6060:6060/udp" + - "12400-12500:1240" +``` ### runtime @@ -1064,11 +1268,12 @@ port (an ephemeral host port is chosen). Specify which runtime to use for the service's containers. Default runtime and available runtimes are listed in the output of `docker info`. - web: - image: busybox:latest - command: true - runtime: runc - +```yaml +web: + image: busybox:latest + command: true + runtime: runc +``` ### scale @@ -1079,18 +1284,22 @@ you run `docker-compose up`, Compose creates or removes containers to match the specified number. This value can be overridden using the [`--scale`](/compose/reference/up.md) flag. - web: - image: busybox:latest - command: echo 'scaled' - scale: 3 +```yaml +web: + image: busybox:latest + command: echo 'scaled' + scale: 3 +``` ### security_opt Override the default labeling scheme for each container. - security_opt: - - label:user:USER - - label:role:ROLE +```yaml +security_opt: + - label:user:USER + - label:role:ROLE +``` ### stop_grace_period @@ -1099,8 +1308,13 @@ handle SIGTERM (or whatever stop signal has been specified with [`stop_signal`](#stopsignal)), before sending SIGKILL. Specified as a [duration](#specifying-durations). - stop_grace_period: 1s - stop_grace_period: 1m30s +```yaml +stop_grace_period: 1s +``` + +```yaml +stop_grace_period: 1m30s +``` By default, `stop` waits 10 seconds for the container to exit before sending SIGKILL. @@ -1111,7 +1325,9 @@ Sets an alternative signal to stop the container. By default `stop` uses SIGTERM. Setting an alternative signal using `stop_signal` causes `stop` to send that signal instead. - stop_signal: SIGUSR1 +```yaml +stop_signal: SIGUSR1 +``` ### storage_opt @@ -1119,8 +1335,10 @@ SIGTERM. Setting an alternative signal using `stop_signal` causes Set storage driver options for this service. - storage_opt: - size: '1G' +```yaml +storage_opt: + size: '1G' +``` ### sysctls @@ -1129,31 +1347,38 @@ Set storage driver options for this service. Kernel parameters to set in the container. You can use either an array or a dictionary. - sysctls: - net.core.somaxconn: 1024 - net.ipv4.tcp_syncookies: 0 +```yaml +sysctls: + net.core.somaxconn: 1024 + net.ipv4.tcp_syncookies: 0 +``` - sysctls: - - net.core.somaxconn=1024 - - net.ipv4.tcp_syncookies=0 +```yaml +sysctls: + - net.core.somaxconn=1024 + - net.ipv4.tcp_syncookies=0 +``` ### ulimits Override the default ulimits for a container. You can either specify a single limit as an integer or soft/hard limits as a mapping. - - ulimits: - nproc: 65535 - nofile: - soft: 20000 - hard: 40000 +```yaml +ulimits: + nproc: 65535 + nofile: + soft: 20000 + hard: 40000 +``` ### userns_mode > [Added in version 2.1 file format](compose-versioning.md#version-21). - userns_mode: "host" +```yaml +userns_mode: "host" +``` Disables the user namespace for this service, if Docker daemon is configured with user namespaces. See [dockerd](/engine/reference/commandline/dockerd.md#disable-user-namespace-for-a-container) for @@ -1161,7 +1386,7 @@ more information. ### volumes -Mount host folders or named volumes. Named volumes need to be specified with the +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 @@ -1175,21 +1400,23 @@ 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). - volumes: - # Just specify a path and let the Engine create a volume - - /var/lib/mysql +```yaml +volumes: + # Just specify a path and let the Engine create a volume + - /var/lib/mysql - # Specify an absolute path mapping - - /opt/data:/var/lib/mysql + # Specify an absolute path mapping + - /opt/data:/var/lib/mysql - # Path on the host, relative to the Compose file - - ./cache:/tmp/cache + # Path on the host, relative to the Compose file + - ./cache:/tmp/cache - # User-relative path - - ~/configs:/etc/configs/:ro + # User-relative path + - ~/configs:/etc/configs/:ro - # Named volume - - datavolume:/var/lib/mysql + # Named volume + - datavolume:/var/lib/mysql +``` #### Long syntax @@ -1213,7 +1440,7 @@ expressed in the short form. - `size`: the size for the tmpfs mount in bytes -```none +```yaml version: "{{ site.compose_file_v2 }}" services: web: @@ -1248,7 +1475,9 @@ volumes: Specify a default volume driver to be used for all declared volumes on this service. - volume_driver: mydriver +```yaml +volume_driver: mydriver +``` > **Note**: In [version 2 files](compose-versioning.md#version-2), this > option only applies to anonymous volumes (those specified in the image, @@ -1263,14 +1492,16 @@ See [Docker Volumes](/engine/userguide/dockervolumes.md) and ### volumes_from Mount all of the volumes from another service or container, optionally -specifying read-only access (``ro``) or read-write (``rw``). If no access level is specified, -then read-write is used. +specifying read-only access (``ro``) or read-write (``rw``). If no access level +is specified, then read-write is used. - volumes_from: - - service_name - - service_name:ro - - container:container_name - - container:container_name:rw +```yaml +volumes_from: + - service_name + - service_name:ro + - container:container_name + - container:container_name:rw +``` > **Notes** > @@ -1289,10 +1520,18 @@ then read-write is used. `no` is the default restart policy, and it doesn't restart a container under any circumstance. When `always` is specified, the container always restarts. The `on-failure` policy restarts a container if the exit code indicates an on-failure error. - - restart: no - - restart: always - - restart: on-failure - - restart: unless-stopped +```yaml +restart: no +``` +```yaml +restart: always +``` +```yaml +restart: on-failure +``` +```yaml +restart: unless-stopped +``` {: id="cpu-and-other-resources"} @@ -1306,34 +1545,36 @@ Each of these is a single value, analogous to its > The following options were added in [version 2.1](compose-versioning.md#version-21): > `oom_kill_disable`, `cpu_period` - cpu_count: 2 - cpu_percent: 50 - cpus: 0.5 - cpu_shares: 73 - cpu_quota: 50000 - cpu_period: 20ms - cpuset: 0,1 +```yaml +cpu_count: 2 +cpu_percent: 50 +cpus: 0.5 +cpu_shares: 73 +cpu_quota: 50000 +cpu_period: 20ms +cpuset: 0,1 - user: postgresql - working_dir: /code +user: postgresql +working_dir: /code - domainname: foo.com - hostname: foo - ipc: host - mac_address: 02:42:ac:11:65:43 +domainname: foo.com +hostname: foo +ipc: host +mac_address: 02:42:ac:11:65:43 - mem_limit: 1000000000 - memswap_limit: 2000000000 - mem_reservation: 512m - privileged: true +mem_limit: 1000000000 +memswap_limit: 2000000000 +mem_reservation: 512m +privileged: true - oom_score_adj: 500 - oom_kill_disable: true +oom_score_adj: 500 +oom_kill_disable: true - read_only: true - shm_size: 64M - stdin_open: true - tty: true +read_only: true +shm_size: 64M +stdin_open: true +tty: true +``` {: id="orig-resources" } @@ -1368,31 +1609,36 @@ The supported units are `b`, `k`, `m` and `g`, and their alternative notation `k ## Volume configuration reference -While it is possible to declare volumes on the fly as part of the service -declaration, this section allows you to create named volumes that can be +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](/engine/reference/commandline/volume_create.md) subcommand documentation for more information. +See [use volumes](/engine/admin/volumes/volumes.md) and [volume +plugins](/engine/extend/plugins_volume.md) for general information on volumes. + Here's an example of a two-service setup where a database's data directory is shared with another service as a volume so that it can be periodically backed up: - version: "{{ site.compose_file_v2 }}" - - services: - db: - image: db - volumes: - - data-volume:/var/lib/db - backup: - image: backup-service - volumes: - - data-volume:/var/lib/backup/data +```yaml +version: "{{ site.compose_file_v2 }}" +services: + db: + image: db volumes: - data-volume: + - data-volume:/var/lib/db + backup: + image: backup-service + volumes: + - data-volume:/var/lib/backup/data + +volumes: + data-volume: +``` An entry under the top-level `volumes` key can be empty, in which case it uses the default driver configured by the Engine (in most cases, this is the @@ -1405,7 +1651,9 @@ driver the Docker Engine has been configured to use, which in most cases is `local`. If the driver is not available, the Engine returns an error when `docker-compose up` tries to create the volume. - driver: foobar +```yaml +driver: foobar +``` ### driver_opts @@ -1413,9 +1661,14 @@ Specify a list of options as key-value pairs to pass to the driver for this volume. Those options are driver-dependent - consult the driver's documentation for more information. Optional. - driver_opts: - foo: "bar" - baz: 1 +```yaml +volumes: + example: + driver_opts: + type: "nfs" + o: "addr=10.40.0.199,nolock,soft,rw" + device: ":/docker/example" +``` ### external @@ -1432,25 +1685,29 @@ In the example below, instead of attempting to create a volume called `[projectname]_data`, Compose looks for an existing volume simply called `data` and mount it into the `db` service's containers. - version: "{{ site.compose_file_v2 }}" - - services: - db: - image: postgres - volumes: - - data:/var/lib/postgresql/data +```yaml +version: "{{ site.compose_file_v2 }}" +services: + db: + image: postgres volumes: - data: - external: true + - data:/var/lib/postgresql/data + +volumes: + data: + external: true +``` You can also specify the name of the volume separately from the name used to refer to it within the Compose file: - volumes: - data: - external: - name: actual-name-of-volume +```yaml +volumes: + data: + external: + 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. @@ -1466,35 +1723,44 @@ 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. - labels: - com.example.description: "Database volume" - com.example.department: "IT/Ops" - com.example.label-with-empty-value: "" - - labels: - - "com.example.description=Database volume" - - "com.example.department=IT/Ops" - - "com.example.label-with-empty-value" +```yaml +labels: + com.example.description: "Database volume" + com.example.department: "IT/Ops" + com.example.label-with-empty-value: "" +``` +```yaml +labels: + - "com.example.description=Database volume" + - "com.example.department=IT/Ops" + - "com.example.label-with-empty-value" +``` ### name > [Added in version 2.1 file format](compose-versioning.md#version-21) -Set a custom name for this volume. +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 +and will **not** be scoped with the stack name. - version: "{{ site.compose_file_v2 }}" - volumes: - data: - name: my-app-data +```yaml +version: "{{ site.compose_file_v2 }}" +volumes: + data: + name: my-app-data +``` It can also be used in conjunction with the `external` property: - version: "{{ site.compose_file_v2 }}" - volumes: - data: - external: true - name: my-app-data +```yaml +version: "{{ site.compose_file_v2 }}" +volumes: + data: + external: true + name: my-app-data +``` ## Network configuration reference @@ -1512,7 +1778,9 @@ Swarm. The Docker Engine returns an error if the driver is not available. - driver: overlay +```yaml +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 @@ -1524,9 +1792,11 @@ Specify a list of options as key-value pairs to pass to the driver for this network. Those options are driver-dependent - consult the driver's documentation for more information. Optional. - driver_opts: - foo: "bar" - baz: 1 +```yaml +driver_opts: + foo: "bar" + baz: 1 +``` ### enable_ipv6 @@ -1551,19 +1821,21 @@ which is optional: A full example: - ipam: - driver: default - config: - - subnet: 172.28.0.0/16 - ip_range: 172.28.5.0/24 - gateway: 172.28.5.254 - aux_addresses: - host1: 172.28.1.5 - host2: 172.28.1.6 - host3: 172.28.1.7 - options: - foo: bar - baz: "0" +```yaml +ipam: + driver: default + config: + - subnet: 172.28.0.0/16 + ip_range: 172.28.5.0/24 + gateway: 172.28.5.254 + aux_addresses: + host1: 172.28.1.5 + host2: 172.28.1.6 + host3: 172.28.1.7 + options: + foo: bar + baz: "0" +``` ### internal @@ -1582,15 +1854,19 @@ 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. - labels: - com.example.description: "Financial transaction network" - com.example.department: "Finance" - com.example.label-with-empty-value: "" +```yaml +labels: + com.example.description: "Financial transaction network" + com.example.department: "Finance" + com.example.label-with-empty-value: "" +``` - labels: - - "com.example.description=Financial transaction network" - - "com.example.department=Finance" - - "com.example.label-with-empty-value" +```yaml +labels: + - "com.example.description=Financial transaction network" + - "com.example.department=Finance" + - "com.example.label-with-empty-value" +``` ### external @@ -1608,31 +1884,35 @@ attempting to create a network called `[projectname]_outside`, Compose looks for an existing network simply called `outside` and connect the `proxy` service's containers to it. - version: "{{ site.compose_file_v2 }}" - - services: - proxy: - build: ./proxy - networks: - - outside - - default - app: - build: ./app - networks: - - default +```yaml +version: "{{ site.compose_file_v2 }}" +services: + proxy: + build: ./proxy networks: - outside: - external: true + - outside + - default + app: + build: ./app + networks: + - default + +networks: + outside: + external: true +``` You can also specify the name of the network separately from the name used to refer to it within the Compose file: - networks: - outside: - external: - name: actual-name-of-network - +```yaml +version: "{{ site.compose_file_v2 }}" +networks: + outside: + external: + name: actual-name-of-network +``` Not supported for version 2 `docker-compose` files. Use [network_mode](#network_mode) instead. @@ -1641,20 +1921,26 @@ Not supported for version 2 `docker-compose` files. Use > [Added in version 2.1 file format](compose-versioning.md#version-21) -Set a custom name for this network. +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 +and will **not** be scoped with the stack name. - version: "{{ site.compose_file_v2 }}" - networks: - network1: - name: my-app-net +```yaml +version: "{{ site.compose_file_v2 }}" +networks: + network1: + name: my-app-net +``` It can also be used in conjunction with the `external` property: - version: "{{ site.compose_file_v2 }}" - networks: - network1: - external: true - name: my-app-net +```yaml +version: "{{ site.compose_file_v2 }}" +networks: + network1: + external: true + name: my-app-net +``` ## Variable substitution @@ -1671,7 +1957,5 @@ It can also be used in conjunction with the `external` property: - [User guide](/compose/index.md) - [Installing Compose](/compose/install.md) - [Compose file versions and upgrading](compose-versioning.md) -- [Get started with Django](/compose/django.md) -- [Get started with Rails](/compose/rails.md) -- [Get started with WordPress](/compose/wordpress.md) +- [Samples](/samples/) - [Command line reference](/compose/reference/) diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 1684784f94..3ed29953d9 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -3,7 +3,7 @@ description: Compose file reference keywords: fig, composition, compose, docker redirect_from: - /compose/yml -- /compose/compose-file-v3.md +- /compose/compose-file-v3/ title: Compose file version 3 reference toc_max: 4 toc_min: 1 @@ -146,21 +146,21 @@ The Compose file is a [YAML](http://yaml.org/) file defining [volumes](#volume-configuration-reference). The default path for a Compose file is `./docker-compose.yml`. ->**Tip**: You can use either a `.yml` or `.yaml` extension for this file. -They both work. +> **Tip**: You can use either a `.yml` or `.yaml` extension for this file. +> They both work. A service definition contains configuration that is applied to each container started for that service, much like passing command-line parameters to -`docker container create`. Likewise, network and volume definitions are analogous to +`docker run`. Likewise, network and volume definitions are analogous to `docker network create` and `docker volume create`. -As with `docker container create`, options specified in the Dockerfile, such as `CMD`, +As with `docker run`, options specified in the Dockerfile, such as `CMD`, `EXPOSE`, `VOLUME`, `ENV`, are respected by default - you don't need to specify them again in `docker-compose.yml`. You can use environment variables in configuration values with a Bash-like -`${VARIABLE}` syntax - see -[variable substitution](#variable-substitution) for full details. +`${VARIABLE}` syntax - see [variable substitution](#variable-substitution) for +full details. This section contains a list of all configuration options supported by a service definition in version 3. @@ -243,7 +243,7 @@ build process. First, specify the arguments in your Dockerfile: -```Dockerfile +```dockerfile ARG buildno ARG gitcommithash @@ -289,7 +289,7 @@ args: #### cache_from -> **Note**: This option is new in v3.2 +> Added in [version 3.2](compose-versioning.md#version-32) file format A list of images that the engine uses for cache resolution. @@ -303,13 +303,13 @@ build: #### labels -> **Note**: This option is new in v3.3 +> Added in [version 3.3](compose-versioning.md#version-33) file format Add metadata to the resulting image using [Docker labels](/engine/userguide/labels-custom-metadata.md). You can use either an array or a dictionary. -We recommend that you use reverse-DNS notation to prevent your labels from conflicting with -those used by other software. +It's recommended that you use reverse-DNS notation to prevent your labels from +conflicting with those used by other software. ```yaml build: @@ -520,7 +520,8 @@ an error. ### 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. +> **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. 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 @@ -552,8 +553,9 @@ credential_spec: #### Example gMSA configuration When configuring a gMSA credential spec for a service, you only need to specify a credential spec with `config`, as shown in the following example: -``` -version: "3.8" + +```yaml +version: "{{ site.compose_file_v3 }}" services: myservice: image: myimage:latest @@ -567,16 +569,14 @@ configs: ### depends_on -Express dependency between services, Service dependencies cause the following +Express dependency between services. Service dependencies cause the following behaviors: - `docker-compose up` starts services in dependency order. In the following example, `db` and `redis` are started before `web`. - - `docker-compose up SERVICE` automatically includes `SERVICE`'s - dependencies. In the following example, `docker-compose up web` also + dependencies. In the example below, `docker-compose up web` also creates and starts `db` and `redis`. - - `docker-compose stop` stops services in dependency order. In the following example, `web` is stopped before `db` and `redis`. @@ -602,9 +602,7 @@ services: > 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. -> > - Version 3 no longer supports the `condition` form of `depends_on`. -> > - The `depends_on` option is ignored when > [deploying a stack in swarm mode](/engine/reference/commandline/stack_deploy.md) > with a version 3 Compose file. @@ -986,12 +984,12 @@ The entrypoint can also be a list, in a manner similar to ```yaml entrypoint: - - php - - -d - - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so - - -d - - memory_limit=-1 - - vendor/bin/phpunit + - php + - -d + - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so + - -d + - memory_limit=-1 + - vendor/bin/phpunit ``` > **Note**: Setting `entrypoint` both overrides any default entrypoint set @@ -1018,14 +1016,14 @@ env_file: .env env_file: - ./common.env - ./apps/web.env - - /opt/secrets.env + - /opt/runtime_opts.env ``` Compose expects each line in an env file to be in `VAR=VAL` format. Lines beginning with `#` are treated as comments and are ignored. Blank lines are also ignored. -```bash +```console # Set Rails/Rack environment RACK_ENV=development ``` @@ -1056,14 +1054,14 @@ services: And the following files: -```bash +```console # a.env VAR=1 ``` and -```bash +```console # b.env VAR=hello ``` @@ -1105,8 +1103,8 @@ accessible to linked services. Only the internal port can be specified. ```yaml expose: - - "3000" - - "8000" + - "3000" + - "8000" ``` ### external_links @@ -1118,20 +1116,20 @@ specifying both the container name and the link alias (`CONTAINER:ALIAS`). ```yaml external_links: - - redis_1 - - project_db_1:mysql - - project_db_1:postgresql + - redis_1 + - project_db_1:mysql + - project_db_1:postgresql ``` > **Notes:** > -> 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. +> 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. +> with a (version 3) Compose file. ### extra_hosts @@ -1139,13 +1137,13 @@ Add hostname mappings. Use the same values as the docker client `--add-host` par ```yaml extra_hosts: - - "somehost:162.242.195.82" - - "otherhost:50.31.209.229" + - "somehost:162.242.195.82" + - "otherhost:50.31.209.229" ``` An entry with the ip address and hostname is created in `/etc/hosts` inside containers for this service, e.g: -```none +```console 162.242.195.82 somehost 50.31.209.229 otherhost ``` @@ -1168,10 +1166,11 @@ healthcheck: start_period: 40s ``` -`interval`, `timeout` and `start_period` are specified as [durations](#specifying-durations). +`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. +> file format. `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 @@ -1192,8 +1191,8 @@ test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] test: curl -f https://localhost || exit 1 ``` -To disable any default healthcheck set by the image, you can use `disable: -true`. This is equivalent to specifying `test: ["NONE"]`. +To disable any default healthcheck set by the image, you can use `disable: true`. +This is equivalent to specifying `test: ["NONE"]`. ```yaml healthcheck: @@ -1205,11 +1204,21 @@ healthcheck: Specify the image to start the container from. Can either be a repository/tag or a partial image ID. - image: redis - image: ubuntu:14.04 - image: tutum/influxdb - image: example-registry.com:4000/postgresql - image: a4bc65fd +```yaml +image: redis +``` +```yaml +image: ubuntu:18.04 +``` +```yaml +image: tutum/influxdb +``` +```yaml +image: example-registry.com:4000/postgresql +``` +```yaml +image: a4bc65fd +``` If the image does not exist, Compose attempts to pull it, unless you have also specified [build](#build), in which case it builds it using the specified @@ -1276,14 +1285,14 @@ containers in a more controlled way. {:.warning} Link to containers in another service. Either specify both the service name and -a link alias (`SERVICE:ALIAS`), or just the service name. +a link alias (`"SERVICE:ALIAS"`), or just the service name. ```yaml web: links: - - db - - db:database - - redis + - "db" + - "db:database" + - "redis" ``` Containers for the linked service are reachable at a hostname identical to @@ -1299,12 +1308,11 @@ Links also express dependency between services in the same way as > **Notes** > > * 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. +> 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. ### logging @@ -1323,13 +1331,19 @@ containers, as with the ``--log-driver`` option for docker run The default value is json-file. - driver: "json-file" - driver: "syslog" - driver: "none" +```yaml +driver: "json-file" +``` +```yaml +driver: "syslog" +``` +```yaml +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`. @@ -1381,11 +1395,21 @@ For a full list of supported logging drivers and their options, see Network mode. Use the same values as the docker client `--network` parameter, plus the special form `service:[service name]`. - network_mode: "bridge" - network_mode: "host" - network_mode: "none" - network_mode: "service:[service name]" - network_mode: "container:[container name/id]" +```yaml +network_mode: "bridge" +``` +```yaml +network_mode: "host" +``` +```yaml +network_mode: "none" +``` +```yaml +network_mode: "service:[service name]" +``` +```yaml +network_mode: "container:[container name/id]" +``` > **Notes** > @@ -1425,11 +1449,11 @@ services: networks: some-network: aliases: - - alias1 - - alias3 + - alias1 + - alias3 other-network: aliases: - - alias2 + - alias2 ``` In the example below, three services are provided (`web`, `worker`, and `db`), @@ -1502,7 +1526,9 @@ networks: ### pid - pid: "host" +```yaml +pid: "host" +``` Sets the PID mode to the host PID mode. This turns on sharing between container and the host operating system the PID address space. Containers @@ -1527,14 +1553,15 @@ port (an ephemeral host port is chosen). ```yaml ports: - - "3000" - - "3000-3005" - - "8000:8000" - - "9090-9091:8080-8081" - - "49100:22" - - "127.0.0.1:8001:8001" - - "127.0.0.1:5000-5010:5000-5010" - - "6060:6060/udp" + - "3000" + - "3000-3005" + - "8000:8000" + - "9090-9091:8080-8081" + - "49100:22" + - "127.0.0.1:8001:8001" + - "127.0.0.1:5000-5010:5000-5010" + - "6060:6060/udp" + - "12400-12500:1240" ``` #### Long syntax @@ -1687,8 +1714,13 @@ handle SIGTERM (or whatever stop signal has been specified with [`stop_signal`](#stopsignal)), before sending SIGKILL. Specified as a [duration](#specifying-durations). - stop_grace_period: 1s - stop_grace_period: 1m30s +```yaml +stop_grace_period: 1s +``` + +```yaml +stop_grace_period: 1m30s +``` By default, `stop` waits 10 seconds for the container to exit before sending SIGKILL. @@ -1731,8 +1763,6 @@ parameters (sysctls) at runtime](/engine/reference/commandline/run/#configure-na ### tmpfs -> [Version 2 file format](compose-versioning.md#version-2) and up. - Mount a temporary file system inside the container. Can be a single value or a list. ```yaml @@ -1766,7 +1796,6 @@ of the tmpfs mount in bytes. Unlimited by default. Override the default ulimits for a container. You can either specify a single limit as an integer or soft/hard limits as a mapping. - ```yaml ulimits: nproc: 65535 @@ -1848,7 +1877,7 @@ volumes: Optionally specify a path on the host machine (`HOST:CONTAINER`), or an access mode (`HOST:CONTAINER:ro`). -You can mount a relative path on the host, that expands relative to +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 `..`. @@ -1888,7 +1917,9 @@ expressed in the short form. created - `tmpfs`: configure additional tmpfs options - `size`: the size for the tmpfs mount in bytes -- `consistency`: the consistency requirements of the mount, one of `consistent` (host and container have identical view), `cached` (read cache, host view is authoritative) or `delegated` (read-write cache, container's view is authoritative) +- `consistency`: the consistency requirements of the mount, one of `consistent` + (host and container have identical view), `cached` (read cache, host view is + authoritative) or `delegated` (read-write cache, container's view is authoritative) ```yaml version: "{{ site.compose_file_v3 }}" @@ -1954,23 +1985,19 @@ services: #### Caching options for volume mounts (Docker Desktop for Mac) -On Docker 17.04 CE Edge and up, including 17.06 CE Edge and Stable, you can -configure container-and-host consistency requirements for bind-mounted +You can configure container-and-host consistency requirements for bind-mounted directories in Compose files to allow for better performance on read/write of volume mounts. These options address issues specific to `osxfs` file sharing, and therefore are only applicable on Docker Desktop for Mac. The flags are: -* `consistent`: Full consistency. The container runtime and the -host maintain an identical view of the mount at all times. This is the default. - -* `cached`: The host's view of the mount is authoritative. There may be -delays before updates made on the host are visible within a container. - -* `delegated`: The container runtime's view of the mount is -authoritative. There may be delays before updates made in a container -are visible on the host. +* `consistent`: Full consistency. The container runtime and the host maintain an + identical view of the mount at all times. This is the default. +* `cached`: The host's view of the mount is authoritative. There may be delays + before updates made on the host are visible within a container. +* `delegated`: The container runtime's view of the mount is authoritative. There + may be delays before updates made in a container are visible on the host. Here is an example of configuring a volume as `cached`: @@ -2026,7 +2053,6 @@ format that looks like this: The supported units are `us`, `ms`, `s`, `m` and `h`. - ## Specifying byte values Some configuration options, such as the `shm_size` sub-option for @@ -2042,18 +2068,17 @@ that looks like this: The supported units are `b`, `k`, `m` and `g`, and their alternative notation `kb`, `mb` and `gb`. Decimal values are not supported at this time. - ## Volume configuration reference -While it is possible to declare [volumes](#volumes) on the file as part of the -service declaration, this section allows you to create named volumes (without -relying on `volumes_from`) that can be reused across multiple services, and are -easily retrieved and inspected using the docker command line or API. See the -[docker volume](/engine/reference/commandline/volume_create.md) subcommand -documentation for more information. +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](/engine/reference/commandline/volume_create.md) +subcommand documentation for more information. -See [Use volumes](/engine/admin/volumes/volumes.md) and [Volume -Plugins](/engine/extend/plugins_volume.md) for general information on volumes. +See [use volumes](/engine/admin/volumes/volumes.md) and [volume +plugins](/engine/extend/plugins_volume.md) for general information on volumes. Here's an example of a two-service setup where a database's data directory is shared with another service as a volume so that it can be periodically backed @@ -2212,12 +2237,10 @@ 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 and all -network driver options, see the [Networking guide](../networking.md). - + network driver options, see the [Networking guide](/compose/networking.md). * For [Docker Labs](https://github.com/docker/labs/blob/master/README.md) -tutorials on networking, start with [Designing Scalable, Portable Docker -Container -Networks](https://github.com/docker/labs/blob/master/networking/README.md) + tutorials on networking, start with [Designing Scalable, Portable Docker + Container Networks](https://github.com/docker/labs/blob/master/networking/README.md) ### driver @@ -2584,7 +2607,7 @@ stack. ## Compose documentation - [User guide](/compose/index.md) -- [Installing Compose](/compose/install/) +- [Installing Compose](/compose/install.md) - [Compose file versions and upgrading](compose-versioning.md) - [Samples](/samples/) - [Command line reference](/compose/reference/)