From 38620ab5890cea5e585edcdc076486a2d79478a1 Mon Sep 17 00:00:00 2001 From: Irfan Alam Date: Tue, 15 Mar 2022 13:06:53 +0530 Subject: [PATCH 01/17] POSTGRES_NAME should be POSTGRES_DB POSTGRES_NAME should be POSTGRES_DB for the db service --- samples/django.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/samples/django.md b/samples/django.md index 811e907a57..61c9a07777 100644 --- a/samples/django.md +++ b/samples/django.md @@ -76,7 +76,7 @@ and a `docker-compose.yml` file. (You can use either a `.yml` or `.yaml` extensi volumes: - ./data/db:/var/lib/postgresql/data environment: - - POSTGRES_NAME=postgres + - POSTGRES_DB=postgres - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres web: From fc9286930911e408be1a2606fad8323928eac828 Mon Sep 17 00:00:00 2001 From: SethuMK Date: Wed, 16 Mar 2022 09:33:19 -0500 Subject: [PATCH 02/17] missed & in the powershellcommand --- engine/install/binaries.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/engine/install/binaries.md b/engine/install/binaries.md index 9a5288e2fe..e910372545 100644 --- a/engine/install/binaries.md +++ b/engine/install/binaries.md @@ -224,7 +224,7 @@ To install server and client binaries, perform the following steps: 3. Register the service and start the Docker Engine: ```powershell - PS C:\> $Env:ProgramFiles\Docker\dockerd --register-service + PS C:\> &$Env:ProgramFiles\Docker\dockerd --register-service PS C:\> Start-Service docker ``` @@ -232,7 +232,7 @@ To install server and client binaries, perform the following steps: image. ```powershell - PS C:\> $Env:ProgramFiles\Docker\docker run hello-world:nanoserver + PS C:\> &$Env:ProgramFiles\Docker\docker run hello-world:nanoserver ``` This command downloads a test image and runs it in a container. When the From cd01954af984ba233d8e88e772b2af81f8d6ff62 Mon Sep 17 00:00:00 2001 From: Usha Mandya Date: Mon, 21 Mar 2022 12:04:20 +0000 Subject: [PATCH 03/17] Move Compose file ref to the legacy node Signed-off-by: Usha Mandya --- _data/toc.yaml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/_data/toc.yaml b/_data/toc.yaml index 477a51f559..f8bef9e5b3 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1040,14 +1040,16 @@ reference: section: - path: /compose/compose-file/ title: Compose Specification - - path: /compose/compose-file/compose-file-v3/ - title: Version 3 - - path: /compose/compose-file/compose-file-v2/ - title: Version 2 - path: /compose/compose-file/compose-versioning/ title: About versions and upgrading - path: /compose/faq/ title: Frequently asked questions + - sectiontitle: Legacy versions + section: + - path: /compose/compose-file/compose-file-v3/ + title: Version 3 + - path: /compose/compose-file/compose-file-v2/ + title: Version 2 - sectiontitle: Drivers and specifications section: - sectiontitle: Registry image manifests From 1d5af4b2b97fc88bd1ef73b4384ac941c05da17c Mon Sep 17 00:00:00 2001 From: Usha Mandya Date: Mon, 21 Mar 2022 12:07:21 +0000 Subject: [PATCH 04/17] Test: Add Compose spec details to the repo Signed-off-by: Usha Mandya --- compose/compose-file/index.md | 2483 ++++++++++++++++++++++++++++++++- 1 file changed, 2482 insertions(+), 1 deletion(-) diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index de284d7fd4..63c3f97ac6 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -2,7 +2,7 @@ description: Compose file reference keywords: fig, composition, compose, docker redirect_from: -- /compose/yml +- /compose/yaml - /compose/compose-file/compose-file-v1/ title: Compose file toc_max: 4 @@ -22,6 +22,2487 @@ how to upgrade, see **[About versions and upgrading](compose-versioning.md)**. {% include content/compose-matrix.md %} +## Status of this document + +This document specifies the Compose file format used to define multi-containers applications. Distribution of this document is unlimited. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +### Requirements and optional attributes + +The Compose specification includes properties designed to target a local [OCI](https://opencontainers.org/) container runtime, +exposing Linux kernel specific configuration options, but also some Windows container specific properties, as well as cloud platform features related to resource placement on a cluster, replicated application distribution and scalability. + +We acknowledge that no Compose implementation is expected to support **all** attributes, and that support for some properties +is Platform dependent and can only be confirmed at runtime. The definition of a versioned schema to control the supported +properties in a Compose file, established by the [docker-compose](https://github.com/docker/compose) tool where the Compose +file format was designed, doesn't offer any guarantee to the end-user attributes will be actually implemented. + +The specification defines the expected configuration syntax and behaviour, but - until noted - supporting any of those is OPTIONAL. + +A Compose implementation to parse a Compose file using unsupported attributes SHOULD warn user. We recommend implementors +to support those running modes: + +* default: warn user about unsupported attributes, but ignore them +* strict: warn user about unsupported attributes and reject the compose file +* loose: ignore unsupported attributes AND unknown attributes (that were not defined by the spec by the time implementation was created) + +## The Compose application model + +The Compose specification allows one to define a platform-agnostic container based application. Such an application is designed as a set of containers which have to both run together with adequate shared resources and communication channels. + +Computing components of an application are defined as [Services](#Services-top-level-element). A Service is an abstract concept implemented on platforms by running the same container image (and configuration) one or more times. + +Services communicate with each other through [Networks](#Networks-top-level-element). In this specification, a Network is a platform capability abstraction to establish an IP route between containers within services connected together. Low-level, platform-specific networking options are grouped into the Network definition and MAY be partially implemented on some platforms. + +Services store and share persistent data into [Volumes](#Volumes-top-level-element). The specification describes such a persistent data as a high-level filesystem mount with global options. Actual platform-specific implementation details are grouped into the Volumes definition and MAY be partially implemented on some platforms. + +Some services require configuration data that is dependent on the runtime or platform. For this, the specification defines a dedicated concept: [Configs](#Configs-top-level-element). From a Service container point of view, Configs are comparable to Volumes, in that they are files mounted into the container. But the actual definition involves distinct platform resources and services, which are abstracted by this type. + +A [Secret](#Secrets-top-level-element) is a specific flavour of configuration data for sensitive data that SHOULD NOT be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose specification. + +Distinction within Volumes, Configs and Secret allows implementations to offer a comparable abstraction at service level, but cover the specific configuration of adequate platform resources for well identified data usages. + +A **Project** is an individual deployment of an application specification on a platform. A project's name is used to group +resources together and isolate them from other applications or other installation of the same Compose specified application with distinct parameters. A Compose implementation creating resources on a platform MUST prefix resource names by project and +set the label `com.docker.compose.project`. + +Project name can be set explicitly by top-level `name` attribute. Compose implementation MUST offer a way for user to set a custom project name and override this name, so that the same `compose.yaml` file can be deployed twice on the same infrastructure, without changes, by just passing a distinct name. + +### Illustrative example + +The following example illustrates Compose specification concepts with a concrete example application. The example is non-normative. + +Consider an application split into a frontend web application and a backend service. + +The frontend is configured at runtime with an HTTP configuration file managed by infrastructure, providing an external domain name, and an HTTPS server certificate injected by the platform's secured secret store. + +The backend stores data in a persistent volume. + +Both services communicate with each other on an isolated back-tier network, while frontend is also connected to a front-tier network and exposes port 443 for external usage. + +``` +(External user) --> 443 [frontend network] + | + +--------------------+ + | frontend service |...ro... + | "webapp" |...ro... #secured + +--------------------+ + | + [backend network] + | + +--------------------+ + | backend service | r+w ___________________ + | "database" |=======( persistent volume ) + +--------------------+ \_________________/ +``` + +The example application is composed of the following parts: + +- 2 services, backed by Docker images: `webapp` and `database` +- 1 secret (HTTPS certificate), injected into the frontend +- 1 configuration (HTTP), injected into the frontend +- 1 persistent volume, attached to the backend +- 2 networks + +```yaml +services: + frontend: + image: awesome/webapp + ports: + - "443:8043" + networks: + - front-tier + - back-tier + configs: + - httpd-config + secrets: + - server-certificate + + backend: + image: awesome/database + volumes: + - db-data:/etc/data + networks: + - back-tier + +volumes: + db-data: + driver: flocker + driver_opts: + size: "10GiB" + +configs: + httpd-config: + external: true + +secrets: + server-certificate: + external: true + +networks: + # The presence of these objects is sufficient to define them + front-tier: {} + back-tier: {} +``` + +This example illustrates the distinction between volumes, configs and secrets. While all of them are all exposed +to service containers as mounted files or directories, only a volume can be configured for read+write access. +Secrets and configs are read-only. The volume configuration allows you to select a volume driver and pass driver options +to tweak volume management according to the actual infrastructure. Configs and Secrets rely on platform services, +and are declared `external` as they are not managed as part of the application lifecycle: the Compose implementation +will use a platform-specific lookup mechanism to retrieve runtime values. + +## Compose file + +The Compose file is a [YAML](http://yaml.org/) file defining +[version](#version-top-level-element) (DEPRECATED), +[services](#services-top-level-element) (REQUIRED), +[networks](#networks-top-level-element), +[volumes](#volumes-top-level-element), +[configs](#configs-top-level-element) and +[secrets](#secrets-top-level-element). +The default path for a Compose file is `compose.yaml` (preferred) or `compose.yml` in working directory. +Compose implementations SHOULD also support `docker-compose.yaml` and `docker-compose.yml` for backward compatibility. +If both files exist, Compose implementations MUST prefer canonical `compose.yaml` one. + +Multiple Compose files can be combined together to define the application model. The combination of YAML files +MUST be implemented by appending/overriding YAML elements based on Compose file order set by the user. Simple +attributes and maps get overridden by the highest order Compose file, lists get merged by appending. Relative +paths MUST be resolved based on the **first** Compose file's parent folder, whenever complimentary files being +merged are hosted in other folders. + +As some Compose file elements can both be expressed as single strings or complex objects, merges MUST apply to +the expanded form. + +### Profiles + +Profiles allow to adjust the Compose application model for various usages and environments. A Compose +implementation SHOULD allow the user to define a set of active profiles. The exact mechanism is implementation +specific and MAY include command line flags, environment variables, etc. + +The Services top-level element supports a `profiles` attribute to define a list of named profiles. Services without +a `profiles` attribute set MUST always be enabled. A service MUST be ignored by the Compose +implementation when none of the listed `profiles` match the active ones, unless the service is +explicitly targeted by a command. In that case its `profiles` MUST be added to the set of active profiles. +All other top-level elements are not affected by `profiles` and are always active. + +References to other services (by `links`, `extends` or shared resource syntax `service:xxx`) MUST not +automatically enable a component that would otherwise have been ignored by active profiles. Instead the +Compose implementation MUST return an error. + +#### Illustrative example + +```yaml +services: + foo: + image: foo + bar: + image: bar + profiles: + - test + baz: + image: baz + depends_on: + - bar + profiles: + - test + zot: + image: zot + depends_on: + - bar + profiles: + - debug +``` + +- Compose application model parsed with no profile enabled only contains the `foo` service. +- If profile `test` is enabled, model contains the services `bar` and `baz` which are enabled by the + `test` profile and service `foo` which is always enabled. +- If profile `debug` is enabled, model contains both `foo` and `zot` services, but not `bar` and `baz` + and as such the model is invalid regarding the `depends_on` constraint of `zot`. +- If profiles `debug` and `test` are enabled, model contains all services: `foo`, `bar`, `baz` and `zot`. +- If Compose implementation is executed with `bar` as explicit service to run, it and the `test` profile + will be active even if `test` profile is not enabled _by the user_. +- If Compose implementation is executed with `baz` as explicit service to run, the service `baz` and the + profile `test` will be active and `bar` will be pulled in by the `depends_on` constraint. +- If Compose implementation is executed with `zot` as explicit service to run, again the model will be + invalid regarding the `depends_on` constraint of `zot` since `zot` and `bar` have no common `profiles` + listed. +- If Compose implementation is executed with `zot` as explicit service to run and profile `test` enabled, + profile `debug` is automatically enabled and service `bar` is pulled in as a dependency starting both + services `zot` and `bar`. + +## Version top-level element + +Top-level `version` property is defined by the specification for backward compatibility but is only informative. + +A Compose implementation SHOULD NOT use this version to select an exact schema to validate the Compose file, but +prefer the most recent schema at the time it has been designed. + +Compose implementations SHOULD validate whether they can fully parse the Compose file. If some fields are unknown, typically +because the Compose file was written with fields defined by a newer version of the specification, Compose implementations +SHOULD warn the user. Compose implementations MAY offer options to ignore unknown fields (as defined by ["loose"](#Requirements-and-optional-attributes) mode). + +## Name top-level element + +Top-level `name` property is defined by the specification as project name to be used if user doesn't set one explicitly. +Compose implementations MUST offer a way for user to override this name, and SHOULD define a mechanism to compute a +default project name, to be used if the top-level `name` element is not set. + +Whenever project name is defined by top-level `name` or by some custom mechanism, it MUST be exposed for +[interpolation](#Interpolation) and environment variable resolution as `COMPOSE_PROJECT_NAME` + +```yaml +services: + foo: + image: busybox + environment: + - COMPOSE_PROJECT_NAME + command: echo "I'm running ${COMPOSE_PROJECT_NAME}" +``` + +## Services top-level element + +A Service is an abstract definition of a computing resource within an application which can be scaled/replaced +independently from other components. Services are backed by a set of containers, run by the platform +according to replication requirements and placement constraints. Being backed by containers, Services are defined +by a Docker image and set of runtime arguments. All containers within a service are identically created with these +arguments. + +A Compose file MUST declare a `services` root element as a map whose keys are string representations of service names, +and whose values are service definitions. A service definition contains the configuration that is applied to each +container started for that service. + +Each service MAY also include a Build section, which defines how to create the Docker image for the service. +Compose implementations MAY support building docker images using this service definition. If not implemented +the Build section SHOULD be ignored and the Compose file MUST still be considered valid. + +Build support is an OPTIONAL aspect of the Compose specification, and is described in detail [here](build.md) + +Each Service defines runtime constraints and requirements to run its containers. The `deploy` section groups +these constraints and allows the platform to adjust the deployment strategy to best match containers' needs with +available resources. + +Deploy support is an OPTIONAL aspect of the Compose specification, and is described in detail [here](deploy.md). If +not implemented the Deploy section SHOULD be ignored and the Compose file MUST still be considered valid. + + +### build + +`build` specifies the build configuration for creating container image from source, as defined [here](build.md). + + +### blkio_config + +`blkio_config` defines a set of configuration options to set block IO limits for this service. + +```yaml +services: + foo: + image: busybox + blkio_config: + weight: 300 + weight_device: + - path: /dev/sda + weight: 400 + device_read_bps: + - path: /dev/sdb + rate: '12mb' + device_read_iops: + - path: /dev/sdb + rate: 120 + device_write_bps: + - path: /dev/sdb + rate: '1024k' + device_write_iops: + - path: /dev/sdb + rate: 30 +``` + +#### device_read_bps, device_write_bps + +Set a limit in bytes per second for read / write operations on a given device. +Each item in the list MUST have two keys: + +- `path`: defining the symbolic path to the affected device. +- `rate`: either as an integer value representing the number of bytes or as a string expressing a byte value. + +#### device_read_iops, device_write_iops + +Set a limit in operations per second for read / write operations on a given device. +Each item in the list MUST have two keys: + +- `path`: defining the symbolic path to the affected device. +- `rate`: as an integer value representing the permitted number of operations per second. + +#### weight + +Modify the proportion of bandwidth allocated to this service relative to other services. +Takes an integer value between 10 and 1000, with 500 being the default. + +#### weight_device + +Fine-tune bandwidth allocation by device. Each item in the list must have two keys: + +- `path`: defining the symbolic path to the affected device. +- `weight`: an integer value between 10 and 1000. + +### cpu_count + +`cpu_count` defines the number of usable CPUs for service container. + +### cpu_percent + +`cpu_percent` defines the usable percentage of the available CPUs. + +### cpu_shares + +`cpu_shares` defines (as integer value) service container relative CPU weight versus other containers. + +### cpu_period + +`cpu_period` allow Compose implementations to configure CPU CFS (Completely Fair Scheduler) period when platform is based +on Linux kernel. + +### cpu_quota + +`cpu_quota` allow Compose implementations to configure CPU CFS (Completely Fair Scheduler) quota when platform is based +on Linux kernel. + +### cpu_rt_runtime + +`cpu_rt_runtime` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either +an integer value using microseconds as unit or a [duration](#specifying-durations). + +```yaml + cpu_rt_runtime: '400ms' + cpu_rt_runtime: 95000` +``` + +### cpu_rt_period + +`cpu_rt_period` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either +an integer value using microseconds as unit or a [duration](#specifying-durations). + +```yaml + cpu_rt_period: '1400us' + cpu_rt_period: 11000` +``` + +### cpus + +_DEPRECATED: use [deploy.reservations.cpus](deploy.md#cpus)_ + +`cpus` define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. +`0.000` means no limit. + +### cpuset + +`cpuset` defines the explicit CPUs in which to allow execution. Can be a range `0-3` or a list `0,1` + + +### cap_add + +`cap_add` specifies additional container [capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) +as strings. + +``` +cap_add: + - ALL +``` + +### cap_drop + +`cap_drop` specifies container [capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) to drop +as strings. + +``` +cap_drop: + - NET_ADMIN + - SYS_ADMIN +``` + +### cgroup_parent + +`cgroup_parent` specifies an OPTIONAL parent [cgroup](http://man7.org/linux/man-pages/man7/cgroups.7.html) for the container. + +``` +cgroup_parent: m-executor-abcd +``` + +### command + +`command` overrides the the default command declared by the container image (i.e. by Dockerfile's `CMD`). + +``` +command: bundle exec thin -p 3000 +``` + +The command can also be a list, in a manner similar to [Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd): + +``` +command: [ "bundle", "exec", "thin", "-p", "3000" ] +``` + +### configs + +`configs` grant access to configs on a per-service basis using the per-service `configs` +configuration. Two different syntax variants are supported. + +Compose implementations MUST report an error if config doesn't exist on platform or isn't defined in the +[`configs`](#configs-top-level-element) section of this Compose file. + +There are two syntaxes defined for configs. To remain compliant to this specification, an implementation +MUST support both syntaxes. Implementations MUST allow use of both short and long syntaxes within the same document. + +#### Short syntax + +The short syntax variant only specifies the config name. This grants the +container access to the config and mounts it at `/` +within the container. The source name and destination mount point are both set +to the config name. + +The following example uses the short syntax to grant the `redis` service +access to the `my_config` and `my_other_config` configs. The value of +`my_config` is set to the contents of the file `./my_config.txt`, and +`my_other_config` is defined as an external resource, which means that it has +already been defined in the platform. If the external config does not exist, +the deployment MUST fail. + +```yaml +services: + redis: + image: redis:latest + configs: + - my_config +configs: + my_config: + file: ./my_config.txt + my_other_config: + external: true +``` + +#### Long syntax + +The long syntax provides more granularity in how the config is created within the service's task containers. + +- `source`: The name of the config as it exists in the platform. +- `target`: The path and name of the file to be mounted in the service's + task containers. Defaults to `/` if not specified. +- `uid` and `gid`: The numeric UID or GID that owns the mounted config file + within the service's task containers. Default value when not specified is USER running container. +- `mode`: The [permissions](http://permissions-calculator.org/) for the file that is mounted within the service's + task containers, in octal notation. Default value is world-readable (`0444`). + Writable bit MUST be ignored. The executable bit can be set. + +The following example sets the name of `my_config` to `redis_config` within the +container, sets the mode to `0440` (group-readable) and sets the user and group +to `103`. The `redis` service does not have access to the `my_other_config` +config. + +```yaml +services: + redis: + image: redis:latest + configs: + - source: my_config + target: /redis_config + uid: "103" + gid: "103" + mode: 0440 +configs: + my_config: + external: true + my_other_config: + external: true +``` + +You can grant a service access to multiple configs, and you can mix long and short syntax. + +### container_name + +`container_name` is a string that specifies a custom container name, rather than a generated default name. + +```yaml +container_name: my-web-container +``` + +Compose implementation MUST NOT scale a service beyond one container if the Compose file specifies a +`container_name`. Attempting to do so MUST result in an error. + +If present, `container_name` SHOULD follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+` + +### credential_spec + +`credential_spec` configures the credential spec for a managed service account. + +Compose implementations that support services using Windows containers MUST support `file:` and +`registry:` protocols for credential_spec. Compose implementations MAY also support additional +protocols for custom use-cases. + +The `credential_spec` must be in the format `file://` or `registry://`. + +```yaml +credential_spec: + file: my-credential-spec.json +``` + +When using `registry:`, the credential spec is read from the Windows registry on +the daemon's host. A registry value with the given name must be located in: + + HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs + +The following example loads the credential spec from a value named `my-credential-spec` +in the registry: + +```yaml +credential_spec: + registry: my-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: + +```yaml +services: + myservice: + image: myimage:latest + credential_spec: + config: my_credential_spec + +configs: + my_credentials_spec: + file: ./my-credential-spec.json| +``` + +### depends_on + +`depends_on` expresses startup and shutdown dependencies between services. + +#### Short syntax + +The short syntax variant only specifies service names of the dependencies. +Service dependencies cause the following behaviors: + +- Compose implementations MUST create services in dependency order. In the following + example, `db` and `redis` are created before `web`. + +- Compose implementations MUST remove services in dependency order. In the following + example, `web` is removed before `db` and `redis`. + +Simple example: + +```yaml +services: + web: + build: . + depends_on: + - db + - redis + redis: + image: redis + db: + image: postgres +``` + +Compose implementations MUST guarantee dependency services have been started before +starting a dependent service. +Compose implementations MAY wait for dependency services to be "ready" before +starting a dependent service. + +#### Long syntax + +The long form syntax enables the configuration of additional fields that can't be +expressed in the short form. + +- `condition`: condition under which dependency is considered satisfied + - `service_started`: is an equivalent of the short syntax described above + - `service_healthy`: specifies that a dependency is expected to be "healthy" + (as indicated by [healthcheck](#healthcheck)) before starting a dependent + service. + - `service_completed_successfully`: specifies that a dependency is expected to run + to successful completion before starting a dependent service. + +Service dependencies cause the following behaviors: + +- Compose implementations MUST create services in dependency order. In the following + example, `db` and `redis` are created before `web`. + +- Compose implementations MUST wait for healthchecks to pass on dependencies + marked with `service_healthy`. In the following example, `db` is expected to + be "healthy" before `web` is created. + +- Compose implementations MUST remove services in dependency order. In the following + example, `web` is removed before `db` and `redis`. + +Simple example: + +```yaml +services: + web: + build: . + depends_on: + db: + condition: service_healthy + redis: + condition: service_started + redis: + image: redis + db: + image: postgres +``` + +Compose implementations MUST guarantee dependency services have been started before +starting a dependent service. +Compose implementations MUST guarantee dependency services marked with +`service_healthy` are "healthy" before starting a dependent service. + + +### deploy + +`deploy` specifies the configuration for the deployment and lifecycle of services, as defined [here](deploy.md). + + +### device_cgroup_rules + +`device_cgroup_rules` defines a list of device cgroup rules for this container. +The format is the same format the Linux kernel specifies in the [Control Groups +Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html). + +```yaml +device_cgroup_rules: + - 'c 1:3 mr' + - 'a 7:* rmw' +``` + +### devices + +`devices` defines a list of device mappings for created containers in the form of +`HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]`. + +```yaml +devices: + - "/dev/ttyUSB0:/dev/ttyUSB0" + - "/dev/sda:/dev/xvda:rwm" +``` + +### dns + +`dns` defines custom DNS servers to set on the container network interface configuration. Can be a single value or a list. + +```yaml +dns: 8.8.8.8 +``` + +```yaml +dns: + - 8.8.8.8 + - 9.9.9.9 +``` + +### dns_opt + +`dns_opt` list custom DNS options to be passed to the container’s DNS resolver (`/etc/resolv.conf` file on Linux). + +```yaml +dns_opt: + - use-vc + - no-tld-query +``` + +### dns_search + +`dns` defines custom DNS search domains to set on container network interface configuration. Can be a single value or a list. + +```yaml +dns_search: example.com +``` + +```yaml +dns_search: + - dc1.example.com + - dc2.example.com +``` + +### domainname + +`domainname` declares a custom domain name to use for the service container. MUST be a valid RFC 1123 hostname. + +### entrypoint + +`entrypoint` overrides the default entrypoint for the Docker image (i.e. `ENTRYPOINT` set by Dockerfile). +Compose implementations MUST clear out any default command on the Docker image - both `ENTRYPOINT` and `CMD` instruction +in the Dockerfile - when `entrypoint` is configured by a Compose file. If [`command`](#command) is also set, +it is used as parameter to `entrypoint` as a replacement for Docker image's `CMD` + +```yaml +entrypoint: /code/entrypoint.sh +``` + +The entrypoint can also be a list, in a manner similar to +[Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd): + +```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 +``` + +### env_file + +`env_file` adds environment variables to the container based on file content. + +```yaml +env_file: .env +``` + +`env_file` can also be a list. The files in the list MUST be processed from the top down. For the same variable +specified in two env files, the value from the last file in the list MUST stand. + +```yaml +env_file: + - ./a.env + - ./b.env +``` + +Relative path MUST be resolved from the Compose file's parent folder. As absolute paths prevent the Compose +file from being portable, Compose implementations SHOULD warn users when such a path is used to set `env_file`. + +Environment variables declared in the [environment](#environment) section +MUST override these values – this holds true even if those values are +empty or undefined. + +#### Env_file format + +Each line in an env file MUST be in `VAR[=[VAL]]` format. Lines beginning with `#` MUST be ignored. +Blank lines MUST also be ignored. + +The value of `VAL` is used as a raw string and not modified at all. If the value is surrounded by quotes +(as is often the case for shell variables), the quotes MUST be **included** in the value passed to containers +created by the Compose implementation. + +`VAL` MAY be omitted, in such cases the variable value is empty string. +`=VAL` MAY be omitted, in such cases the variable is **unset**. + +```bash +# Set Rails/Rack environment +RACK_ENV=development +VAR="quoted" +``` + +### environment + +`environment` defines environment variables set in the container. `environment` can use either an array or a +map. Any boolean values; true, false, yes, no, SHOULD be enclosed in quotes to ensure +they are not converted to True or False by the YAML parser. + +Environment variables MAY be declared by a single key (no value to equals sign). In such a case Compose +implementations SHOULD rely on some user interaction to resolve the value. If they do not, the variable +is unset and will be removed from the service container environment. + +Map syntax: + +```yaml +environment: + RACK_ENV: development + SHOW: "true" + USER_INPUT: +``` + +Array syntax: + +```yaml +environment: + - RACK_ENV=development + - SHOW=true + - USER_INPUT +``` + +When both `env_file` and `environment` are set for a service, values set by `environment` have precedence. + +### expose + +`expose` defines the ports that Compose implementations MUST expose from container. These ports MUST be +accessible to linked services and SHOULD NOT be published to the host machine. Only the internal container +ports can be specified. + +```yaml +expose: + - "3000" + - "8000" +``` + +### extends + +Extend another service, in the current file or another, optionally overriding configuration. You can use +`extends` on any service together with other configuration keys. The `extends` value MUST be a mapping +defined with a required `service` and an optional `file` key. + +```yaml +extends: + file: common.yaml + service: webapp +``` + +If supported Compose implementations MUST process `extends` in the following way: + +- `service` defines the name of the service being referenced as a base, for example `web` or `database`. +- `file` is the location of a Compose configuration file defining that service. + +#### Restrictions + +The following restrictions apply to the service being referenced: + +- Services that have dependencies on other services cannot be used as a base. Therefore, any key + that introduces a dependency on another service is incompatible with `extends`. The + non-exhaustive list of such keys is: `links`, `volumes_from`, `container` mode (in `ipc`, `pid`, + `network_mode` and `net`), `service` mode (in `ipc`, `pid` and `network_mode`), `depends_on`. +- Services cannot have circular references with `extends` + +Compose implementations MUST return an error in all of these cases. + +#### Finding referenced service + +`file` value can be: + +- Not present. + This indicates that another service within the same Compose file is being referenced. +- File path, which can be either: + - Relative path. This path is considered as relative to the location of the main Compose + file. + - Absolute path. + +Service denoted by `service` MUST be present in the identified referenced Compose file. +Compose implementations MUST return an error if: + +- Service denoted by `service` was not found +- Compose file denoted by `file` was not found + +#### Merging service definitions + +Two service definitions (_main_ one in the current Compose file and _referenced_ one +specified by `extends`) MUST be merged in the following way: + +- Mappings: keys in mappings of _main_ service definition override keys in mappings + of _referenced_ service definition. Keys that aren't overridden are included as is. +- Sequences: items are combined together into an new sequence. Order of elements is + preserved with the _referenced_ items coming first and _main_ items after. +- Scalars: keys in _main_ service definition take precedence over keys in the + _referenced_ one. + +##### Mappings + +The following keys should be treated as mappings: `build.args`, `build.labels`, +`build.extra_hosts`, `deploy.labels`, `deploy.update_config`, `deploy.rollback_config`, +`deploy.restart_policy`, `deploy.resources.limits`, `environment`, `healthcheck`, +`labels`, `logging.options`, `sysctls`, `storage_opt`, `extra_hosts`, `ulimits`. + +One exception that applies to `healthcheck` is that _main_ mapping cannot specify +`disable: true` unless _referenced_ mapping also specifies `disable: true`. Compose +implementations MUST return an error in this case. + +For example, the input below: + +```yaml +services: + common: + image: busybox + environment: + TZ: utc + PORT: 80 + cli: + extends: + service: common + environment: + PORT: 8080 +``` + +Produces the following configuration for the `cli` service. The same output is +produced if array syntax is used. + +```yaml +environment: + PORT: 8080 + TZ: utc +image: busybox +``` + +Items under `blkio_config.device_read_bps`, `blkio_config.device_read_iops`, +`blkio_config.device_write_bps`, `blkio_config.device_write_iops`, `devices` and +`volumes` are also treated as mappings where key is the target path inside the +container. + +For example, the input below: + +```yaml +services: + common: + image: busybox + volumes: + - common-volume:/var/lib/backup/data:rw + cli: + extends: + service: common + volumes: + - cli-volume:/var/lib/backup/data:ro +``` + +Produces the following configuration for the `cli` service. Note that mounted path +now points to the new volume name and `ro` flag was applied. + +```yaml +image: busybox +volumes: +- cli-volume:/var/lib/backup/data:ro +``` + +If _referenced_ service definition contains `extends` mapping, the items under it +are simply copied into the new _merged_ definition. Merging process is then kicked +off again until no `extends` keys are remaining. + +For example, the input below: + +```yaml +services: + base: + image: busybox + user: root + common: + image: busybox + extends: + service: base + cli: + extends: + service: common +``` + +Produces the following configuration for the `cli` service. Here, `cli` services +gets `user` key from `common` service, which in turn gets this key from `base` +service. + +```yaml +image: busybox +user: root +``` + +##### Sequences + +The following keys should be treated as sequences: `cap_add`, `cap_drop`, `configs`, +`deploy.placement.constraints`, `deploy.placement.preferences`, +`deploy.reservations.generic_resources`, `device_cgroup_rules`, `expose`, +`external_links`, `ports`, `secrets`, `security_opt`. +Any duplicates resulting from the merge are removed so that the sequence only +contains unique elements. + +For example, the input below: + +```yaml +services: + common: + image: busybox + security_opt: + - label:role:ROLE + cli: + extends: + service: common + security_opt: + - label:user:USER +``` + +Produces the following configuration for the `cli` service. + +```yaml +image: busybox +security_opt: +- label:role:ROLE +- label:user:USER +``` + +In case list syntax is used, the following keys should also be treated as sequences: +`dns`, `dns_search`, `env_file`, `tmpfs`. Unlike sequence fields mentioned above, +duplicates resulting from the merge are not removed. + +##### Scalars + +Any other allowed keys in the service definition should be treated as scalars. + +### external_links + +`external_links` link service containers to services managed outside this Compose application. +`external_links` define the name of an existing service to retrieve using the platform lookup mechanism. +An alias of the form `SERVICE:ALIAS` can be specified. + +```yaml +external_links: + - redis + - database:mysql + - database:postgresql +``` + +### extra_hosts + +`extra_hosts` adds hostname mappings to the container network interface configuration (`/etc/hosts` for Linux). +Values MUST set hostname and IP address for additional hosts in the form of `HOSTNAME:IP`. + +```yaml +extra_hosts: + - "somehost:162.242.195.82" + - "otherhost:50.31.209.229" +``` + +Compose implementations MUST create matching entry with the IP address and hostname in the container's network +configuration, which means for Linux `/etc/hosts` will get extra lines: + +``` +162.242.195.82 somehost +50.31.209.229 otherhost +``` + +### group_add + +`group_add` specifies additional groups (by name or number) which the user inside the container MUST be a member of. + +An example of where this is useful is when multiple containers (running as different users) need to all read or write +the same file on a shared volume. That file can be owned by a group shared by all the containers, and specified in +`group_add`. + +```yaml +services: + myservice: + image: alpine + group_add: + - mail +``` + +Running `id` inside the created container MUST show that the user belongs to the `mail` group, which would not have +been the case if `group_add` were not declared. + +### healthcheck + +`healthcheck` declares a check that's run to determine whether or not containers for this +service are "healthy". This overrides +[HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck) +set by the service's Docker image. + +```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). + +`test` defines the command the Compose implementation will run to check container health. It can 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. + +```yaml +# Hit the local web app +test: ["CMD", "curl", "-f", "http://localhost"] +``` + +Using `CMD-SHELL` will run the command configured as a string using the container's default shell +(`/bin/sh` for Linux). Both forms below are equivalent: + +```yaml +test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] +``` + +```yaml +test: curl -f https://localhost || exit 1 +``` + +`NONE` disable the healthcheck, and is mostly useful to disable Healthcheck set by image. Alternatively +the healthcheck set by the image can be disabled by setting `disable: true`: + +```yaml +healthcheck: + disable: true +``` + +### hostname + +`hostname` declares a custom host name to use for the service container. MUST be a valid RFC 1123 hostname. + +### image + +`image` specifies the image to start the container from. Image MUST follow the Open Container Specification +[addressable image format](https://github.com/opencontainers/org/blob/master/docs/docs/introduction/digests.md), +as `[/][/][:|@]`. + +```yaml + image: redis + image: redis:5 + image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7 + image: library/redis + image: docker.io/library/redis + image: my_private.registry:5000/redis +``` + +If the image does not exist on the platform, Compose implementations MUST attempt to pull it based on the `pull_policy`. +Compose implementations with build support MAY offer alternative options for the end user to control precedence of +pull over building the image from source, however pulling the image MUST be the default behavior. + +`image` MAY be omitted from a Compose file as long as a `build` section is declared. Compose implementations +without build support MUST fail when `image` is missing from the Compose file. + +### init + +`init` run an init process (PID 1) inside the container that forwards signals and reaps processes. +Set this option to `true` to enable this feature for the service. + +```yaml +services: + web: + image: alpine:latest + init: true +``` + +The init binary that is used is platform specific. + +### ipc + +`ipc` configures the IPC isolation mode set by service container. Available +values are platform specific, but Compose specification defines specific values +which MUST be implemented as described if supported: + +- `shareable` which gives the container own private IPC namespace, with a + possibility to share it with other containers. +- `service:{name}` which makes the container join another (`shareable`) + container's IPC namespace. + +```yaml + ipc: "shareable" + ipc: "service:[service name]" +``` + +### isolation + +`isolation` specifies a container’s isolation technology. Supported values are platform-specific. + +### labels + +`labels` add metadata to containers. You can use either an array or a map. + +It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with +those used by other software. + +```yaml +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" +``` + +Compose implementations MUST create containers with canonical labels: + +- `com.docker.compose.project` set on all resources created by Compose implementation to the user project name +- `com.docker.compose.service` set on service containers with service name as defined in the Compose file + +The `com.docker.compose` label prefix is reserved. Specifying labels with this prefix in the Compose file MUST +result in a runtime error. + +### links + +`links` defines a network link to containers in another service. Either specify both the service name and +a link alias (`SERVICE:ALIAS`), or just the service name. + +```yaml +web: + links: + - db + - db:database + - redis +``` + +Containers for the linked service MUST be 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 - when no specific network configuration is set, +any service MUST be able to reach any other service at that service’s name on the `default` network. If services +do declare networks they are attached to, `links` SHOULD NOT override the network configuration and services not +attached to a shared network SHOULD NOT be able to communicate. Compose implementations MAY NOT warn the user +about this configuration mismatch. + +Links also express implicit dependency between services in the same way as +[depends_on](#depends_on), so they determine the order of service startup. + +### logging + +`logging` defines the logging configuration for the service. + +```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. The default and available values +are platform specific. Driver specific options can be set with `options` as key-value pairs. + +### network_mode + +`network_mode` set service containers network mode. Available values are platform specific, but Compose +specification define specific values which MUST be implemented as described if supported: + +- `none` which disable all container networking +- `host` which gives the container raw access to host's network interface +- `service:{name}` which gives the containers access to the specified service only + +```yaml + network_mode: "host" + network_mode: "none" + network_mode: "service:[service name]" +``` + +### networks + +`networks` defines the networks that service containers are attached to, referencing entries under the +[top-level `networks` key](#networks-top-level-element). + +```yaml +services: + some-service: + networks: + - some-network + - other-network +``` + +#### aliases + +`aliases` declares alternative hostnames for this service on the network. Other containers on the same +network can use either the service name or this alias to connect to one of the service's containers. + +Since `aliases` are 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. + +The general format is shown here: + +```yaml +services: + some-service: + networks: + some-network: + aliases: + - alias1 + - alias3 + other-network: + aliases: + - alias2 +``` + +In the example below, service `frontend` will be able to reach the `backend` service at +the hostname `backend` or `database` on the `back-tier` network, and service `monitoring` +will be able to reach same `backend` service at `db` or `mysql` on the `admin` network. + +```yaml +services: + frontend: + image: awesome/webapp + networks: + - front-tier + - back-tier + + monitoring: + image: awesome/monitoring + networks: + - admin + + backend: + image: awesome/backend + networks: + back-tier: + aliases: + - database + admin: + aliases: + - mysql + +networks: + front-tier: + back-tier: + admin: +``` + +#### 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](#networks) MUST have an +`ipam` block with subnet configurations covering each static address. + +```yaml +services: + frontend: + image: awesome/webapp + networks: + front-tier: + ipv4_address: 172.16.238.10 + ipv6_address: 2001:3984:3989::10 + +networks: + front-tier: + ipam: + driver: default + config: + - subnet: "172.16.238.0/24" + - subnet: "2001:3984:3989::/64" +``` + +#### link_local_ips + +`link_local_ips` specifies 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 dependent on the architecture where they are +deployed. Implementation is Platform specific. + +Example: + +```yaml +services: + app: + image: busybox + command: top + networks: + app_net: + link_local_ips: + - 57.123.22.11 + - 57.123.22.13 +networks: + app_net: + driver: bridge +``` + +#### priority + +`priority` indicates in which order Compose implementation SHOULD connect the service’s containers to its +networks. If unspecified, the default value is 0. + +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. + +```yaml +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: +``` + +### mac_address + +`mac_address` sets a MAC address for service container. + +### mem_limit + +_DEPRECATED: use [deploy.limits.memory](deploy.md#memory)_ + +### mem_reservation + +_DEPRECATED: use [deploy.reservations.memory](deploy.md#memory)_ + +### mem_swappiness + +`mem_swappiness` defines as a percentage (a value between 0 and 100) for the host kernel to swap out +anonymous memory pages used by a container. + +- a value of 0 turns off anonymous page swapping. +- a value of 100 sets all anonymous pages as swappable. + +Default value is platform specific. + +### memswap_limit + +`memswap_limit` defines the amount of memory container is allowed to swap to disk. This is a modifier +attribute that only has meaning if `memory` is also set. Using swap allows the container to write excess +memory requirements to disk when the container has exhausted all the memory that is available to it. +There is a performance penalty for applications that swap memory to disk often. + +- If `memswap_limit` is set to a positive integer, then both `memory` and `memswap_limit` MUST be set. `memswap_limit` represents the total amount of memory and swap that can be used, and `memory` controls the amount used by non-swap memory. So if `memory`="300m" and `memswap_limit`="1g", the container can use 300m of memory and 700m (1g - 300m) swap. +- If `memswap_limit` is set to 0, the setting MUST be ignored, and the value is treated as unset. +- If `memswap_limit` is set to the same value as `memory`, and `memory` is set to a positive integer, the container does not have access to swap. See Prevent a container from using swap. +- If `memswap_limit` is unset, and `memory` is set, the container can use as much swap as the `memory` setting, if the host container has swap memory configured. For instance, if `memory`="300m" and `memswap_limit` is not set, the container can use 600m in total of memory and swap. +- If `memswap_limit` is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system. + +### oom_kill_disable + +If `oom_kill_disable` is set Compose implementation MUST configure the platform so it won't kill the container in case +of memory starvation. + +### oom_score_adj + +`oom_score_adj` tunes the preference for containers to be killed by platform in case of memory starvation. Value MUST +be within [-1000,1000] range. + +### pid + +`pid` sets the PID mode for container created by the Compose implementation. +Supported values are platform specific. + +### pids_limit + +_DEPRECATED: use [deploy.reservations.pids](deploy.md#pids)_ + +`pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs. + +```yaml +pids_limit: 10 +``` + +### platform + +`platform` defines the target platform containers for this service will run on, using the `os[/arch[/variant]]` syntax. +Compose implementation MUST use this attribute when declared to determine which version of the image will be pulled +and/or on which platform the service’s build will be performed. + +```yaml +platform: osx +platform: windows/amd64 +platform: linux/arm64/v8 +``` + +### ports + +Exposes container ports. +Port mapping MUST NOT be used with `network_mode: host` and doing so MUST result in a runtime error. + +#### Short syntax + +The short syntax is a colon-separated string to set host IP, host port and container port +in the form: + +`[HOST:]CONTAINER[/PROTOCOL]` where: + +- `HOST` is `[IP:](port | range)` +- `CONTAINER` is `port | range` +- `PROTOCOL` to restrict port to specified protocol. `tcp` and `udp` values are defined by the specification, + Compose implementations MAY offer support for platform-specific protocol names. + +Host IP, if not set, MUST bind to all network interfaces. Port can be either a single +value or a range. Host and container MUST use equivalent ranges. + +Either specify both ports (`HOST:CONTAINER`), or just the container port. In the latter case, the +Compose implementation SHOULD automatically allocate any unassigned host port. + +`HOST:CONTAINER` SHOULD always be specified as a (quoted) string, to avoid conflicts +with [yaml base-60 float](https://yaml.org/type/float.html). + +Samples: + +```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" +``` + +> **Note**: Host IP mapping MAY not be supported on the platform, in such case Compose implementations SHOULD reject +> the Compose file and MUST inform the user they will ignore the specified host IP. + +#### Long syntax + +The long form syntax allows the configuration of additional fields that can't be +expressed in the short form. + +- `target`: the container port +- `published`: the publicly exposed port. Can be set as a range using syntax `start-end`, then actual port SHOULD be assigned within this range based on available ports. +- `host_ip`: the Host IP mapping, unspecified means all network interfaces (`0.0.0.0`) +- `protocol`: the port protocol (`tcp` or `udp`), unspecified means any protocol +- `mode`: `host` for publishing a host port on each node, or `ingress` for a port to be load balanced. + +```yaml +ports: + - target: 80 + host_ip: 127.0.0.1 + published: 8080 + protocol: tcp + mode: host + + - target: 80 + host_ip: 127.0.0.1 + published: 8000-9000 + protocol: tcp + mode: host +``` + +### privileged + +`privileged` configures the service container to run with elevated privileges. Support and actual impacts are platform-specific. + +### profiles + +`profiles` defines a list of named profiles for the service to be enabled under. When not set, service is always enabled. + +If present, `profiles` SHOULD follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`. + +### pull_policy + +`pull_policy` defines the decisions Compose implementations will make when it starts to pull images. Possible values are: + +* `always`: Compose implementations SHOULD always pull the image from the registry. +* `never`: Compose implementations SHOULD NOT pull the image from a registry and SHOULD rely on the platform cached image. + If there is no cached image, a failure MUST be reported. +* `missing`: Compose implementations SHOULD pull the image only if it's not available in the platform cache. + This SHOULD be the default option for Compose implementations without build support. + `if_not_present` SHOULD be considered an alias for this value for backward compatibility +* `build`: Compose implementations SHOULD build the image. Compose implementations SHOULD rebuild the image if already present. + +If `pull_policy` and `build` both presents, Compose implementations SHOULD build the image by default. Compose implementations MAY override this behavior in the toolchain. + +### read_only + +`read_only` configures service container to be created with a read-only filesystem. + +### restart + +`restart` defines the policy that the platform will apply on container termination. + +- `no`: The default restart policy. Does not restart a container under any circumstances. +- `always`: The policy always restarts the container until its removal. +- `on-failure`: The policy restarts a container if the exit code indicates an error. +- `unless-stopped`: The policy restarts a container irrespective of the exit code but will stop + restarting when the service is stopped or removed. + +```yaml + restart: "no" + restart: always + restart: on-failure + restart: unless-stopped +``` + +### runtime + +`runtime` specifies which runtime to use for the service’s containers. + +The value of `runtime` is specific to implementation. +For example, `runtime` can be the name of [an implementation of OCI Runtime Spec](https://github.com/opencontainers/runtime-spec/blob/master/implementations.md), such as "runc". + +```yaml +web: + image: busybox:latest + command: true + runtime: runc +``` + +### scale + +-DEPRECATED: use [deploy/replicas](deploy.md#replicas)_ + +`scale` specifies the default number of containers to deploy for this service. + +### secrets + +`secrets` grants access to sensitive data defined by [secrets](secrets) on a per-service basis. Two +different syntax variants are supported: the short syntax and the long syntax. + +Compose implementations MUST report an error if the secret doesn't exist on the platform or isn't defined in the +[`secrets`](#secrets-top-level-element) section of this Compose file. + +#### Short syntax + +The short syntax variant only specifies the secret name. This grants the +container access to the secret and mounts it as read-only to `/run/secrets/` +within the container. The source name and destination mountpoint are both set +to the secret name. + +The following example uses the short syntax to grant the `frontend` service +access to the `server-certificate` secret. The value of `server-certificate` is set +to the contents of the file `./server.cert`. + +```yaml +services: + frontend: + image: awesome/webapp + secrets: + - server-certificate +secrets: + server-certificate: + file: ./server.cert +``` + +#### Long syntax + +The long syntax provides more granularity in how the secret is created within +the service's containers. + +- `source`: The name of the secret as it exists on the platform. +- `target`: The name of the file to be mounted in `/run/secrets/` in the + service's task containers. Defaults to `source` if not specified. +- `uid` and `gid`: The numeric UID or GID that owns the file within + `/run/secrets/` in the service's task containers. Default value is USER running container. +- `mode`: The [permissions](http://permissions-calculator.org/) for the file to be mounted in `/run/secrets/` + in the service's task containers, in octal notation. + Default value is world-readable permissions (mode `0444`). + The writable bit MUST be ignored if set. The executable bit MAY be set. + +The following example sets the name of the `server-certificate` secret file to `server.crt` +within the container, sets the mode to `0440` (group-readable) and sets the user and group +to `103`. The value of `server-certificate` secret is provided by the platform through a lookup and +the secret lifecycle not directly managed by the Compose implementation. + +```yaml +services: + frontend: + image: awesome/webapp + secrets: + - source: server-certificate + target: server.cert + uid: "103" + gid: "103" + mode: 0440 +secrets: + server-certificate: + external: true +``` + +Services MAY be granted access to multiple secrets. Long and short syntax for secrets MAY be used in the +same Compose file. Defining a secret in the top-level `secrets` MUST NOT imply granting any service access to it. +Such grant must be explicit within service specification as [secrets](#secrets) service element. + +### security_opt + +`security_opt` overrides the default labeling scheme for each container. + +```yaml +security_opt: + - label:user:USER + - label:role:ROLE +``` + +### shm_size + +`shm_size` configures the size of the shared memory (`/dev/shm` partition on Linux) allowed by the service container. +Specified as a [byte value](#specifying-byte-values). + +### stdin_open + +`stdin_open` configures service containers to run with an allocated stdin. + +### stop_grace_period + +`stop_grace_period` specifies how long the Compose implementation MUST wait when attempting to stop a container if it doesn't +handle SIGTERM (or whichever stop signal has been specified with +[`stop_signal`](#stopsignal)), before sending SIGKILL. Specified +as a [duration](#specifying-durations). + +```yaml + stop_grace_period: 1s + stop_grace_period: 1m30s +``` + +Default value is 10 seconds for the container to exit before sending SIGKILL. + +### stop_signal + +`stop_signal` defines the signal that the Compose implementation MUST use to stop the service containers. +If unset containers are stopped by the Compose Implementation by sending `SIGTERM`. + +```yaml +stop_signal: SIGUSR1 +``` + +### storage_opt + +`storage_opt` defines storage driver options for a service. + +```yaml +storage_opt: + size: '1G' +``` + +### sysctls + +`sysctls` defines kernel parameters to set in the container. `sysctls` can use either an array or a map. + +```yaml +sysctls: + net.core.somaxconn: 1024 + net.ipv4.tcp_syncookies: 0 +``` + +```yaml +sysctls: + - net.core.somaxconn=1024 + - net.ipv4.tcp_syncookies=0 +``` + +You can only use sysctls that are namespaced in the kernel. Docker does not +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](https://docs.docker.com/engine/reference/commandline/run/#configure-namespaced-kernel-parameters-sysctls-at-runtime). + +### tmpfs + +`tmpfs` mounts a temporary file system inside the container. Can be a single value or a list. + +```yaml +tmpfs: /run +``` + +```yaml +tmpfs: + - /run + - /tmp +``` + +### tty + +`tty` configure service container to run with a TTY. + +### ulimits + +`ulimits` overrides the default ulimits for a container. Either specifies as a single limit as an integer or +soft/hard limits as a mapping. + +```yaml +ulimits: + nproc: 65535 + nofile: + soft: 20000 + hard: 40000 +``` + +### user + +`user` overrides the user used to run the container process. Default is that set by image (i.e. Dockerfile `USER`), +if not set, `root`. + +### userns_mode + +`userns_mode` sets the user namespace for the service. Supported values are platform specific and MAY depend +on platform configuration + +```yaml +userns_mode: "host" +``` + +### volumes + +`volumes` defines mount host paths or named volumes that MUST be accessible by service containers. + +If the mount is a host path and only used by a single service, it MAY be declared as part of the service +definition instead of the top-level `volumes` key. + +To reuse a volume across multiple services, a named +volume MUST be declared in the [top-level `volumes` key](#volumes-top-level-element). + +This example shows a named volume (`db-data`) being used by the `backend` service, +and a bind mount defined for a single service + +```yaml +services: + backend: + image: awesome/backend + volumes: + - type: volume + source: db-data + target: /data + volume: + nocopy: true + - type: bind + source: /var/run/postgres/postgres.sock + target: /var/run/postgres/postgres.sock + +volumes: + db-data: +``` + +#### Short syntax + +The short syntax uses a single string with colon-separated values to specify a volume mount +(`VOLUME:CONTAINER_PATH`), or an access mode (`VOLUME:CONTAINER_PATH:ACCESS_MODE`). + +- `VOLUME`: MAY be either a host path on the platform hosting containers (bind mount) or a volume name +- `CONTAINER_PATH`: the path in the container where the volume is mounted +- `ACCESS_MODE`: is a comma-separated `,` list of options and MAY be set to: + - `rw`: read and write access (default) + - `ro`: read-only access + - `z`: SELinux option indicates that the bind mount host content is shared among multiple containers + - `Z`: SELinux option indicates that the bind mount host content is private and unshared for other containers + +> **Note**: The SELinux re-labeling bind mount option is ignored on platforms without SELinux. + +> **Note**: Relative host paths MUST only be supported by Compose implementations that deploy to a +> local container runtime. This is because the relative path is resolved from the Compose file’s parent +> directory which is only applicable in the local case. Compose Implementations deploying to a non-local +> platform MUST reject Compose files which use relative host paths with an error. To avoid ambiguities +> with named volumes, relative paths SHOULD always begin with `.` or `..`. + +#### Long syntax + +The long form syntax allows the configuration of additional fields that can't be +expressed in the short form. + +- `type`: the mount type `volume`, `bind`, `tmpfs` or `npipe` +- `source`: the source of the mount, a path on the host for a bind mount, or the + name of a volume defined in the + [top-level `volumes` key](#volumes-top-level-element). Not applicable for a tmpfs mount. +- `target`: the path in the container where the volume is mounted +- `read_only`: flag to set the volume as read-only +- `bind`: configure additional bind options + - `propagation`: the propagation mode used for the bind + - `create_host_path`: create a directory at the source path on host if there is nothing present. + Do nothing if there is something present at the path. This is automatically implied by short syntax + for backward compatibility with docker-compose legacy. + - `selinux`: the SELinux re-labeling option `z` (shared) or `Z` (private) +- `volume`: configure additional volume options + - `nocopy`: flag to disable copying of data from a container when a volume is created +- `tmpfs`: configure additional tmpfs options + - `size`: the size for the tmpfs mount in bytes (either numeric or as bytes unit) +- `consistency`: the consistency requirements of the mount. Available values are platform specific + +### volumes_from + +`volumes_from` mounts 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 MUST be used. + +String value defines another service in the Compose application model to mount volumes from. The +`container:` prefix, if supported, allows to mount volumes from a container that is not managed by the +Compose implementation. + +```yaml +volumes_from: + - service_name + - service_name:ro + - container:container_name + - container:container_name:rw +``` + +### working_dir + +`working_dir` overrides the container's working directory from that specified by image (i.e. Dockerfile `WORKDIR`). + +## Networks top-level element + +Networks are the layer that allow services to communicate with each other. The networking model exposed to a service +is limited to a simple IP connection with target services and external resources, while the Network definition allows +fine-tuning the actual implementation provided by the platform. + +Networks can be created by specifying the network name under a top-level `networks` section. +Services can connect to networks by specifying the network name under the service [`networks`](#networks) subsection + +In the following example, at runtime, networks `front-tier` and `back-tier` will be created and the `frontend` service +connected to the `front-tier` network and the `back-tier` network. + +```yaml +services: + frontend: + image: awesome/webapp + networks: + - front-tier + - back-tier + +networks: + front-tier: + back-tier: +``` + +### driver + +`driver` specifies which driver should be used for this network. Compose implementations MUST return an error if the +driver is not available on the platform. + +```yaml +driver: overlay +``` + +Default and available values are platform specific. Compose specification MUST support the following specific drivers: +`none` and `host` + +- `host` use the host's networking stack +- `none` disable networking + +#### host or none + +The syntax for using built-in networks such as `host` and `none` is different, as such networks implicitly exists outside +the scope of the Compose implementation. To use them one MUST define an external network with the name `host` or `none` and +an alias that the Compose implementation can use (`hostnet` or `nonet` in the following examples), then grant the service +access to that network using its alias. + +```yaml +services: + web: + networks: + hostnet: {} + +networks: + hostnet: + external: true + name: host +``` + +```yaml +services: + web: + ... + networks: + nonet: {} + +networks: + nonet: + external: true + name: none +``` + +### driver_opts + +`driver_opts` specifies a list of options as key-value pairs to pass to the driver for this network. These options are +driver-dependent - consult the driver's documentation for more information. Optional. + +```yaml +driver_opts: + foo: "bar" + baz: 1 +``` + +### attachable + +If `attachable` is set to `true`, then standalone containers SHOULD be able attach to this network, in addition to services. +If a standalone container attaches to the network, it can communicate with services and other standalone containers +that are also attached to the network. + +```yaml +networks: + mynet1: + driver: overlay + attachable: true +``` + +### enable_ipv6 + +`enable_ipv6` enable IPv6 networking on this network. + +### ipam + +`ipam` specifies custom a IPAM configuration. This is an object with several properties, each of which is optional: + +- `driver`: Custom IPAM driver, instead of the default. +- `config`: A list with zero or more configuration elements, each containing: + - `subnet`: Subnet in CIDR format that represents a network segment + - `ip_range`: Range of IPs from which to allocate container IPs + - `gateway`: IPv4 or IPv6 gateway for the master subnet + - `aux_addresses`: Auxiliary IPv4 or IPv6 addresses used by Network driver, as a mapping from hostname to IP +- `options`: Driver-specific options as a key-value mapping. + +A full example: + +```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 + +By default, Compose implementations MUST provides external connectivity to networks. `internal` when set to `true` allow to +create an externally isolated network. + +### labels + +Add metadata to containers using Labels. Can use either an array or a dictionary. + +Users SHOULD use reverse-DNS notation to prevent labels from conflicting with those used by other software. + +```yaml +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" +``` + +Compose implementations MUST set `com.docker.compose.project` and `com.docker.compose.network` labels. + +### external + +If set to `true`, `external` specifies that this network’s lifecycle is maintained outside of that of the application. +Compose Implementations SHOULD NOT attempt to create these networks, and raises an error if one doesn't exist. + +In the example below, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose +implementations SHOULD interrogate the platform for an existing network simply called `outside` and connect the +`proxy` service's containers to it. + +```yaml + +services: + proxy: + image: awesome/proxy + networks: + - outside + - default + app: + image: awesome/app + networks: + - default + +networks: + outside: + external: true +``` + +### name + +`name` sets 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 project name. + +```yaml +networks: + network1: + name: my-app-net +``` + +It can also be used in conjunction with the `external` property to define the platform network that the Compose implementation +should retrieve, typically by using a parameter so the Compose file doesn't need to hard-code runtime specific values: + +```yaml +networks: + network1: + external: true + name: "${NETWORK_ID}" +``` + +## Volumes top-level element + +Volumes are persistent data stores implemented by the platform. The Compose specification offers a neutral abstraction +for services to mount volumes, and configuration parameters to allocate them on infrastructure. + +The `volumes` section allows the configuration of named volumes that can be reused across multiple services. Here's +an example of a two-service setup where a database's data directory is shared with another service as a volume named +`db-data` so that it can be periodically backed up: + +```yaml +services: + backend: + image: awesome/database + volumes: + - db-data:/etc/data + + backup: + image: backup-service + volumes: + - db-data:/var/lib/backup/data + +volumes: + db-data: +``` + +An entry under the top-level `volumes` key can be empty, in which case it uses the platform's default configuration for +creating a volume. Optionally, you can configure it with the following keys: + +### driver + +Specify which volume driver should be used for this volume. Default and available values are platform specific. If the driver is not available, the Compose implementation MUST return an error and stop application deployment. + +```yaml +driver: foobar +``` + +### driver_opts + +`driver_opts` specifies a list of options as key-value pairs to pass to the driver for this volume. Those options are driver-dependent. + +```yaml +volumes: + example: + driver_opts: + type: "nfs" + o: "addr=10.40.0.199,nolock,soft,rw" + device: ":/docker/example" +``` + +### external + +If set to `true`, `external` specifies that this volume already exist on the platform and its lifecycle is managed outside +of that of the application. Compose implementations MUST NOT attempt to create these volumes, and MUST return an error if they +do not exist. + +In the example below, instead of attempting to create a volume called +`{project_name}_db-data`, Compose looks for an existing volume simply +called `db-data` and mounts it into the `backend` service's containers. + +```yaml +services: + backend: + image: awesome/database + volumes: + - db-data:/etc/data + +volumes: + db-data: + external: true +``` + +### labels + +`labels` are used to add metadata to volumes. 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. + +```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" +``` + +Compose implementation MUST set `com.docker.compose.project` and `com.docker.compose.volume` labels. + +### name + +`name` 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. + +```yaml +volumes: + data: + name: "my-app-data" +``` + +It can also be used in conjunction with the `external` property. Doing so the name of the volume used to lookup for +actual volume on platform is set separately from the name used to refer to it within the Compose file: + +```yaml +volumes: + db-data: + external: + name: actual-name-of-volume +``` + +This make it possible to make this lookup name a parameter of a Compose file, so that the model ID for volume is +hard-coded but the actual volume ID on platform is set at runtime during deployment: + +```yaml +volumes: + db-data: + external: + name: ${DATABASE_VOLUME} +``` + +## Configs top-level element + +Configs allow services to adapt their behaviour without the need to rebuild a Docker image. Configs are comparable to Volumes from a service point of view as they are mounted into service's containers filesystem. The actual implementation detail to get configuration provided by the platform can be set from the Configuration definition. + +When granted access to a config, the config content is mounted as a file in the container. The location of the mount point within the container defaults to `/` in Linux containers and `C:\` in Windows containers. + +By default, the config MUST be owned by the user running the container command but can be overridden by service configuration. +By default, the config MUST have world-readable permissions (mode 0444), unless service is configured to override this. + +Services can only access configs when explicitly granted by a [`configs`](#configs) subsection. + +The top-level `configs` declaration defines or references +configuration data that can be granted to the services in this +application. The source of the config is either `file` or `external`. + +- `file`: The config is created with the contents of the file at the specified path. +- `external`: If set to true, specifies that this config has already been created. Compose implementation does not + attempt to create it, and if it does not exist, an error occurs. +- `name`: The name of config object on Platform to lookup. This field can be used to + reference configs that contain special characters. The name is used as is + and will **not** be scoped with the project name. + +In this example, `http_config` is created (as `_http_config`) when the application is deployed, +and `my_second_config` MUST already exist on Platform and value will be obtained by lookup. + +In this example, `server-http_config` is created as `_http_config` when the application is deployed, +by registering content of the `httpd.conf` as configuration data. + +```yaml +configs: + http_config: + file: ./httpd.conf +``` + +Alternatively, `http_config` can be declared as external, doing so Compose implementation will lookup `http_config` to expose configuration data to relevant services. + +```yaml +configs: + http_config: + external: true +``` + +External configs lookup can also use a distinct key by specifying a `name`. The following +example modifies the previous one to lookup for config using a parameter `HTTP_CONFIG_KEY`. Doing +so the actual lookup key will be set at deployment time by [interpolation](#interpolation) of +variables, but exposed to containers as hard-coded ID `http_config`. + +```yaml +configs: + http_config: + external: true + name: "${HTTP_CONFIG_KEY}" +``` + +Compose file need to explicitly grant access to the configs to relevant services in the application. + +## Secrets top-level element + +Secrets are a flavour of Configs focussing on sensitive data, with specific constraint for this usage. As the platform implementation may significantly differ from Configs, dedicated Secrets section allows to configure the related resources. + +The top-level `secrets` declaration defines or references sensitive data that can be granted to the services in this +application. The source of the secret is either `file` or `external`. + +- `file`: The secret is created with the contents of the file at the specified path. +- `external`: If set to true, specifies that this secret has already been created. Compose implementation does + not attempt to create it, and if it does not exist, an error occurs. +- `name`: The name of the secret object in Docker. This field can be used to + reference secrets that contain special characters. The name is used as is + and will **not** be scoped with the project name. + +In this example, `server-certificate` is created as `_server-certificate` when the application is deployed, +by registering content of the `server.cert` as a platform secret. + +```yaml +secrets: + server-certificate: + file: ./server.cert +``` + +Alternatively, `server-certificate` can be declared as external, doing so Compose implementation will lookup `server-certificate` to expose secret to relevant services. + +```yaml +secrets: + server-certificate: + external: true +``` + +External secrets lookup can also use a distinct key by specifying a `name`. The following +example modifies the previous one to look up for secret using a parameter `CERTIFICATE_KEY`. Doing +so the actual lookup key will be set at deployment time by [interpolation](#interpolation) of +variables, but exposed to containers as hard-coded ID `server-certificate`. + +```yaml +secrets: + server-certificate: + external: true + name: "${CERTIFICATE_KEY}" +``` + +Compose file need to explicitly grant access to the secrets to relevant services in the application. + +## Fragments + +It is possible to re-use configuration fragments using [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2765878). + +```yaml +volumes: + db-data: &default-volume + driver: default + metrics: *default-volume +``` + +In previous sample, an _anchor_ is created as `default-volume` based on `db-data` volume specification. It is later reused by _alias_ `*default-volume` to define `metrics` volume. Same logic can apply to any element in a Compose file. Anchor resolution MUST take place +before [variables interpolation](#interpolation), so variables can't be used to set anchors or aliases. + +It is also possible to partially override values set by anchor reference using the +[YAML merge type](http://yaml.org/type/merge.html). In following example, `metrics` volume specification uses alias +to avoid repetition but override `name` attribute: + +```yaml + +services: + backend: + image: awesome/database + volumes: + - db-data + - metrics +volumes: + db-data: &default-volume + driver: default + name: "data" + metrics: + <<: *default-volume + name: "metrics" +``` + +## Extension + +Special extension fields can be of any format as long as their name starts with the `x-` character sequence. They can be used +within any structure in a Compose file. This is the sole exception for Compose implementations to silently ignore unrecognized field. + +```yaml +x-custom: + foo: + - bar + - zot + +services: + webapp: + image: awesome/webapp + x-foo: bar +``` + +The contents of such fields are unspecified by Compose specification, and can be used to enable custom features. Compose implementation to encounter an unknown extension field MUST NOT fail, but COULD warn about unknown field. + +For platform extensions, it is highly recommended to prefix extension by platform/vendor name, the same way browsers add +support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords) + +```yaml +service: + backend: + deploy: + placement: + x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo" + x-aws-region: "eu-west-3" + x-azure-region: "france-central" +``` + +### Informative Historical Notes + +This section is informative. At the time of writing, the following prefixes are known to exist: + +| prefix | vendor/organization | +| ---------- | ------------------- | +| docker | Docker | +| kubernetes | Kubernetes | + +### Using extensions as fragments + +With the support for extension fields, Compose file can be written as follows to improve readability of reused fragments: + +```yaml +x-logging: &default-logging + options: + max-size: "12m" + max-file: "5" + driver: json-file + +services: + frontend: + image: awesome/webapp + logging: *default-logging + backend: + image: awesome/database + logging: *default-logging +``` + +### specifying byte values + +Value express a byte value as a string in `{amount}{byte unit}` format: +The supported units are `b` (bytes), `k` or `kb` (kilo bytes), `m` or `mb` (mega bytes) and `g` or `gb` (giga bytes). + +``` + 2b + 1024kb + 2048k + 300m + 1gb +``` + +### specifying durations + +Value express a duration as a string in the in the form of `{value}{unit}`. +The supported units are `us` (microseconds), `ms` (milliseconds), `s` (seconds), `m` (minutes) and `h` (hours). +Value can can combine multiple values and using without separator. + +``` + 10ms + 40s + 1m30s + 1h5m30s20ms +``` + +## Interpolation + +Values in a Compose file can be set by variables, and interpolated at runtime. Compose files use a Bash-like +syntax `${VARIABLE}` + +Both `$VARIABLE` and `${VARIABLE}` syntax are supported. Default values can be defined inline using typical shell syntax: +latest + +- `${VARIABLE:-default}` evaluates to `default` if `VARIABLE` is unset or + empty in the environment. +- `${VARIABLE-default}` evaluates to `default` only if `VARIABLE` is unset + in the environment. + +Similarly, the following syntax allows you to specify mandatory variables: + +- `${VARIABLE:?err}` exits with an error message containing `err` if + `VARIABLE` is unset or empty in the environment. +- `${VARIABLE?err}` exits with an error message containing `err` if + `VARIABLE` is unset in the environment. + +Interpolation can also be nested: + +- `${VARIABLE:-${FOO}}` +- `${VARIABLE?$FOO}` +- `${VARIABLE:-${FOO:-default}}` + +Other extended shell-style features, such as `${VARIABLE/foo/bar}`, are not +supported by the Compose specification. + +You can use a `$$` (double-dollar sign) when your configuration needs a literal +dollar sign. This also prevents Compose from interpolating a value, so a `$$` +allows you to refer to environment variables that you don't want processed by +Compose. + +```yaml +web: + build: . + command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE" +``` + +If the Compose implementation can't resolve a substituted variable and no default value is defined, it MUST warn +the user and substitute the variable with an empty string. + +As any values in a Compose file can be interpolated with variable substitution, including compact string notation +for complex elements, interpolation MUST be applied _before_ merge on a per-file-basis. + ## Compose documentation - [User guide](../index.md) From 3c008117c34321d444770cd844f8583793ea01ed Mon Sep 17 00:00:00 2001 From: Ygor Perez de Oliveira Date: Mon, 21 Mar 2022 10:51:47 -0300 Subject: [PATCH 05/17] Add new step 1 "Exit MySQL" In the "Connect to MySQL" section, if you don't exit MySQL with the command `exit`, you can't proceed to create the container --- get-started/07_multi_container.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/get-started/07_multi_container.md b/get-started/07_multi_container.md index 4cc4c6b9a0..725a6e441f 100644 --- a/get-started/07_multi_container.md +++ b/get-started/07_multi_container.md @@ -110,13 +110,20 @@ address)? To figure it out, we're going to make use of the [nicolaka/netshoot](https://github.com/nicolaka/netshoot) container, which ships with a _lot_ of tools that are useful for troubleshooting or debugging networking issues. -1. Start a new container using the nicolaka/netshoot image. Make sure to connect it to the same network. + +1. Exit MySQL if you haven't already (if you have typed any thing before press `;` and hit enter). + + ```console + mysql> exit + ``` + +2. Start a new container using the nicolaka/netshoot image. Make sure to connect it to the same network. ```console $ docker run -it --network todo-app nicolaka/netshoot ``` -2. Inside the container, we're going to use the `dig` command, which is a useful DNS tool. We're going to look up +3. Inside the container, we're going to use the `dig` command, which is a useful DNS tool. We're going to look up the IP address for the hostname `mysql`. ```console From a4953322d2ac433442ccfddd75ace9fc3f5178a5 Mon Sep 17 00:00:00 2001 From: Ygor Perez de Oliveira Date: Sat, 26 Mar 2022 04:30:52 -0300 Subject: [PATCH 06/17] Moved intructions from line 112 to 101 Edit made based on usha-mandya comment on issue #14417 --- get-started/07_multi_container.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/get-started/07_multi_container.md b/get-started/07_multi_container.md index 725a6e441f..c15678cd00 100644 --- a/get-started/07_multi_container.md +++ b/get-started/07_multi_container.md @@ -98,8 +98,13 @@ For now, we will create the network first and attach the MySQL container at star +--------------------+ 5 rows in set (0.00 sec) ``` +Exit the MySQL shell to return to the shell on our machine. - Hooray! We have our `todos` database and it's ready for us to use! + ```console + mysql> exit + ``` + + Hooray! We have our `todos` database and it's ready for us to use! ## Connect to MySQL @@ -110,20 +115,13 @@ address)? To figure it out, we're going to make use of the [nicolaka/netshoot](https://github.com/nicolaka/netshoot) container, which ships with a _lot_ of tools that are useful for troubleshooting or debugging networking issues. - -1. Exit MySQL if you haven't already (if you have typed any thing before press `;` and hit enter). - - ```console - mysql> exit - ``` - -2. Start a new container using the nicolaka/netshoot image. Make sure to connect it to the same network. +1. Start a new container using the nicolaka/netshoot image. Make sure to connect it to the same network. ```console $ docker run -it --network todo-app nicolaka/netshoot ``` -3. Inside the container, we're going to use the `dig` command, which is a useful DNS tool. We're going to look up +2. Inside the container, we're going to use the `dig` command, which is a useful DNS tool. We're going to look up the IP address for the hostname `mysql`. ```console From fc28f7560a80c0333ffb6604cc10703dd301e715 Mon Sep 17 00:00:00 2001 From: Usha Mandya Date: Tue, 29 Mar 2022 12:55:29 +0100 Subject: [PATCH 07/17] Add build and deploy docs Signed-off-by: Usha Mandya --- _data/toc.yaml | 8 +- compose/compose-file/build.md | 305 +++++++++++++++++++++++++++++++++ compose/compose-file/deploy.md | 296 ++++++++++++++++++++++++++++++++ compose/compose-file/index.md | 235 ++++++++++++------------- 4 files changed, 721 insertions(+), 123 deletions(-) create mode 100644 compose/compose-file/build.md create mode 100644 compose/compose-file/deploy.md diff --git a/_data/toc.yaml b/_data/toc.yaml index f8bef9e5b3..1cb2fa0612 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1040,12 +1040,16 @@ reference: section: - path: /compose/compose-file/ title: Compose Specification - - path: /compose/compose-file/compose-versioning/ - title: About versions and upgrading + - path: /compose/compose-file/build/ + title: Compose file build + - path: /compose/compose-file/deploy/ + title: Compose file deploy - path: /compose/faq/ title: Frequently asked questions - sectiontitle: Legacy versions section: + - path: /compose/compose-file/compose-versioning/ + title: About versions and upgrading - path: /compose/compose-file/compose-file-v3/ title: Version 3 - path: /compose/compose-file/compose-file-v2/ diff --git a/compose/compose-file/build.md b/compose/compose-file/build.md new file mode 100644 index 0000000000..861a97b1fd --- /dev/null +++ b/compose/compose-file/build.md @@ -0,0 +1,305 @@ +--- +description: Compose file build reference +keywords: fig, composition, compose, docker +title: Compose file build reference +toc_max: 4 +toc_min: 2 +--- + +Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation +focusing on development use-case to run application on local machine will obviously also support (re)building +application from sources. The Compose Build specification allows to define the build process within a Compose file +in a portable way. + +## Definitions + +Compose Specification is extended to support an OPTIONAL `build` subsection on services. This section define the +build requirements for service container image. Only a subset of Compose file services MAY define such a Build +subsection, others being created based on `Image` attribute. When a Build subsection is present for a service, it +is *valid* for a Compose file to miss an `Image` attribute for corresponding service, as Compose implementation +can build image from source. + +Build can be either specified as a single string defining a context path, or as a detailed build definition. + +In the former case, the whole path is used as a Docker context to execute a docker build, looking for a canonical +`Dockerfile` at context root. Context path can be absolute or relative, and if so relative path MUST be resolved +from Compose file parent folder. As an absolute path prevent the Compose file to be portable, Compose implementation +SHOULD warn user accordingly. + +In the later case, build arguments can be specified, including an alternate `Dockerfile` location. This one can be +absolute or relative path. If Dockerfile path is relative, it MUST be resolved from context path. As an absolute +path prevent the Compose file to be portable, Compose implementation SHOULD warn user if an absolute alternate +Dockerfile path is used. + +## Consistency with Image + +When service definition do include both `Image` attribute and a `Build` section, Compose implementation can't +guarantee a pulled image is strictly equivalent to building the same image from sources. Without any explicit +user directives, Compose implementation with Build support MUST first try to pull Image, then build from source +if image was not found on registry. Compose implementation MAY offer options to customize this behaviour by user +request. + +## Publishing built images + +Compose implementation with Build support SHOULD offer an option to push built images to a registry. Doing so, it +MUST NOT try to push service images without an `Image` attribute. Compose implementation SHOULD warn user about +missing `Image` attribute which prevent image being pushed. + +Compose implementation MAY offer a mechanism to compute an `Image` attribute for service when not explicitly +declared in yaml file. In such a case, the resulting Compose configuration is considered to have a valid `Image` +attribute, whenever the actual raw yaml file doesn't explicitly declare one. + +## Illustrative sample + +The following sample illustrates Compose specification concepts with a concrete sample application. The sample is non-normative. + +```yaml +services: + frontend: + image: awesome/webapp + build: ./webapp + + backend: + image: awesome/database + build: + context: backend + dockerfile: ../backend.Dockerfile + + custom: + build: ~/custom +``` + +When used to build service images from source, such a Compose file will create three docker images: + +* `awesome/webapp` docker image is build using `webapp` sub-directory within Compose file parent folder as docker build context. Lack of a `Dockerfile` within this folder will throw an error. +* `awesome/database` docker image is build using `backend` sub-directory within Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to context path, which means for this sample `..` will resolve to Compose file parent folder, so `backend.Dockerfile` is a sibling file. +* a docker image is build using `custom` directory within user's HOME as docker context. Compose implementation warn user about non-portable path used to build image. + +On push, both `awesome/webapp` and `awesome/database` docker images are pushed to (default) registry. `custom` service image is skipped as no `Image` attribute is set and user is warned about this missing attribute. + +## Build definition + +The `build` element define configuration options that are applied by Compose implementations to build Docker image from source. +`build` can be specified either as a string containing a path to the build context or a detailed structure: + +```yml +services: + webapp: + build: ./dir +``` + +Using this string syntax, only the build context can be configured as a relative path to the Compose file's parent folder. +This path MUST be a directory and contain a `Dockerfile`. + +Alternatively `build` can be an object with fields defined as follow + +### context (REQUIRED) + +`context` defines either a path to a directory containing a Dockerfile, or a url to a git repository. + +When the value supplied is a relative path, it MUST be interpreted as relative to the location of the Compose file. +Compose implementations MUST warn user about absolute path used to define build context as those prevent Compose file +for being portable. + +```yml +build: + context: ./dir +``` + +### dockerfile + +`dockerfile` allows to set an alternate Dockerfile. A relative path MUST be resolved from the build context. +Compose implementations MUST warn user about absolute path used to define Dockerfile as those prevent Compose file +for being portable. + +```yml +build: + context: . + dockerfile: webapp.Dockerfile +``` + +### args + +`args` define build arguments, i.e. Dockerfile `ARG` values. + +Using following Dockerfile: + +```Dockerfile +ARG GIT_COMMIT +RUN echo "Based on commit: $GIT_COMMIT" +``` + +`args` can be set in Compose file under the `build` key to define `GIT_COMMIT`. `args` can be set a mapping or a list: + +```yml +build: + context: . + args: + GIT_COMMIT: cdc3b19 +``` + +```yml +build: + context: . + args: + - GIT_COMMIT=cdc3b19 +``` + +Value can be omitted when specifying a build argument, in which case its value at build time MUST be obtained by user interaction, +otherwise build arg won't be set when building the Docker image. + +```yml +args: + - GIT_COMMIT +``` + +### ssh + +`ssh` defines SSH authentications that the image builder SHOULD use during image build (e.g., cloning private repository) + +`ssh` property syntax can be either: +* `default` - let the builder connect to the ssh-agent. +* `ID=path` - a key/value definition of an ID and the associated path. Can be either a [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) file, or path to ssh-agent socket + +Simple `default` sample +```yaml +build: + context: . + ssh: + - default # mount the default ssh agent +``` +or +```yaml +build: + context: . + ssh: ["default"] # mount the default ssh agent +``` + +Using a custom id `myproject` with path to a local SSH key: +```yaml +build: + context: . + ssh: + - myproject=~/.ssh/myproject.pem +``` +Image builder can then rely on this to mount SSH key during build. +For illustration, [BuildKit extended syntax](https://github.com/compose-spec/compose-spec/pull/234/%5Bmoby/buildkit@master/frontend/dockerfile/docs/syntax.md#run---mounttypessh%5D(https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#run---mounttypessh)) can be used to mount ssh key set by ID and access a secured resource: + +`RUN --mount=type=ssh,id=myproject git clone ...` + +### cache_from + +`cache_from` defines a list of sources the Image builder SHOULD use for cache resolution. + +Cache location syntax MUST follow the global format `[NAME|type=TYPE[,KEY=VALUE]]`. Simple `NAME` is actually a shortcut notation for `type=registry,ref=NAME`. + +Compose Builder implementations MAY support custom types, the Compose Specification defines canonical types which MUST be supported: + +- `registry` to retrieve build cache from an OCI image set by key `ref` + + +```yml +build: + context: . + cache_from: + - alpine:latest + - type=local,src=path/to/cache + - type=gha +``` + +Unsupported caches MUST be ignored and not prevent user from building image. + +### cache_to + +`cache_to` defines a list of export locations to be used to share build cache with future builds. + +```yml +build: + context: . + cache_to: + - user/app:cache + - type=local,dest=path/to/cache +``` + +Cache target is defined using the same `type=TYPE[,KEY=VALUE]` syntax defined by [`cache_from`](#cache_from). + +Unsupported cache target MUST be ignored and not prevent user from building image. + +### extra_hosts + +`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](spec.md#extra_hosts). + +```yml +extra_hosts: + - "somehost:162.242.195.82" + - "otherhost:50.31.209.229" +``` + +Compose implementations MUST create matching entry with the IP address and hostname in the container's network +configuration, which means for Linux `/etc/hosts` will get extra lines: + +``` +162.242.195.82 somehost +50.31.209.229 otherhost +``` + +### isolation + +`isolation` specifies a build’s container isolation technology. Like [isolation](spec.md#isolation) supported values +are platform-specific. + +### labels + +`labels` add metadata to the resulting image. `labels` can be set either as an array or a map. + +reverse-DNS notation SHOULD be used to prevent labels from conflicting with those used by other software. + +```yml +build: + context: . + labels: + com.example.description: "Accounting webapp" + com.example.department: "Finance" + com.example.label-with-empty-value: "" +``` + +```yml +build: + context: . + labels: + - "com.example.description=Accounting webapp" + - "com.example.department=Finance" + - "com.example.label-with-empty-value" +``` + +### shm_size + +`shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify +as an integer value representing the number of bytes or as a string expressing a [byte value](spec.md#specifying-byte-values). + +```yml +build: + context: . + shm_size: '2gb' +``` + +```yaml +build: + context: . + shm_size: 10000000 +``` + +### target + +`target` defines the stage to build as defined inside a multi-stage `Dockerfile`. + +```yml +build: + context: . + target: prod +``` + +## Implementations + +* [docker-compose](https://docs.docker.com/compose) +* [buildX bake](https://docs.docker.com/buildx/working-with-buildx/) diff --git a/compose/compose-file/deploy.md b/compose/compose-file/deploy.md new file mode 100644 index 0000000000..af0bf5eb71 --- /dev/null +++ b/compose/compose-file/deploy.md @@ -0,0 +1,296 @@ +--- +description: Compose file deploy reference +keywords: fig, composition, compose, docker +title: Compose file deploy reference +toc_max: 4 +toc_min: 2 +--- + +Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation supporting +deployment of application model MAY require some additional metadata as the Compose application model is way too abstract +to reflect actual infrastructure needs per service, or lifecycle constraints. + +Compose Specification Deployment allows users to declare additional metadata on services so Compose implementations get +relevant data to allocate adequate resources on platform and configure them to match user's needs. + +## Definitions + +Compose Specification is extended to support an OPTIONAL `deploy` subsection on services. This section define runtime requirements +for a service. + +### endpoint_mode + +`endpoint_mode` specifies a service discovery method for external clients connecting to a service. Default and available values +are platform specific, anyway the Compose specification define two canonical values: + +* `endpoint_mode: vip`: Assigns the service a virtual IP (VIP) that acts as the front end for clients to reach the service + on a network. Platform routes requests between the client and nodes running the service, without client knowledge of how + many nodes are participating in the service or their IP addresses or ports. + +* `endpoint_mode: dnsrr`: Platform sets up DNS entries for the service such that a DNS query for the service name returns a + list of IP addresses (DNS round-robin), and the client connects directly to one of these. + +```yml +services: + frontend: + image: awesome/webapp + ports: + - "8080:80" + deploy: + mode: replicated + replicas: 2 + endpoint_mode: vip +``` + +### labels + +`labels` specifies metadata for the service. These labels MUST *only* be set on the service and *not* on any containers for the service. +This assumes the platform has some native concept of "service" that can match Compose application model. + +```yml +services: + frontend: + image: awesome/webapp + deploy: + labels: + com.example.description: "This label will appear on the web service" +``` + +### mode + +`mode` define the replication model used to run the service on platform. Either `global` (exactly one container per physical node) or `replicated` (a specified number of containers). The default is `replicated`. + +```yml +services: + frontend: + image: awesome/webapp + deploy: + mode: global +``` + +### placement + +`placement` specifies constraints and preferences for platform to select a physical node to run service containers. + +#### constraints + +`constraints` defines a REQUIRED property the platform's node MUST fulfill to run service container. Can be set either +by a list or a map with string values. + +```yml +deploy: + placement: + constraints: + - disktype=ssd +``` + +```yml +deploy: + placement: + constraints: + disktype: ssd +``` + +#### preferences + +`preferences` defines a property the platform's node SHOULD fulfill to run service container. Can be set either +by a list or a map with string values. + +```yml +deploy: + placement: + preferences: + - datacenter=us-east +``` + +```yml +deploy: + placement: + preferences: + datacenter: us-east +``` + +### replicas + +If the service is `replicated` (which is the default), `replicas` specifies the number of containers that SHOULD be +running at any given time. + +```yml +services: + fronted: + image: awesome/webapp + deploy: + mode: replicated + replicas: 6 +``` + +### resources + +`resources` configures physical resource constraints for container to run on platform. Those constraints can be configured +as a: + +- `limits`: The platform MUST prevent container to allocate more +- `reservations`: The platform MUST guarantee container can allocate at least the configured amount + +```yml +services: + frontend: + image: awesome/webapp + deploy: + resources: + limits: + cpus: '0.50' + memory: 50M + pids: 1 + reservations: + cpus: '0.25' + memory: 20M +``` + +#### cpus + +`cpus` configures a limit or reservation for how much of the available CPU resources (as number of cores) a container can use. + +#### memory + +`memory` configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](spec.md#specifying-byte-values). + +#### pids + +`pids` tunes a container’s PIDs limit, set as an integer. + +#### devices + +`devices` configures reservations of the devices a container can use. It contains a list of reservations, each set as an object with the following parameters: `capabilities`, `driver`, `count`, `device_ids` and `options`. + +Devices are reserved using a list of capabilities, making `capabilities` the only required field. A device MUST satisfy all the requested capabilities for a successful reservation. + +##### capabilities + +`capabilities` are set as a list of strings, expressing both generic and driver specific capabilities. +The following generic capabilities are recognized today: + +- `gpu`: Graphics accelerator +- `tpu`: AI accelerator + +To avoid name clashes, driver specific capabilities MUST be prefixed with the driver name. +For example, reserving an nVidia CUDA-enabled accelerator might look like this: + +```yml +deploy: + resources: + reservations: + devices: + - capabilities: ["nvidia-compute"] +``` + +##### driver + +A different driver for the reserved device(s) can be requested using `driver` field. The value is specified as a string. + +```yml +deploy: + resources: + reservations: + devices: + - capabilities: ["nvidia-compute"] + driver: nvidia +``` + +##### count + +If `count` is set to `all` or not specified, Compose implementations MUST reserve all devices that satisfy the requested capabilities. Otherwise, Compose implementations MUST reserve at least the number of devices specified. The value is specified as an integer. + +```yml +deploy: + resources: + reservations: + devices: + - capabilities: ["tpu"] + count: 2 +``` + +`count` and `device_ids` fields are exclusive. Compose implementations MUST return an error if both are specified. + +##### device_ids + +If `device_ids` is set, Compose implementations MUST reserve devices with the specified IDs providing they satisfy the requested capabilities. The value is specified as a list of strings. + +```yml +deploy: + resources: + reservations: + devices: + - capabilities: ["gpu"] + device_ids: ["GPU-f123d1c9-26bb-df9b-1c23-4a731f61d8c7"] +``` + +`count` and `device_ids` fields are exclusive. Compose implementations MUST return an error if both are specified. + +##### options + +Driver specific options can be set with `options` as key-value pairs. + +```yml +deploy: + resources: + reservations: + devices: + - capabilities: ["gpu"] + driver: gpuvendor + options: + virtualization: false +``` + +### restart_policy + +`restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose implementations MUST consider `restart` field set by service configuration. + +- `condition`: One of `none`, `on-failure` or `any` (default: `any`). +- `delay`: How long to wait between restart attempts, specified as a [duration](spec.md#specifying-durations) (default: 0). +- `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not + succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value. + For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts MUST be attempted. +- `window`: How long to wait before deciding if a restart has succeeded, specified as a [duration](#specifying-durations) (default: + decide immediately). + +```yml +deploy: + restart_policy: + condition: on-failure + delay: 5s + max_attempts: 3 + window: 120s +``` + +### rollback_config + +`rollback_config` configures how the service should be rollbacked in case of a failing update. + +- `parallelism`: The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously. +- `delay`: The time to wait between each container group's rollback (default 0s). +- `failure_action`: What to do if a rollback fails. One of `continue` or `pause` (default `pause`) +- `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s). +- `max_failure_ratio`: Failure rate to tolerate during a rollback (default 0). +- `order`: Order of operations during rollbacks. 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`). + +### update_config + +`update_config` configures how the service should be updated. Useful for configuring rolling updates. + +- `parallelism`: The number of containers to update at a time. +- `delay`: The time to wait between updating a group of containers. +- `failure_action`: What to do if an update fails. One of `continue`, `rollback`, or `pause` (default: `pause`). +- `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s). +- `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`). + +```yml +deploy: + update_config: + parallelism: 2 + delay: 10s + order: stop-first +``` diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 63c3f97ac6..31df90d680 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -4,7 +4,7 @@ keywords: fig, composition, compose, docker redirect_from: - /compose/yaml - /compose/compose-file/compose-file-v1/ -title: Compose file +title: Compose specification toc_max: 4 toc_min: 1 --- @@ -14,14 +14,6 @@ toc_min: 1 These topics describe the Docker Compose implementation of the Compose format. Docker Compose **1.27.0+** implements the format defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). Previous Docker Compose versions have support for several Compose file formats – 2, 2.x, and 3.x. The Compose specification is a unified 2.x and 3.x file format, aggregating properties across these formats. -## Compose and Docker compatibility matrix - -There are several versions of the Compose file format – 2, 2.x, and 3.x. The -table below provides a snapshot of various versions. For full details on what each version includes and -how to upgrade, see **[About versions and upgrading](compose-versioning.md)**. - -{% include content/compose-matrix.md %} - ## Status of this document This document specifies the Compose file format used to define multi-containers applications. Distribution of this document is unlimited. @@ -38,7 +30,7 @@ is Platform dependent and can only be confirmed at runtime. The definition of a properties in a Compose file, established by the [docker-compose](https://github.com/docker/compose) tool where the Compose file format was designed, doesn't offer any guarantee to the end-user attributes will be actually implemented. -The specification defines the expected configuration syntax and behaviour, but - until noted - supporting any of those is OPTIONAL. +The specification defines the expected configuration syntax and behavior, but - until noted - supporting any of those is OPTIONAL. A Compose implementation to parse a Compose file using unsupported attributes SHOULD warn user. We recommend implementors to support those running modes: @@ -51,15 +43,15 @@ to support those running modes: The Compose specification allows one to define a platform-agnostic container based application. Such an application is designed as a set of containers which have to both run together with adequate shared resources and communication channels. -Computing components of an application are defined as [Services](#Services-top-level-element). A Service is an abstract concept implemented on platforms by running the same container image (and configuration) one or more times. +Computing components of an application are defined as [Services](#services-top-level-element). A Service is an abstract concept implemented on platforms by running the same container image (and configuration) one or more times. -Services communicate with each other through [Networks](#Networks-top-level-element). In this specification, a Network is a platform capability abstraction to establish an IP route between containers within services connected together. Low-level, platform-specific networking options are grouped into the Network definition and MAY be partially implemented on some platforms. +Services communicate with each other through [Networks](#networks-top-level-element). In this specification, a Network is a platform capability abstraction to establish an IP route between containers within services connected together. Low-level, platform-specific networking options are grouped into the Network definition and MAY be partially implemented on some platforms. -Services store and share persistent data into [Volumes](#Volumes-top-level-element). The specification describes such a persistent data as a high-level filesystem mount with global options. Actual platform-specific implementation details are grouped into the Volumes definition and MAY be partially implemented on some platforms. +Services store and share persistent data into [Volumes](#volumes-top-level-element). The specification describes such a persistent data as a high-level filesystem mount with global options. Actual platform-specific implementation details are grouped into the Volumes definition and MAY be partially implemented on some platforms. -Some services require configuration data that is dependent on the runtime or platform. For this, the specification defines a dedicated concept: [Configs](#Configs-top-level-element). From a Service container point of view, Configs are comparable to Volumes, in that they are files mounted into the container. But the actual definition involves distinct platform resources and services, which are abstracted by this type. +Some services require configuration data that is dependent on the runtime or platform. For this, the specification defines a dedicated concept: [Configs](#configs-top-level-element). From a Service container point of view, Configs are comparable to Volumes, in that they are files mounted into the container. But the actual definition involves distinct platform resources and services, which are abstracted by this type. -A [Secret](#Secrets-top-level-element) is a specific flavour of configuration data for sensitive data that SHOULD NOT be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose specification. +A [Secret](#secrets-top-level-element) is a specific flavor of configuration data for sensitive data that SHOULD NOT be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose specification. Distinction within Volumes, Configs and Secret allows implementations to offer a comparable abstraction at service level, but cover the specific configuration of adequate platform resources for well identified data usages. @@ -105,7 +97,7 @@ The example application is composed of the following parts: - 1 persistent volume, attached to the backend - 2 networks -```yaml +```yml services: frontend: image: awesome/webapp @@ -241,7 +233,7 @@ prefer the most recent schema at the time it has been designed. Compose implementations SHOULD validate whether they can fully parse the Compose file. If some fields are unknown, typically because the Compose file was written with fields defined by a newer version of the specification, Compose implementations -SHOULD warn the user. Compose implementations MAY offer options to ignore unknown fields (as defined by ["loose"](#Requirements-and-optional-attributes) mode). +SHOULD warn the user. Compose implementations MAY offer options to ignore unknown fields (as defined by ["loose"](#requirements-and-optional-attributes) mode). ## Name top-level element @@ -250,9 +242,9 @@ Compose implementations MUST offer a way for user to override this name, and SHO default project name, to be used if the top-level `name` element is not set. Whenever project name is defined by top-level `name` or by some custom mechanism, it MUST be exposed for -[interpolation](#Interpolation) and environment variable resolution as `COMPOSE_PROJECT_NAME` +[interpolation](#interpolation) and environment variable resolution as `COMPOSE_PROJECT_NAME` -```yaml +```yml services: foo: image: busybox @@ -277,26 +269,27 @@ Each service MAY also include a Build section, which defines how to create the D Compose implementations MAY support building docker images using this service definition. If not implemented the Build section SHOULD be ignored and the Compose file MUST still be considered valid. -Build support is an OPTIONAL aspect of the Compose specification, and is described in detail [here](build.md) +Build support is an OPTIONAL aspect of the Compose specification, and is +described in detail in the [Build support](build.md) documentation. Each Service defines runtime constraints and requirements to run its containers. The `deploy` section groups these constraints and allows the platform to adjust the deployment strategy to best match containers' needs with available resources. -Deploy support is an OPTIONAL aspect of the Compose specification, and is described in detail [here](deploy.md). If +Deploy support is an OPTIONAL aspect of the Compose specification, and is +described in detail in the [Deployment support](deploy.md) documentation. not implemented the Deploy section SHOULD be ignored and the Compose file MUST still be considered valid. - ### build -`build` specifies the build configuration for creating container image from source, as defined [here](build.md). +`build` specifies the build configuration for creating container image from source, as defined in the [Build support](build.md) documentation. ### blkio_config `blkio_config` defines a set of configuration options to set block IO limits for this service. -```yaml +```yml services: foo: image: busybox @@ -374,7 +367,7 @@ on Linux kernel. `cpu_rt_runtime` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either an integer value using microseconds as unit or a [duration](#specifying-durations). -```yaml +```yml cpu_rt_runtime: '400ms' cpu_rt_runtime: 95000` ``` @@ -384,7 +377,7 @@ an integer value using microseconds as unit or a [duration](#specifying-duration `cpu_rt_period` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either an integer value using microseconds as unit or a [duration](#specifying-durations). -```yaml +```yml cpu_rt_period: '1400us' cpu_rt_period: 11000` ``` @@ -469,7 +462,7 @@ access to the `my_config` and `my_other_config` configs. The value of already been defined in the platform. If the external config does not exist, the deployment MUST fail. -```yaml +```yml services: redis: image: redis:latest @@ -500,7 +493,7 @@ container, sets the mode to `0440` (group-readable) and sets the user and group to `103`. The `redis` service does not have access to the `my_other_config` config. -```yaml +```yml services: redis: image: redis:latest @@ -523,7 +516,7 @@ You can grant a service access to multiple configs, and you can mix long and sho `container_name` is a string that specifies a custom container name, rather than a generated default name. -```yaml +```yml container_name: my-web-container ``` @@ -542,7 +535,7 @@ protocols for custom use-cases. The `credential_spec` must be in the format `file://` or `registry://`. -```yaml +```yml credential_spec: file: my-credential-spec.json ``` @@ -555,7 +548,7 @@ the daemon's host. A registry value with the given name must be located in: The following example loads the credential spec from a value named `my-credential-spec` in the registry: -```yaml +```yml credential_spec: registry: my-credential-spec ``` @@ -565,7 +558,7 @@ credential_spec: 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: -```yaml +```yml services: myservice: image: myimage:latest @@ -594,7 +587,7 @@ Service dependencies cause the following behaviors: Simple example: -```yaml +```yml services: web: build: . @@ -639,7 +632,7 @@ Service dependencies cause the following behaviors: Simple example: -```yaml +```yml services: web: build: . @@ -671,7 +664,7 @@ Compose implementations MUST guarantee dependency services marked with The format is the same format the Linux kernel specifies in the [Control Groups Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html). -```yaml +```yml device_cgroup_rules: - 'c 1:3 mr' - 'a 7:* rmw' @@ -682,7 +675,7 @@ device_cgroup_rules: `devices` defines a list of device mappings for created containers in the form of `HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]`. -```yaml +```yml devices: - "/dev/ttyUSB0:/dev/ttyUSB0" - "/dev/sda:/dev/xvda:rwm" @@ -692,11 +685,11 @@ devices: `dns` defines custom DNS servers to set on the container network interface configuration. Can be a single value or a list. -```yaml +```yml dns: 8.8.8.8 ``` -```yaml +```yml dns: - 8.8.8.8 - 9.9.9.9 @@ -706,7 +699,7 @@ dns: `dns_opt` list custom DNS options to be passed to the container’s DNS resolver (`/etc/resolv.conf` file on Linux). -```yaml +```yml dns_opt: - use-vc - no-tld-query @@ -716,11 +709,11 @@ dns_opt: `dns` defines custom DNS search domains to set on container network interface configuration. Can be a single value or a list. -```yaml +```yml dns_search: example.com ``` -```yaml +```yml dns_search: - dc1.example.com - dc2.example.com @@ -737,14 +730,14 @@ Compose implementations MUST clear out any default command on the Docker image - in the Dockerfile - when `entrypoint` is configured by a Compose file. If [`command`](#command) is also set, it is used as parameter to `entrypoint` as a replacement for Docker image's `CMD` -```yaml +```yml entrypoint: /code/entrypoint.sh ``` The entrypoint can also be a list, in a manner similar to [Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd): -```yaml +```yml entrypoint: - php - -d @@ -758,14 +751,14 @@ entrypoint: `env_file` adds environment variables to the container based on file content. -```yaml +```yml env_file: .env ``` `env_file` can also be a list. The files in the list MUST be processed from the top down. For the same variable specified in two env files, the value from the last file in the list MUST stand. -```yaml +```yml env_file: - ./a.env - ./b.env @@ -808,7 +801,7 @@ is unset and will be removed from the service container environment. Map syntax: -```yaml +```yml environment: RACK_ENV: development SHOW: "true" @@ -817,7 +810,7 @@ environment: Array syntax: -```yaml +```yml environment: - RACK_ENV=development - SHOW=true @@ -832,7 +825,7 @@ When both `env_file` and `environment` are set for a service, values set by `env accessible to linked services and SHOULD NOT be published to the host machine. Only the internal container ports can be specified. -```yaml +```yml expose: - "3000" - "8000" @@ -846,7 +839,7 @@ defined with a required `service` and an optional `file` key. ```yaml extends: - file: common.yaml + file: common.yml service: webapp ``` @@ -1038,7 +1031,7 @@ Any other allowed keys in the service definition should be treated as scalars. `external_links` define the name of an existing service to retrieve using the platform lookup mechanism. An alias of the form `SERVICE:ALIAS` can be specified. -```yaml +```yml external_links: - redis - database:mysql @@ -1050,7 +1043,7 @@ external_links: `extra_hosts` adds hostname mappings to the container network interface configuration (`/etc/hosts` for Linux). Values MUST set hostname and IP address for additional hosts in the form of `HOSTNAME:IP`. -```yaml +```yml extra_hosts: - "somehost:162.242.195.82" - "otherhost:50.31.209.229" @@ -1072,7 +1065,7 @@ An example of where this is useful is when multiple containers (running as diffe the same file on a shared volume. That file can be owned by a group shared by all the containers, and specified in `group_add`. -```yaml +```yml services: myservice: image: alpine @@ -1090,7 +1083,7 @@ service are "healthy". This overrides [HEALTHCHECK Dockerfile instruction](https://docs.docker.com/engine/reference/builder/#healthcheck) set by the service's Docker image. -```yaml +```yml healthcheck: test: ["CMD", "curl", "-f", "http://localhost"] interval: 1m30s @@ -1105,7 +1098,7 @@ healthcheck: 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. -```yaml +```yml # Hit the local web app test: ["CMD", "curl", "-f", "http://localhost"] ``` @@ -1113,18 +1106,18 @@ test: ["CMD", "curl", "-f", "http://localhost"] Using `CMD-SHELL` will run the command configured as a string using the container's default shell (`/bin/sh` for Linux). Both forms below are equivalent: -```yaml +```yml test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] ``` -```yaml +```yml test: curl -f https://localhost || exit 1 ``` `NONE` disable the healthcheck, and is mostly useful to disable Healthcheck set by image. Alternatively the healthcheck set by the image can be disabled by setting `disable: true`: -```yaml +```yml healthcheck: disable: true ``` @@ -1139,7 +1132,7 @@ healthcheck: [addressable image format](https://github.com/opencontainers/org/blob/master/docs/docs/introduction/digests.md), as `[/][/][:|@]`. -```yaml +```yml image: redis image: redis:5 image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7 @@ -1160,7 +1153,7 @@ without build support MUST fail when `image` is missing from the Compose file. `init` run an init process (PID 1) inside the container that forwards signals and reaps processes. Set this option to `true` to enable this feature for the service. -```yaml +```yml services: web: image: alpine:latest @@ -1180,7 +1173,7 @@ which MUST be implemented as described if supported: - `service:{name}` which makes the container join another (`shareable`) container's IPC namespace. -```yaml +```yml ipc: "shareable" ipc: "service:[service name]" ``` @@ -1196,14 +1189,14 @@ which MUST be implemented as described if supported: It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software. -```yaml +```yml labels: com.example.description: "Accounting webapp" com.example.department: "Finance" com.example.label-with-empty-value: "" ``` -```yaml +```yml labels: - "com.example.description=Accounting webapp" - "com.example.department=Finance" @@ -1223,7 +1216,7 @@ result in a runtime error. `links` defines a network link to containers in another service. Either specify both the service name and a link alias (`SERVICE:ALIAS`), or just the service name. -```yaml +```yml web: links: - db @@ -1247,7 +1240,7 @@ Links also express implicit dependency between services in the same way as `logging` defines the logging configuration for the service. -```yaml +```yml logging: driver: syslog options: @@ -1266,7 +1259,7 @@ specification define specific values which MUST be implemented as described if s - `host` which gives the container raw access to host's network interface - `service:{name}` which gives the containers access to the specified service only -```yaml +```yml network_mode: "host" network_mode: "none" network_mode: "service:[service name]" @@ -1277,7 +1270,7 @@ specification define specific values which MUST be implemented as described if s `networks` defines the networks that service containers are attached to, referencing entries under the [top-level `networks` key](#networks-top-level-element). -```yaml +```yml services: some-service: networks: @@ -1297,7 +1290,7 @@ Since `aliases` are network-scoped, the same service can have different aliases The general format is shown here: -```yaml +```yml services: some-service: networks: @@ -1314,7 +1307,7 @@ In the example below, service `frontend` will be able to reach the `backend` ser the hostname `backend` or `database` on the `back-tier` network, and service `monitoring` will be able to reach same `backend` service at `db` or `mysql` on the `admin` network. -```yaml +```yml services: frontend: image: awesome/webapp @@ -1350,7 +1343,7 @@ Specify a static IP address for containers for this service when joining the net The corresponding network configuration in the [top-level networks section](#networks) MUST have an `ipam` block with subnet configurations covering each static address. -```yaml +```yml services: frontend: image: awesome/webapp @@ -1472,7 +1465,7 @@ _DEPRECATED: use [deploy.reservations.pids](deploy.md#pids)_ `pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs. -```yaml +```yml pids_limit: 10 ``` @@ -1482,7 +1475,7 @@ pids_limit: 10 Compose implementation MUST use this attribute when declared to determine which version of the image will be pulled and/or on which platform the service’s build will be performed. -```yaml +```yml platform: osx platform: windows/amd64 platform: linux/arm64/v8 @@ -1516,7 +1509,7 @@ with [yaml base-60 float](https://yaml.org/type/float.html). Samples: -```yaml +```yml ports: - "3000" - "3000-3005" @@ -1542,7 +1535,7 @@ expressed in the short form. - `protocol`: the port protocol (`tcp` or `udp`), unspecified means any protocol - `mode`: `host` for publishing a host port on each node, or `ingress` for a port to be load balanced. -```yaml +```yml ports: - target: 80 host_ip: 127.0.0.1 @@ -1595,7 +1588,7 @@ If `pull_policy` and `build` both presents, Compose implementations SHOULD build - `unless-stopped`: The policy restarts a container irrespective of the exit code but will stop restarting when the service is stopped or removed. -```yaml +```yml restart: "no" restart: always restart: on-failure @@ -1609,7 +1602,7 @@ If `pull_policy` and `build` both presents, Compose implementations SHOULD build The value of `runtime` is specific to implementation. For example, `runtime` can be the name of [an implementation of OCI Runtime Spec](https://github.com/opencontainers/runtime-spec/blob/master/implementations.md), such as "runc". -```yaml +```yml web: image: busybox:latest command: true @@ -1641,7 +1634,7 @@ The following example uses the short syntax to grant the `frontend` service access to the `server-certificate` secret. The value of `server-certificate` is set to the contents of the file `./server.cert`. -```yaml +```yml services: frontend: image: awesome/webapp @@ -1672,7 +1665,7 @@ within the container, sets the mode to `0440` (group-readable) and sets the user to `103`. The value of `server-certificate` secret is provided by the platform through a lookup and the secret lifecycle not directly managed by the Compose implementation. -```yaml +```yml services: frontend: image: awesome/webapp @@ -1695,7 +1688,7 @@ Such grant must be explicit within service specification as [secrets](#secrets) `security_opt` overrides the default labeling scheme for each container. -```yaml +```yml security_opt: - label:user:USER - label:role:ROLE @@ -1717,7 +1710,7 @@ handle SIGTERM (or whichever stop signal has been specified with [`stop_signal`](#stopsignal)), before sending SIGKILL. Specified as a [duration](#specifying-durations). -```yaml +```yml stop_grace_period: 1s stop_grace_period: 1m30s ``` @@ -1729,7 +1722,7 @@ Default value is 10 seconds for the container to exit before sending SIGKILL. `stop_signal` defines the signal that the Compose implementation MUST use to stop the service containers. If unset containers are stopped by the Compose Implementation by sending `SIGTERM`. -```yaml +```yml stop_signal: SIGUSR1 ``` @@ -1737,7 +1730,7 @@ stop_signal: SIGUSR1 `storage_opt` defines storage driver options for a service. -```yaml +```yml storage_opt: size: '1G' ``` @@ -1746,13 +1739,13 @@ storage_opt: `sysctls` defines kernel parameters to set in the container. `sysctls` can use either an array or a map. -```yaml +```yml sysctls: net.core.somaxconn: 1024 net.ipv4.tcp_syncookies: 0 ``` -```yaml +```yml sysctls: - net.core.somaxconn=1024 - net.ipv4.tcp_syncookies=0 @@ -1767,11 +1760,11 @@ parameters (sysctls) at runtime](https://docs.docker.com/engine/reference/comman `tmpfs` mounts a temporary file system inside the container. Can be a single value or a list. -```yaml +```yml tmpfs: /run ``` -```yaml +```yml tmpfs: - /run - /tmp @@ -1786,7 +1779,7 @@ tmpfs: `ulimits` overrides the default ulimits for a container. Either specifies as a single limit as an integer or soft/hard limits as a mapping. -```yaml +```yml ulimits: nproc: 65535 nofile: @@ -1804,7 +1797,7 @@ if not set, `root`. `userns_mode` sets the user namespace for the service. Supported values are platform specific and MAY depend on platform configuration -```yaml +```yml userns_mode: "host" ``` @@ -1821,7 +1814,7 @@ volume MUST be declared in the [top-level `volumes` key](#volumes-top-level-elem This example shows a named volume (`db-data`) being used by the `backend` service, and a bind mount defined for a single service -```yaml +```yml services: backend: image: awesome/backend @@ -1916,7 +1909,7 @@ Services can connect to networks by specifying the network name under the servic In the following example, at runtime, networks `front-tier` and `back-tier` will be created and the `frontend` service connected to the `front-tier` network and the `back-tier` network. -```yaml +```yml services: frontend: image: awesome/webapp @@ -1934,7 +1927,7 @@ networks: `driver` specifies which driver should be used for this network. Compose implementations MUST return an error if the driver is not available on the platform. -```yaml +```yml driver: overlay ``` @@ -1951,7 +1944,7 @@ the scope of the Compose implementation. To use them one MUST define an external an alias that the Compose implementation can use (`hostnet` or `nonet` in the following examples), then grant the service access to that network using its alias. -```yaml +```yml services: web: networks: @@ -1963,7 +1956,7 @@ networks: name: host ``` -```yaml +```yml services: web: ... @@ -1981,7 +1974,7 @@ networks: `driver_opts` specifies a list of options as key-value pairs to pass to the driver for this network. These options are driver-dependent - consult the driver's documentation for more information. Optional. -```yaml +```yml driver_opts: foo: "bar" baz: 1 @@ -1993,7 +1986,7 @@ If `attachable` is set to `true`, then standalone containers SHOULD be able atta If a standalone container attaches to the network, it can communicate with services and other standalone containers that are also attached to the network. -```yaml +```yml networks: mynet1: driver: overlay @@ -2018,7 +2011,7 @@ networks: A full example: -```yaml +```yml ipam: driver: default config: @@ -2045,14 +2038,14 @@ Add metadata to containers using Labels. Can use either an array or a dictionary Users SHOULD use reverse-DNS notation to prevent labels from conflicting with those used by other software. -```yaml +```yml labels: com.example.description: "Financial transaction network" com.example.department: "Finance" com.example.label-with-empty-value: "" ``` -```yaml +```yml labels: - "com.example.description=Financial transaction network" - "com.example.department=Finance" @@ -2070,7 +2063,7 @@ In the example below, `proxy` is the gateway to the outside world. Instead of at implementations SHOULD interrogate the platform for an existing network simply called `outside` and connect the `proxy` service's containers to it. -```yaml +```yml services: proxy: @@ -2093,7 +2086,7 @@ networks: `name` sets 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 project name. -```yaml +```yml networks: network1: name: my-app-net @@ -2102,7 +2095,7 @@ networks: It can also be used in conjunction with the `external` property to define the platform network that the Compose implementation should retrieve, typically by using a parameter so the Compose file doesn't need to hard-code runtime specific values: -```yaml +```yml networks: network1: external: true @@ -2118,7 +2111,7 @@ The `volumes` section allows the configuration of named volumes that can be reus an example of a two-service setup where a database's data directory is shared with another service as a volume named `db-data` so that it can be periodically backed up: -```yaml +```yml services: backend: image: awesome/database @@ -2141,7 +2134,7 @@ creating a volume. Optionally, you can configure it with the following keys: Specify which volume driver should be used for this volume. Default and available values are platform specific. If the driver is not available, the Compose implementation MUST return an error and stop application deployment. -```yaml +```yml driver: foobar ``` @@ -2149,7 +2142,7 @@ driver: foobar `driver_opts` specifies a list of options as key-value pairs to pass to the driver for this volume. Those options are driver-dependent. -```yaml +```yml volumes: example: driver_opts: @@ -2168,7 +2161,7 @@ In the example below, instead of attempting to create a volume called `{project_name}_db-data`, Compose looks for an existing volume simply called `db-data` and mounts it into the `backend` service's containers. -```yaml +```yml services: backend: image: awesome/database @@ -2187,14 +2180,14 @@ volumes: It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software. -```yaml +```yml labels: com.example.description: "Database volume" com.example.department: "IT/Ops" com.example.label-with-empty-value: "" ``` -```yaml +```yml labels: - "com.example.description=Database volume" - "com.example.department=IT/Ops" @@ -2208,7 +2201,7 @@ Compose implementation MUST set `com.docker.compose.project` and `com.docker.com `name` 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. -```yaml +```yml volumes: data: name: "my-app-data" @@ -2217,7 +2210,7 @@ volumes: It can also be used in conjunction with the `external` property. Doing so the name of the volume used to lookup for actual volume on platform is set separately from the name used to refer to it within the Compose file: -```yaml +```yml volumes: db-data: external: @@ -2227,7 +2220,7 @@ volumes: This make it possible to make this lookup name a parameter of a Compose file, so that the model ID for volume is hard-coded but the actual volume ID on platform is set at runtime during deployment: -```yaml +```yml volumes: db-data: external: @@ -2262,7 +2255,7 @@ and `my_second_config` MUST already exist on Platform and value will be obtained In this example, `server-http_config` is created as `_http_config` when the application is deployed, by registering content of the `httpd.conf` as configuration data. -```yaml +```yml configs: http_config: file: ./httpd.conf @@ -2270,7 +2263,7 @@ configs: Alternatively, `http_config` can be declared as external, doing so Compose implementation will lookup `http_config` to expose configuration data to relevant services. -```yaml +```yml configs: http_config: external: true @@ -2281,7 +2274,7 @@ example modifies the previous one to lookup for config using a parameter `HTTP_C so the actual lookup key will be set at deployment time by [interpolation](#interpolation) of variables, but exposed to containers as hard-coded ID `http_config`. -```yaml +```yml configs: http_config: external: true @@ -2307,7 +2300,7 @@ application. The source of the secret is either `file` or `external`. In this example, `server-certificate` is created as `_server-certificate` when the application is deployed, by registering content of the `server.cert` as a platform secret. -```yaml +```yml secrets: server-certificate: file: ./server.cert @@ -2315,7 +2308,7 @@ secrets: Alternatively, `server-certificate` can be declared as external, doing so Compose implementation will lookup `server-certificate` to expose secret to relevant services. -```yaml +```yml secrets: server-certificate: external: true @@ -2326,7 +2319,7 @@ example modifies the previous one to look up for secret using a parameter `CERTI so the actual lookup key will be set at deployment time by [interpolation](#interpolation) of variables, but exposed to containers as hard-coded ID `server-certificate`. -```yaml +```yml secrets: server-certificate: external: true @@ -2339,7 +2332,7 @@ Compose file need to explicitly grant access to the secrets to relevant services It is possible to re-use configuration fragments using [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2765878). -```yaml +```yml volumes: db-data: &default-volume driver: default @@ -2353,7 +2346,7 @@ It is also possible to partially override values set by anchor reference using t [YAML merge type](http://yaml.org/type/merge.html). In following example, `metrics` volume specification uses alias to avoid repetition but override `name` attribute: -```yaml +```yml services: backend: @@ -2375,7 +2368,7 @@ volumes: Special extension fields can be of any format as long as their name starts with the `x-` character sequence. They can be used within any structure in a Compose file. This is the sole exception for Compose implementations to silently ignore unrecognized field. -```yaml +```yml x-custom: foo: - bar @@ -2392,7 +2385,7 @@ The contents of such fields are unspecified by Compose specification, and can be For platform extensions, it is highly recommended to prefix extension by platform/vendor name, the same way browsers add support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords) -```yaml +```yml service: backend: deploy: @@ -2415,7 +2408,7 @@ This section is informative. At the time of writing, the following prefixes are With the support for extension fields, Compose file can be written as follows to improve readability of reused fragments: -```yaml +```yml x-logging: &default-logging options: max-size: "12m" @@ -2491,7 +2484,7 @@ dollar sign. This also prevents Compose from interpolating a value, so a `$$` allows you to refer to environment variables that you don't want processed by Compose. -```yaml +```yml web: build: . command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE" From 5636e8e678c6bcb9273f33857419abfdde9b8158 Mon Sep 17 00:00:00 2001 From: Usha Mandya Date: Tue, 29 Mar 2022 14:37:44 +0100 Subject: [PATCH 08/17] Fix broken xrefs, curate compose spec overview Signed-off-by: Usha Mandya --- compose/compose-file/build.md | 6 +++--- compose/compose-file/deploy.md | 6 ++++-- compose/compose-file/index.md | 26 ++++++++++++++------------ 3 files changed, 21 insertions(+), 17 deletions(-) diff --git a/compose/compose-file/build.md b/compose/compose-file/build.md index 861a97b1fd..a02ee140f3 100644 --- a/compose/compose-file/build.md +++ b/compose/compose-file/build.md @@ -227,7 +227,7 @@ Unsupported cache target MUST be ignored and not prevent user from building imag ### extra_hosts -`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](spec.md#extra_hosts). +`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](index.md#extra_hosts). ```yml extra_hosts: @@ -245,7 +245,7 @@ configuration, which means for Linux `/etc/hosts` will get extra lines: ### isolation -`isolation` specifies a build’s container isolation technology. Like [isolation](spec.md#isolation) supported values +`isolation` specifies a build’s container isolation technology. Like [isolation](index.md#isolation) supported values are platform-specific. ### labels @@ -275,7 +275,7 @@ build: ### shm_size `shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify -as an integer value representing the number of bytes or as a string expressing a [byte value](spec.md#specifying-byte-values). +as an integer value representing the number of bytes or as a string expressing a [byte value](index.md#specifying-byte-values). ```yml build: diff --git a/compose/compose-file/deploy.md b/compose/compose-file/deploy.md index af0bf5eb71..f0371d9e61 100644 --- a/compose/compose-file/deploy.md +++ b/compose/compose-file/deploy.md @@ -153,7 +153,9 @@ services: #### memory -`memory` configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](spec.md#specifying-byte-values). +`memory` configures a limit or reservation on the amount of memory a container +can allocate, set as a string expressing a +[byte value](index.md#specifying-byte-values). #### pids @@ -247,7 +249,7 @@ deploy: `restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose implementations MUST consider `restart` field set by service configuration. - `condition`: One of `none`, `on-failure` or `any` (default: `any`). -- `delay`: How long to wait between restart attempts, specified as a [duration](spec.md#specifying-durations) (default: 0). +- `delay`: How long to wait between restart attempts, specified as a [duration](index.md#specifying-durations) (default: 0). - `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value. For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts MUST be attempted. diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 31df90d680..76666c39f1 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -9,25 +9,27 @@ toc_max: 4 toc_min: 1 --- -## Reference and guidelines - -These topics describe the Docker Compose implementation of the Compose format. -Docker Compose **1.27.0+** implements the format defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). Previous Docker Compose versions have support for several Compose file formats – 2, 2.x, and 3.x. The Compose specification is a unified 2.x and 3.x file format, aggregating properties across these formats. +The Compose file is a [YAML](https://yaml.org){: target="_blank" rel="noopener" class="_"} file defining services, +networks, and volumes for a Docker application. The latest and recommended +version of the Compose file format is defined by the [Compose +Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md){: +target="_blank" rel="noopener" class="_"}. The Compose spec merges the legacy +2.x and 3.x versions, aggregating properties across these formats and is implemented by **Compose 1.27.0+**. ## Status of this document This document specifies the Compose file format used to define multi-containers applications. Distribution of this document is unlimited. -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119){: target="_blank" rel="noopener" class="_"}. ### Requirements and optional attributes -The Compose specification includes properties designed to target a local [OCI](https://opencontainers.org/) container runtime, +The Compose specification includes properties designed to target a local [OCI](https://opencontainers.org/){: target="_blank" rel="noopener" class="_"} container runtime, exposing Linux kernel specific configuration options, but also some Windows container specific properties, as well as cloud platform features related to resource placement on a cluster, replicated application distribution and scalability. We acknowledge that no Compose implementation is expected to support **all** attributes, and that support for some properties is Platform dependent and can only be confirmed at runtime. The definition of a versioned schema to control the supported -properties in a Compose file, established by the [docker-compose](https://github.com/docker/compose) tool where the Compose +properties in a Compose file, established by the [docker-compose](https://github.com/docker/compose){: target="_blank" rel="noopener" class="_"} tool where the Compose file format was designed, doesn't offer any guarantee to the end-user attributes will be actually implemented. The specification defines the expected configuration syntax and behavior, but - until noted - supporting any of those is OPTIONAL. @@ -662,7 +664,7 @@ Compose implementations MUST guarantee dependency services marked with `device_cgroup_rules` defines a list of device cgroup rules for this container. The format is the same format the Linux kernel specifies in the [Control Groups -Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html). +Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html){: target="_blank" rel="noopener" class="_"}. ```yml device_cgroup_rules: @@ -1505,7 +1507,7 @@ Either specify both ports (`HOST:CONTAINER`), or just the container port. In the Compose implementation SHOULD automatically allocate any unassigned host port. `HOST:CONTAINER` SHOULD always be specified as a (quoted) string, to avoid conflicts -with [yaml base-60 float](https://yaml.org/type/float.html). +with [yaml base-60 float](https://yaml.org/type/float.html){: target="_blank" rel="noopener" class="_"}. Samples: @@ -1600,7 +1602,7 @@ If `pull_policy` and `build` both presents, Compose implementations SHOULD build `runtime` specifies which runtime to use for the service’s containers. The value of `runtime` is specific to implementation. -For example, `runtime` can be the name of [an implementation of OCI Runtime Spec](https://github.com/opencontainers/runtime-spec/blob/master/implementations.md), such as "runc". +For example, `runtime` can be the name of [an implementation of OCI Runtime Spec](https://github.com/opencontainers/runtime-spec/blob/master/implementations.md){: target="_blank" rel="noopener" class="_"}, such as "runc". ```yml web: @@ -1617,7 +1619,7 @@ web: ### secrets -`secrets` grants access to sensitive data defined by [secrets](secrets) on a per-service basis. Two +`secrets` grants access to sensitive data defined by [secrets](#secrets) on a per-service basis. Two different syntax variants are supported: the short syntax and the long syntax. Compose implementations MUST report an error if the secret doesn't exist on the platform or isn't defined in the @@ -2383,7 +2385,7 @@ services: The contents of such fields are unspecified by Compose specification, and can be used to enable custom features. Compose implementation to encounter an unknown extension field MUST NOT fail, but COULD warn about unknown field. For platform extensions, it is highly recommended to prefix extension by platform/vendor name, the same way browsers add -support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords) +support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords){: target="_blank" rel="noopener" class="_"}. ```yml service: From 8bdda2079dcbe195af6a60c6291d6bd7b6f9d453 Mon Sep 17 00:00:00 2001 From: Nitin Gouda <90847875+shaggyyy2002@users.noreply.github.com> Date: Wed, 30 Mar 2022 19:34:33 +0530 Subject: [PATCH 09/17] Update ecs-integration.md --- cloud/ecs-integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloud/ecs-integration.md b/cloud/ecs-integration.md index c5106241d2..1d694b7478 100644 --- a/cloud/ecs-integration.md +++ b/cloud/ecs-integration.md @@ -10,7 +10,7 @@ toc_max: 2 ## Overview -The Docker Compose CLI enables developers to use native Docker commands to run applications in Amazon EC2 Container Service (ECS) when building cloud-native applications. +The Docker Compose CLI enables developers to use native Docker commands to run applications in Amazon Elastic Container Service (ECS) when building cloud-native applications. The integration between Docker and Amazon ECS allows developers to use the Docker Compose CLI to: From bca3ed715cee3dd0de73dbbcdb3b6a5709f5357f Mon Sep 17 00:00:00 2001 From: shjin404 <50716604+shjin404@users.noreply.github.com> Date: Wed, 30 Mar 2022 22:50:52 -0700 Subject: [PATCH 10/17] Update 06 bind mount page Updated the instruction to ensure running the command from the app directory. --- get-started/06_bind_mounts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/06_bind_mounts.md b/get-started/06_bind_mounts.md index 741f2ea978..bacab743bf 100644 --- a/get-started/06_bind_mounts.md +++ b/get-started/06_bind_mounts.md @@ -40,7 +40,7 @@ So, let's do it! 1. Make sure you don't have any previous `getting-started` containers running. -2. Run the following command. We'll explain what's going on afterwards: +2. Run the following command from the app directory. We'll explain what's going on afterwards: ```console $ docker run -dp 3000:3000 \ From 1cf511078df0c46ab4f336a00cccb8d555e36236 Mon Sep 17 00:00:00 2001 From: Usha Mandya Date: Thu, 31 Mar 2022 17:26:01 +0100 Subject: [PATCH 11/17] Update note on DD4L beta Signed-off-by: Usha Mandya --- engine/install/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/engine/install/index.md b/engine/install/index.md index 7cbfa28dc8..eaeb54e9fe 100644 --- a/engine/install/index.md +++ b/engine/install/index.md @@ -30,7 +30,10 @@ redirect_from: > **Docker Desktop for Linux** > -> Docker Desktop helps you build, share, and run containers easily on Mac and Windows as you do on Linux. Docker handles the complex setup and allows you to focus on writing the code. Thanks to the positive support we received on the [subscription updates](https://www.docker.com/blog/updating-product-subscriptions/){: target="_blank" rel="noopener" class="_" id="dkr_docs_cta"}, we've started working on [Docker Desktop for Linux](https://www.docker.com/blog/accelerating-new-features-in-docker-desktop/){: target="_blank" rel="noopener" class="_" id="dkr_docs_cta"} which is the second-most popular feature request in our public roadmap. If you are interested in early access, sign up for our [Developer Preview program](https://www.docker.com/community/get-involved/developer-preview){: target="_blank" rel="noopener" class="_" id="dkr_docs_cta"}. +> Docker Desktop helps you build, share, and run containers easily on Mac and +> Windows as you do on Linux. We are excited to share that Docker Desktop for +> Linux (Beta) is now available for you to test. For more information, see +[Docker Desktop for Linux](../../desktop/linux/index.md). {: .important} ## Supported platforms From 07ba341736651943f8ce0ade15665e1d19668d77 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 31 Mar 2022 22:28:12 +0200 Subject: [PATCH 12/17] IAM: fix missing prompt, causing code to not be selectable This code-block uses the "console" highlighting, which considers lines that do not start with a prompt to be "output" of the command, and non-selectable. Signed-off-by: Sebastiaan van Stijn --- _includes/configure-registry-json.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_includes/configure-registry-json.md b/_includes/configure-registry-json.md index 43f21fc86d..9d744f48b3 100644 --- a/_includes/configure-registry-json.md +++ b/_includes/configure-registry-json.md @@ -52,13 +52,13 @@ To create your `registry.json` file on macOS: 3. Open a new terminal and type the following command: ```console - sudo mkdir -p /Library/Application\ Support/com.docker.docker + $ sudo mkdir -p /Library/Application\ Support/com.docker.docker ``` If prompted, type your password associated with your local computer. 4. Type the following command: - ```console - sudo cp Documents/registry.json /Library/Application\ Support/com.docker.docker/registry.json + ```console + $ sudo cp Documents/registry.json /Library/Application\ Support/com.docker.docker/registry.json ``` From a7c4a6bdd97f19f41abbac192953cd8ce5e3554f Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 31 Mar 2022 23:26:35 +0200 Subject: [PATCH 13/17] move "page generated" comment to prevent rendering in quirks mode As described on https://en.wikipedia.org/wiki/Quirks_mode, a comment preceding the `` can cause some browsers to render the HTML in quirks mode. This patch moves the comment after the doctype to prevent this. Signed-off-by: Sebastiaan van Stijn --- _layouts/docs.html | 2 +- _layouts/landing.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_layouts/docs.html b/_layouts/docs.html index 701bac4165..f7446e6956 100644 --- a/_layouts/docs.html +++ b/_layouts/docs.html @@ -1,10 +1,10 @@ + - {%- include head.html -%} diff --git a/_layouts/landing.html b/_layouts/landing.html index 0cf5737324..717d1821d6 100644 --- a/_layouts/landing.html +++ b/_layouts/landing.html @@ -1,5 +1,5 @@ - + {%- include head.html -%} From dddeb5a51edb195e8e11ff94c4730deee640a996 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 31 Mar 2022 23:51:22 +0200 Subject: [PATCH 14/17] reformat "get started" 06 - bind-mounts The "docker build" example was written as an in-line example, but directly followed by a full-stop at the end of the sentence, which made it easy to confuse the extra `.` to be part of the command to run. This moves it to a code block to allow the example to be highlighted, and less confusing. Signed-off-by: Sebastiaan van Stijn --- get-started/06_bind_mounts.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/get-started/06_bind_mounts.md b/get-started/06_bind_mounts.md index 741f2ea978..55a4f09de3 100644 --- a/get-started/06_bind_mounts.md +++ b/get-started/06_bind_mounts.md @@ -66,7 +66,7 @@ So, let's do it! running `yarn install` to install _all_ dependencies and then running `yarn run dev`. If we look in the `package.json`, we'll see that the `dev` script is starting `nodemon`. -3. You can watch the logs using `docker logs -f `. You'll know you're ready to go when you see this: +3. You can watch the logs using `docker logs`. You'll know you're ready to go when you see this: ```console $ docker logs -f @@ -96,7 +96,11 @@ So, let's do it! {: .text-center } 6. Feel free to make any other changes you'd like to make. When you're done, stop the container and build your new image - using `docker build -t getting-started .`. + using: + + ```console + $ docker build -t getting-started . + ``` Using bind mounts is _very_ common for local development setups. The advantage is that the dev machine doesn't need to have all of the build tools and environments installed. With a single `docker run` command, the dev environment is pulled and ready From 6ea99b800fa39bb0ddcf7c45fea7542fcb0f8c37 Mon Sep 17 00:00:00 2001 From: Chris McLellan Date: Fri, 1 Apr 2022 11:59:04 +0100 Subject: [PATCH 15/17] Update index.md --- desktop/linux/index.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/desktop/linux/index.md b/desktop/linux/index.md index f40fcc032a..7495ef1805 100644 --- a/desktop/linux/index.md +++ b/desktop/linux/index.md @@ -148,10 +148,11 @@ Status: Downloaded newer image for molly/privateimage:latest docker.io/molly/privateimage:latest ``` +## Report a bug -## Logs +Please report any bugs via the Issues tracker within the [docker/desktop-linux repo](https://github.com/docker/desktop-linux/issues). -To create and upload a diagnostics bundle: +To create and upload a diagnostics bundle with your bug report: 1. From the Docker menu, select **Troubleshoot** > **Get support**. 2. When the diagnostics are available, click **Upload to get a Diagnostic ID**. @@ -160,7 +161,9 @@ To create and upload a diagnostics bundle: be generated, once uploaded, it displays a diagnostics ID that can be sent to us for investigation. -Or, if you prefer to investigate the issue, you can access Docker Desktop logs by running the following command: +## Logs + +If you prefer to investigate issues yourself, you can access Docker Desktop logs by running the following command: ```console $ journalctl --user --unit=docker-desktop From f6130a53fdd4c1fa37a40c0cb9635511006d64cc Mon Sep 17 00:00:00 2001 From: Chris McLellan Date: Fri, 1 Apr 2022 12:14:53 +0100 Subject: [PATCH 16/17] Update desktop/linux/index.md Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com> --- desktop/linux/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/desktop/linux/index.md b/desktop/linux/index.md index 7495ef1805..3ca3729239 100644 --- a/desktop/linux/index.md +++ b/desktop/linux/index.md @@ -150,7 +150,7 @@ docker.io/molly/privateimage:latest ## Report a bug -Please report any bugs via the Issues tracker within the [docker/desktop-linux repo](https://github.com/docker/desktop-linux/issues). +Thanks for trying out the Docker Desktop Linux (beta) release. We'd love to hear from you. You can provide feedback and report any bugs through the **Issues** tracker within the [docker/desktop-linux](https://github.com/docker/desktop-linux/issues){: target="_blank" rel="noopener" class="_"} repository. To create and upload a diagnostics bundle with your bug report: From dffe6c367580d7e2396d334e1682e8d102bfafa0 Mon Sep 17 00:00:00 2001 From: Chris McLellan Date: Fri, 1 Apr 2022 12:15:26 +0100 Subject: [PATCH 17/17] Update index.md --- desktop/linux/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/desktop/linux/index.md b/desktop/linux/index.md index 3ca3729239..136afaa282 100644 --- a/desktop/linux/index.md +++ b/desktop/linux/index.md @@ -148,7 +148,7 @@ Status: Downloaded newer image for molly/privateimage:latest docker.io/molly/privateimage:latest ``` -## Report a bug +## Feedback Thanks for trying out the Docker Desktop Linux (beta) release. We'd love to hear from you. You can provide feedback and report any bugs through the **Issues** tracker within the [docker/desktop-linux](https://github.com/docker/desktop-linux/issues){: target="_blank" rel="noopener" class="_"} repository.