From bfd46ac620fcb8eb7d5c1c0cb56d77e9eadac6a5 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Tue, 7 Jan 2025 17:12:17 +0000 Subject: [PATCH] ENGDOCS-2360 (#21725) ## Description Looks larger than it is: - - A follow-up to comments on https://github.com/docker/docs/pull/21639 - Deals with hotjar issue https://docker.slack.com/archives/C04BMTUC41E/p1734970724382829 - Vale freshness ## Related issues or tickets ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Co-authored-by: Sarah Sanders --- _vale/Docker/Acronyms.yml | 9 + _vale/config/vocabularies/Docker/accept.txt | 12 +- content/reference/compose-file/build.md | 68 +++-- content/reference/compose-file/deploy.md | 44 +-- content/reference/compose-file/develop.md | 36 +-- content/reference/compose-file/include.md | 17 +- content/reference/compose-file/networks.md | 22 +- content/reference/compose-file/services.md | 282 ++++++++++---------- content/reference/compose-file/volumes.md | 12 +- 9 files changed, 259 insertions(+), 243 deletions(-) diff --git a/_vale/Docker/Acronyms.yml b/_vale/Docker/Acronyms.yml index ae5de53732f..cfccdaf0800 100644 --- a/_vale/Docker/Acronyms.yml +++ b/_vale/Docker/Acronyms.yml @@ -18,7 +18,9 @@ exceptions: - BIOS - BPF - BSD + - CFS - CI + - CIDR - CISA - CLI - CNCF @@ -26,6 +28,7 @@ exceptions: - CPU - CSS - CSV + - CUDA - CVE - DCT - DEBUG @@ -60,6 +63,8 @@ exceptions: - ID - IDE - IP + - IPAM + - IPC - JAR - JSON - JSX @@ -79,6 +84,7 @@ exceptions: - NVDA - OCI - OS + - OSI - OSS - PATH - PDF @@ -91,6 +97,7 @@ exceptions: - RAM - REPL - REST + - RFC - RHEL - RPM - RSA @@ -125,8 +132,10 @@ exceptions: - USB - USD - UTF + - UTS - UUID - VAT + - VIP - VLAN - VM - VPN diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 07fb5e1242b..516200bd089 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -104,16 +104,20 @@ Zsh [Bb]uildx [Cc]odenames? [Cc]ompose +[Cc]onfigs [Dd]istroless [Ff]ilepaths? [Ff]iletypes? [GgCc]oroutine +[Hh]ealthcheck [Hh]ostname [Ii]nfosec +[Ii]nline [Kk]eyrings? [Ll]oopback [Mm]emcached [Mm]oby +[Mm]ountpoint [Nn]amespace [Oo]nboarding [Pp]aravirtualization @@ -126,6 +130,7 @@ Zsh [Ss]andbox(ed)? [Ss]eccomp [Ss]ubmounts? +[Ss]ubnet [Ss]ubpaths? [Ss]ubtrees? [Ss]wappable @@ -146,6 +151,7 @@ Zsh cgroup config containerd +datacenter deprovisioning deserialization deserialize @@ -160,7 +166,6 @@ kubectl kubefwd kubelet lookup -label_file macOS macvlan mfsymlinks @@ -174,15 +179,18 @@ npm osquery osxfs pgAdmin +rollback rootful runc snapshotters? stdin stdout -subnet +syntaxes +sysctls systemd tmpfs ufw +uid umask vSphere vpnkit diff --git a/content/reference/compose-file/build.md b/content/reference/compose-file/build.md index b5640f080a7..636ab89ec23 100644 --- a/content/reference/compose-file/build.md +++ b/content/reference/compose-file/build.md @@ -51,7 +51,7 @@ When used to build service images from source, the Compose file creates three Do * `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder throws an error. * `example/database`: A Docker image is built using `backend` sub-directory within the Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to the context path, which means `..` resolves to the Compose file's parent folder, so `backend.Dockerfile` is a sibling file. -* A Docker image is built using the `custom` directory with the user's HOME as the Docker context. Compose displays a warning about the non-portable path used to build image. +* A Docker image is built using the `custom` directory with the user's `$HOME` as the Docker context. Compose displays a warning about the non-portable path used to build image. On push, both `example/webapp` and `example/database` Docker images are pushed to the default registry. The `custom` service image is skipped as no `image` attribute is set and Compose displays a warning about this missing attribute. @@ -81,7 +81,7 @@ The second part represents a subdirectory inside the repository that is used as Alternatively `build` can be an object with fields defined as follows: -### additional_contexts +### `additional_contexts` {{< introduced compose 2.17.0 "/manuals/compose/releases/release-notes.md#2170" >}} @@ -118,9 +118,9 @@ the unused contexts. Illustrative examples of how this is used in Buildx can be found [here](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-additional-build-contexts---build-context). -### args +### `args` -`args` define build arguments, i.e. Dockerfile `ARG` values. +`args` define build arguments, that is Dockerfile `ARG` values. Using the following Dockerfile as an example: @@ -146,16 +146,16 @@ build: ``` Values can be omitted when specifying a build argument, in which case its value at build time must be obtained by user interaction, -otherwise the build arg won't be set when building the Docker image. +otherwise the build argument won't be set when building the Docker image. ```yml args: - GIT_COMMIT ``` -### context +### `context` -`context` defines either a path to a directory containing a Dockerfile, or a URL to a git repository. +`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 is interpreted as relative to the project directory. Compose warns you about the absolute path used to define the build context as those prevent the Compose file @@ -174,7 +174,7 @@ services: If not set explicitly, `context` defaults to project directory (`.`). -### cache_from +### `cache_from` `cache_from` defines a list of sources the image builder should use for cache resolution. @@ -196,7 +196,7 @@ build: Unsupported caches are ignored and don't prevent you from building images. -### cache_to +### `cache_to` `cache_to` defines a list of export locations to be used to share build cache with future builds. @@ -212,7 +212,7 @@ Cache target is defined using the same `type=TYPE[,KEY=VALUE]` syntax defined by Unsupported caches are ignored and don't prevent you from building images. -### dockerfile +### `dockerfile` `dockerfile` sets an alternate Dockerfile. A relative path is resolved from the build context. Compose warns you about the absolute path used to define the Dockerfile as it prevents Compose files @@ -227,7 +227,7 @@ build: dockerfile: webapp.Dockerfile ``` -### dockerfile_inline +### `dockerfile_inline` {{< introduced compose 2.17.0 "/manuals/compose/releases/release-notes.md#2170" >}} @@ -244,7 +244,7 @@ build: RUN some command ``` -### entitlements +### `entitlements` {{< introduced compose 2.27.1 "/manuals/compose/releases/release-notes.md#2271" >}} @@ -256,9 +256,9 @@ build: - security.insecure ``` -### extra_hosts +### `extra_hosts` -`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](services.md#extra_hosts). +`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [`extra_hosts`](services.md#extra_hosts). ```yml extra_hosts: @@ -290,12 +290,12 @@ configuration, which means for Linux `/etc/hosts` will get extra lines: ::1 myhostv6 ``` -### isolation +### `isolation` `isolation` specifies a build’s container isolation technology. Like [isolation](services.md#isolation), supported values are platform specific. -### labels +### `labels` `labels` add metadata to the resulting image. `labels` can be set either as an array or a map. @@ -319,7 +319,7 @@ build: - "com.example.label-with-empty-value" ``` -### network +### `network` Set the network containers connect to for the `RUN` instructions during build. @@ -343,13 +343,13 @@ build: network: none ``` -### no_cache +### `no_cache` `no_cache` disables image builder cache and enforces a full rebuild from source for all image layers. This only applies to layers declared in the Dockerfile, referenced images can be retrieved from local image store whenever tag has been updated on registry (see [pull](#pull)). -### platforms +### `platforms` `platforms` defines a list of target [platforms](services.md#platform). @@ -368,8 +368,8 @@ When the `platforms` attribute is defined, Compose includes the service's platform, otherwise users won't be able to run images they built. Composes reports an error in the following cases: -* When the list contains multiple platforms but the implementation is incapable of storing multi-platform images. -* When the list contains an unsupported platform. +- When the list contains multiple platforms but the implementation is incapable of storing multi-platform images. +- When the list contains an unsupported platform. ```yml build: @@ -378,7 +378,7 @@ Composes reports an error in the following cases: - "linux/amd64" - "unsupported/unsupported" ``` -* When the list is non-empty and does not contain the service's platform +- When the list is non-empty and does not contain the service's platform. ```yml services: @@ -390,7 +390,7 @@ Composes reports an error in the following cases: - "linux/arm64" ``` -### privileged +### `privileged` {{< introduced compose 2.15.0 "/manuals/compose/releases/release-notes.md#2" >}} @@ -402,12 +402,12 @@ build: privileged: true ``` -### pull +### `pull` `pull` requires the image builder to pull referenced images (`FROM` Dockerfile directive), even if those are already available in the local image store. -### secrets +### `secrets` `secrets` grants access to sensitive data defined by [secrets](services.md#secrets) on a per-service build basis. Two different syntax variants are supported: the short syntax and the long syntax. @@ -446,8 +446,8 @@ 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. +- `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`. - `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) 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`). @@ -478,7 +478,7 @@ Service builds may be granted access to multiple secrets. Long and short syntax same Compose file. Defining a secret in the top-level `secrets` must not imply granting any service build access to it. Such grant must be explicit within service specification as [secrets](services.md#secrets) service element. -### ssh +### `ssh` `ssh` defines SSH authentications that the image builder should use during image build (e.g., cloning private repository). @@ -515,7 +515,7 @@ For illustration, [SSH mounts](https://github.com/moby/buildkit/blob/master/fron RUN --mount=type=ssh,id=myproject git clone ... ``` -### shm_size +### `shm_size` `shm_size` sets the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker images. Specify as an integer value representing the number of bytes or as a string expressing a [byte value](extension.md#specifying-byte-values). @@ -532,7 +532,7 @@ build: shm_size: 10000000 ``` -### tags +### `tags` `tags` defines a list of tag mappings that must be associated to the build image. This list comes in addition to the `image` [property defined in the service section](services.md#image) @@ -543,7 +543,7 @@ tags: - "registry/username/myrepos:my-other-tag" ``` -### target +### `target` `target` defines the stage to build as defined inside a multi-stage `Dockerfile`. @@ -553,11 +553,11 @@ build: target: prod ``` -### ulimits +### `ulimits` {{< introduced compose 2.23.1 "/manuals/compose/releases/release-notes.md#2231" >}} -`ulimits` overrides the default ulimits for a container. It's specified either as an integer for a single limit +`ulimits` overrides the default `ulimits` for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits. ```yml @@ -571,5 +571,3 @@ services: soft: 20000 hard: 40000 ``` - - diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md index 11fd5e911cf..9fabf625d5d 100644 --- a/content/reference/compose-file/deploy.md +++ b/content/reference/compose-file/deploy.md @@ -11,7 +11,7 @@ weight: 140 ## Attributes -### endpoint_mode +### `endpoint_mode` `endpoint_mode` specifies a service discovery method for external clients connecting to a service. The Compose Deploy Specification defines two canonical values: @@ -34,7 +34,7 @@ services: endpoint_mode: vip ``` -### labels +### `labels` `labels` specifies metadata for the service. These labels are only 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 the Compose application model. @@ -48,9 +48,9 @@ services: com.example.description: "This label will appear on the web service" ``` -### mode +### `mode` -`mode` defines the replication model used to run the service on the platform. Either `global`, exactly one container per physical node, or `replicated`, a specified number of containers. The default is `replicated`. +`mode` defines the replication model used to run the service on the platform. Either `global`, exactly one container per physical node, or `replicated`, a specified number of containers. The default is `replicated`. ```yml services: @@ -60,11 +60,11 @@ services: mode: global ``` -### placement +### `placement` `placement` specifies constraints and preferences for the platform to select a physical node to run service containers. -#### constraints +#### `constraints` `constraints` defines a required property the platform's node must fulfill to run the service container. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create.md#constraint). @@ -75,7 +75,7 @@ deploy: - disktype=ssd ``` -#### preferences +#### `preferences` `preferences` defines a strategy (currently `spread` is the only supported strategy) to spread tasks evenly over the values of the datacenter node label. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create.md#placement-pref) @@ -87,7 +87,7 @@ deploy: - spread: node.labels.zone ``` -### replicas +### `replicas` If the service is `replicated` (which is the default), `replicas` specifies the number of containers that should be running at any given time. @@ -101,7 +101,7 @@ services: replicas: 6 ``` -### resources +### `resources` `resources` configures physical resource constraints for container to run on platform. Those constraints can be configured as: @@ -124,25 +124,25 @@ services: memory: 20M ``` -#### cpus +#### `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` `memory` configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](extension.md#specifying-byte-values). -#### pids +#### `pids` `pids` tunes a container’s PIDs limit, set as an integer. -#### devices +#### `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` `capabilities` are set as a list of strings, expressing both generic and driver specific capabilities. The following generic capabilities are recognized today: @@ -151,7 +151,7 @@ The following generic capabilities are recognized today: - `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: +For example, reserving an NVIDIA CUDA-enabled accelerator might look like this: ```yml deploy: @@ -161,7 +161,7 @@ deploy: - capabilities: ["nvidia-compute"] ``` -##### driver +##### `driver` A different driver for the reserved device(s) can be requested using `driver` field. The value is specified as a string. @@ -174,7 +174,7 @@ deploy: driver: nvidia ``` -##### count +##### `count` If `count` is set to `all` or not specified, Compose reserves all devices that satisfy the requested capabilities. Otherwise, Compose reserves at least the number of devices specified. The value is specified as an integer. @@ -189,7 +189,7 @@ deploy: `count` and `device_ids` fields are exclusive. Compose returns an error if both are specified. -##### device_ids +##### `device_ids` If `device_ids` is set, Compose reserves devices with the specified IDs provided they satisfy the requested capabilities. The value is specified as a list of strings. @@ -204,7 +204,7 @@ deploy: `count` and `device_ids` fields are exclusive. Compose returns an error if both are specified. -##### options +##### `options` Driver specific options can be set with `options` as key-value pairs. @@ -219,7 +219,7 @@ deploy: virtualization: false ``` -### restart_policy +### `restart_policy` `restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose considers the `restart` field set by the service configuration. @@ -243,7 +243,7 @@ deploy: window: 120s ``` -### rollback_config +### `rollback_config` `rollback_config` configures how the service should be rollbacked in case of a failing update. @@ -255,7 +255,7 @@ deploy: - `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` `update_config` configures how the service should be updated. Useful for configuring rolling updates. diff --git a/content/reference/compose-file/develop.md b/content/reference/compose-file/develop.md index d08ad90a31d..7bc771f103a 100644 --- a/content/reference/compose-file/develop.md +++ b/content/reference/compose-file/develop.md @@ -7,14 +7,13 @@ aliases: weight: 150 --- -> **Note:** +> [!NOTE] > > Develop is an optional part of the Compose Specification. It is available with Docker Compose version 2.22.0 and later. {{< include "compose/develop.md" >}} -This page defines how Compose behaves to efficiently assist you and defines the development constraints and workflows set by Compose. Only a subset of -Compose file services may require a `develop` subsection. +This page defines how Compose behaves to efficiently assist you and defines the development constraints and workflows set by Compose. Only a subset of Compose file services may require a `develop` subsection. ## Illustrative example @@ -44,24 +43,26 @@ services: ## Attributes + + The `develop` subsection defines configuration options that are applied by Compose to assist you during development of a service with optimized workflows. -### watch +### `watch` The `watch` attribute defines a list of rules that control automatic service updates based on local file changes. `watch` is a sequence, each individual item in the sequence defines a rule to be applied by Compose to monitor source code for changes. For more information, see [Use Compose Watch](/manuals/compose/how-tos/file-watch.md). -#### action +#### `action` `action` defines the action to take when changes are detected. If `action` is set to: -- `rebuild`, Compose rebuilds the service image based on the `build` section and recreates the service with the updated image. -- `restart`, Compose restarts the service container. Available with Docker Compose version 2.32.0 and later. -- `sync`, Compose keeps the existing service container(s) running, but synchronizes source files with container content according to the `target` attribute. -- `sync+restart`, Compose synchronizes source files with container content according to the `target` attribute, and then restarts the container. Available with Docker Compose version 2.23.0 and later. -- `sync+exec`, Compose synchronizes source files with container content according to the `target` attribute, and then executes a command inside the container. Available with Docker Compose version 2.32.0 and later. +- `rebuild`: Compose rebuilds the service image based on the `build` section and recreates the service with the updated image. +- `restart`: Compose restarts the service container. Available with Docker Compose version 2.32.0 and later. +- `sync`: Compose keeps the existing service container(s) running, but synchronizes source files with container content according to the `target` attribute. +- `sync+restart`: Compose synchronizes source files with container content according to the `target` attribute, and then restarts the container. Available with Docker Compose version 2.23.0 and later. +- `sync+exec`: Compose synchronizes source files with container content according to the `target` attribute, and then executes a command inside the container. Available with Docker Compose version 2.32.0 and later. -#### exec +#### `exec` {{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} @@ -87,26 +88,25 @@ services: command: app reload ``` -#### ignore +#### `ignore` The `ignore` attribute can be used to define a list of patterns for paths to be ignored. Any updated file that matches a pattern, or belongs to a folder that matches a pattern, won't trigger services to be re-created. The syntax is the same as `.dockerignore` file: -- `*` matches 0 or more characters in a file name. -- `?` matches a single character in file name. +- `*` matches 0 or more characters in a filename. +- `?` matches a single character in filename. - `*/*` matches two nested folders with arbitrary names - `**` matches an arbitrary number of nested folders If the build context includes a `.dockerignore` file, the patterns in this file is loaded as implicit content for the `ignores` file, and values set in the Compose model are appended. -#### path +#### `path` `path` attribute defines the path to source code (relative to the project directory) to monitor for changes. Updates to any file inside the path, which doesn't match any `ignore` rule, triggers the configured action. -#### target +#### `target` -`target` attribute only applies when `action` is configured for `sync`. Files within `path` with changes are synchronized -with container filesystem, so that the latter is always running with up-to-date content. +`target` attribute only applies when `action` is configured for `sync`. Files within `path` that have changes are synchronized with the container's filesystem, so that the latter is always running with up-to-date content. diff --git a/content/reference/compose-file/include.md b/content/reference/compose-file/include.md index 4e763859709..84591669903 100644 --- a/content/reference/compose-file/include.md +++ b/content/reference/compose-file/include.md @@ -61,7 +61,7 @@ services: - included-service # defined by another_domain ``` -In the above example, both `../commons/compose.yaml` and +In the previous example, both `../commons/compose.yaml` and `../another_domain/compose.yaml` are loaded as individual Compose projects. Relative paths in Compose files being referred by `include` are resolved relative to their own Compose file path, not based on the local project's directory. Variables are interpolated using values set in the optional @@ -78,12 +78,15 @@ include: env_file: ../another/.env ``` -### path +### `path` `path` is required and defines the location of the Compose file(s) to be parsed and included into the -local Compose model. `path` can be set to either a string when a single Compose file is involved, -or to a list of strings when multiple Compose files need to be [merged together](merge.md) to -define the Compose model to be included in the local application. +local Compose model. + +`path` can be set as: + +- A string: When using a single Compose file. +- A list of strings: When multiple Compose files need to be [merged together](merge.md) to define the Compose model for the local application. ```yaml include: @@ -92,12 +95,12 @@ include: - ./commons-override.yaml ``` -### project_directory +### `project_directory` `project_directory` defines a base path to resolve relative paths set in the Compose file. It defaults to the directory of the included Compose file. -### env_file +### `env_file` `env_file` defines an environment file(s) to use to define default values when interpolating variables in the Compose file being parsed. It defaults to `.env` file in the `project_directory` for the Compose diff --git a/content/reference/compose-file/networks.md b/content/reference/compose-file/networks.md index 73c4dff4422..4812272295d 100644 --- a/content/reference/compose-file/networks.md +++ b/content/reference/compose-file/networks.md @@ -64,7 +64,7 @@ The advanced example shows a Compose file which defines two custom networks. The ## Attributes -### driver +### `driver` `driver` specifies which driver should be used for this network. Compose returns an error if the driver is not available on the platform. @@ -77,7 +77,7 @@ networks: For more information on drivers and available options, see [Network drivers](/manuals/engine/network/drivers/_index.md). -### driver_opts +### `driver_opts` `driver_opts` specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent. @@ -92,7 +92,7 @@ networks: Consult the [network drivers documentation](/manuals/engine/network/_index.md) for more information. -### attachable +### `attachable` If `attachable` is set to `true`, then standalone containers should be able to 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 @@ -105,18 +105,18 @@ networks: attachable: true ``` -### enable_ipv6 +### `enable_ipv6` `enable_ipv6` enables IPv6 networking. For an example, see step four of [Create an IPv6 network](/manuals/engine/daemon/ipv6.md). -### external +### `external` If set to `true`: - `external` specifies that this network’s lifecycle is maintained outside of that of the application. Compose doesn't attempt to create these networks, and returns an error if one doesn't exist. - All other attributes apart from name are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid. -In the example below, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose +In the following example, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose queries the platform for an existing network simply called `outside` and connects the `proxy` service's containers to it. @@ -137,7 +137,7 @@ networks: external: true ``` -### ipam +### `ipam` `ipam` specifies a custom IPAM configuration. This is an object with several properties, each of which is optional: @@ -167,12 +167,12 @@ networks: baz: "0" ``` -### internal +### `internal` -By default, Compose provides external connectivity to networks. `internal`, when set to `true`, allows you to +By default, Compose provides external connectivity to networks. `internal`, when set to `true`, lets you create an externally isolated network. -### labels +### `labels` Add metadata to containers using `labels`. You can use either an array or a dictionary. @@ -198,7 +198,7 @@ networks: Compose sets `com.docker.compose.project` and `com.docker.compose.network` labels. -### name +### `name` `name` sets a custom name for the network. The name field can be used to reference networks which contain special characters. The name is used as is and is not scoped with the project name. diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md index 64867c483b0..b3bac368fec 100644 --- a/content/reference/compose-file/services.md +++ b/content/reference/compose-file/services.md @@ -10,15 +10,15 @@ weight: 20 {{< include "compose/services.md" >}} A Compose file must declare a `services` top-level 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 +and whose values are service definitions. A service definition contains the configuration that is applied to each service container. Each service may also include a `build` section, which defines how to create the Docker image for the service. -Compose supports building docker images using this service definition. If not used, the `build` section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is +Compose supports building Docker images using this service definition. If not used, the `build` section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is described in detail in the [Compose Build Specification](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 +these constraints and lets the platform 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 in the [Compose Deploy Specification](deploy.md) documentation. If not implemented the `deploy` section is ignored and the Compose file is still considered valid. @@ -73,7 +73,9 @@ For more example Compose files, explore the [Awesome Compose samples](https://gi ## Attributes -### annotations + + +### `annotations` `annotations` defines annotations for the container. `annotations` can use either an array or a map. @@ -87,7 +89,7 @@ annotations: - com.example.foo=bar ``` -### attach +### `attach` {{< introduced compose 2.20.0 "/manuals/compose/releases/release-notes.md#2200" >}} @@ -96,13 +98,13 @@ until you explicitly request it to. The default service configuration is `attach: true`. -### build +### `build` `build` specifies the build configuration for creating a container image from source, as defined in the [Compose Build Specification](build.md). -### blkio_config +### `blkio_config` -`blkio_config` defines a set of configuration options to set block IO limits for a service. +`blkio_config` defines a set of configuration options to set block I/O limits for a service. ```yml services: @@ -127,7 +129,7 @@ services: rate: 30 ``` -#### device_read_bps, device_write_bps +#### `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: @@ -135,7 +137,7 @@ Each item in the list must have two keys: - `path`: Defines 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 +#### `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: @@ -143,43 +145,43 @@ Each item in the list must have two keys: - `path`: Defines the symbolic path to the affected device. - `rate`: As an integer value representing the permitted number of operations per second. -#### weight +#### `weight` Modify the proportion of bandwidth allocated to a service relative to other services. Takes an integer value between 10 and 1000, with 500 being the default. -#### weight_device +#### `weight_device` Fine-tune bandwidth allocation by device. Each item in the list must have two keys: - `path`: Defines the symbolic path to the affected device. - `weight`: An integer value between 10 and 1000. -### cpu_count +### `cpu_count` `cpu_count` defines the number of usable CPUs for service container. -### cpu_percent +### `cpu_percent` `cpu_percent` defines the usable percentage of the available CPUs. -### cpu_shares +### `cpu_shares` `cpu_shares` defines, as integer value, a service container's relative CPU weight versus other containers. -### cpu_period +### `cpu_period` `cpu_period` configures CPU CFS (Completely Fair Scheduler) period when a platform is based on Linux kernel. -### cpu_quota +### `cpu_quota` `cpu_quota` configures CPU CFS (Completely Fair Scheduler) quota when a platform is based on Linux kernel. -### cpu_rt_runtime +### `cpu_rt_runtime` -`cpu_rt_runtime` configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either +`cpu_rt_runtime` configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a [duration](extension.md#specifying-durations). ```yml @@ -187,9 +189,9 @@ an integer value using microseconds as unit or a [duration](extension.md#specify cpu_rt_runtime: '95000' ``` -### cpu_rt_period +### `cpu_rt_period` -`cpu_rt_period` configures CPU allocation parameters for platforms with support for realtime scheduler. It can be either +`cpu_rt_period` configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a [duration](extension.md#specifying-durations). ```yml @@ -197,18 +199,18 @@ an integer value using microseconds as unit or a [duration](extension.md#specify cpu_rt_period: '11000' ``` -### cpus +### `cpus` `cpus` define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. `0.000` means no limit. When set, `cpus` must be consistent with the `cpus` attribute in the [Deploy Specification](deploy.md#cpus). -### cpuset +### `cpuset` -`cpuset` defines the explicit CPUs in which to allow execution. Can be a range `0-3` or a list `0,1` +`cpuset` defines the explicit CPUs in which to permit execution. Can be a range `0-3` or a list `0,1` -### cap_add +### `cap_add` `cap_add` specifies additional container [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) as strings. @@ -218,7 +220,7 @@ cap_add: - ALL ``` -### cap_drop +### `cap_drop` `cap_drop` specifies container [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) to drop as strings. @@ -229,7 +231,7 @@ cap_drop: - SYS_ADMIN ``` -### cgroup +### `cgroup` {{< introduced compose 2.15.0 "/manuals/compose/releases/release-notes.md#2150" >}} @@ -239,7 +241,7 @@ select which cgroup namespace to use, if supported. - `host`: Runs the container in the Container runtime cgroup namespace. - `private`: Runs the container in its own private cgroup namespace. -### cgroup_parent +### `cgroup_parent` `cgroup_parent` specifies an optional parent [cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) for the container. @@ -247,7 +249,7 @@ select which cgroup namespace to use, if supported. cgroup_parent: m-executor-abcd ``` -### command +### `command` `command` overrides the default command declared by the container image, for example by Dockerfile's `CMD`. @@ -263,12 +265,11 @@ command: [ "bundle", "exec", "thin", "-p", "3000" ] If the value is `null`, the default command from the image is used. -If the value is `[]` (empty list) or `''` (empty string), the default command declared by the image is ignored, -i.e. overridden to be empty. +If the value is `[]` (empty list) or `''` (empty string), the default command declared by the image is ignored, or in other words overridden to be empty. -### configs +### `configs` -Configs allow services to adapt their behaviour without the need to rebuild a Docker image. +`configs` let services adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the `configs` attribute. Two different syntax variants are supported. Compose reports an error if `config` doesn't exist on the platform or isn't defined in the @@ -311,8 +312,8 @@ The long syntax provides more granularity in how the config is created within th - `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. +- `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`. - `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) 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. @@ -339,7 +340,7 @@ configs: external: true ``` -### container_name +### `container_name` `container_name` is a string that specifies a custom container name, rather than a name generated by default. @@ -352,7 +353,7 @@ Compose does not scale a service beyond one container if the Compose file specif `container_name` follows the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+` -### credential_spec +### `credential_spec` `credential_spec` configures the credential spec for a managed service account. @@ -397,7 +398,7 @@ configs: file: ./my-credential-spec.json| ``` -### depends_on +### `depends_on` {{< include "compose/services-depends-on.md" >}} @@ -442,9 +443,9 @@ expressed in the short form. after the container dies. Introduced in Docker Compose version [2.17.0](/manuals/compose/releases/release-notes.md#2170). - `condition`: Sets the condition under which dependency is considered satisfied - - `service_started`: An equivalent of the short syntax described above + - `service_started`: An equivalent of the short syntax described previously - `service_healthy`: Specifies that a dependency is expected to be "healthy" - (as indicated by [healthcheck](#healthcheck)) before starting a dependent + (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. @@ -484,17 +485,17 @@ starting a dependent service. Compose guarantees dependency services marked with `service_healthy` are "healthy" before starting a dependent service. -### deploy +### `deploy` `deploy` specifies the configuration for the deployment and lifecycle of services, as defined [in the Compose Deploy Specification](deploy.md). -### develop +### `develop` {{< introduced compose 2.22.0 "/manuals/compose/releases/release-notes.md#2220" >}} `develop` specifies the development configuration for maintaining a container in sync with source, as defined in the [Development Section](develop.md). -### device_cgroup_rules +### `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 @@ -506,7 +507,7 @@ device_cgroup_rules: - 'a 7:* rmw' ``` -### devices +### `devices` `devices` defines a list of device mappings for created containers in the form of `HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]`. @@ -517,7 +518,7 @@ devices: - "/dev/sda:/dev/xvda:rwm" ``` -### dns +### `dns` `dns` defines custom DNS servers to set on the container network interface configuration. It can be a single value or a list. @@ -531,7 +532,7 @@ dns: - 9.9.9.9 ``` -### dns_opt +### `dns_opt` `dns_opt` list custom DNS options to be passed to the container’s DNS resolver (`/etc/resolv.conf` file on Linux). @@ -541,7 +542,7 @@ dns_opt: - no-tld-query ``` -### dns_search +### `dns_search` `dns_search` defines custom DNS search domains to set on container network interface configuration. It can be a single value or a list. @@ -555,11 +556,11 @@ dns_search: - dc2.example.com ``` -### domainname +### `domainname` `domainname` declares a custom domain name to use for the service container. It must be a valid RFC 1123 hostname. -### driver_opts +### `driver_opts` {{< introduced compose 2.27.1 "/manuals/compose/releases/release-notes.md#2271" >}} @@ -577,7 +578,7 @@ services: Consult the [network drivers documentation](/manuals/engine/network/_index.md) for more information. -### entrypoint +### `entrypoint` `entrypoint` declares the default entrypoint for the service container. This overrides the `ENTRYPOINT` instruction from the service's Dockerfile. @@ -607,10 +608,9 @@ entrypoint: If the value is `null`, the default entrypoint from the image is used. -If the value is `[]` (empty list) or `''` (empty string), the default entrypoint declared by the image is ignored, -i.e. overridden to be empty. +If the value is `[]` (empty list) or `''` (empty string), the default entrypoint declared by the image is ignored, or in other words, overridden to be empty. -### env_file +### `env_file` {{< include "compose/services-env-file.md" >}} @@ -621,11 +621,11 @@ env_file: .env Relative paths are resolved from the Compose file's parent folder. As absolute paths prevent the Compose file from being portable, Compose warns you when such a path is used to set `env_file`. -Environment variables declared in the [environment](#environment) section override these values. This holds true even if those values are +Environment variables declared in the [`environment`](#environment) section override these values. This holds true even if those values are empty or undefined. `env_file` can also be a list. The files in the list are processed from the top down. For the same variable -specified in two env files, the value from the last file in the list stands. +specified in two environment files, the value from the last file in the list stands. ```yml env_file: @@ -636,7 +636,7 @@ env_file: List elements can also be declared as a mapping, which then lets you set additional attributes. -#### required +#### `required` {{< introduced compose 2.24.0 "/manuals/compose/releases/release-notes.md#2240" >}} @@ -650,11 +650,11 @@ env_file: required: false ``` -#### format +#### `format` {{< introduced compose 2.30.0 "/manuals/compose/releases/release-notes.md#2300" >}} -The `format` attribute lets you use an alternative file format for the `env_file`. When not set, `env_file` is parsed according to the Compose rules outlined in [Env_file format](#env_file-format). +The `format` attribute lets you use an alternative file format for the `env_file`. When not set, `env_file` is parsed according to the Compose rules outlined in [`Env_file` format](#env_file-format). `raw` format lets you use an `env_file` with key=value items, but without any attempt from Compose to parse the value for interpolation. This let you pass values as-is, including quotes and `$` signs. @@ -665,7 +665,7 @@ env_file: format: raw ``` -#### Env_file format +#### `Env_file` format Each line in an `.env` file must be in `VAR[=[VAL]]` format. The following syntax rules apply: @@ -702,7 +702,7 @@ RACK_ENV=development VAR="quoted" ``` -### environment +### `environment` {{< include "compose/services-environment.md" >}} @@ -730,7 +730,7 @@ environment: When both `env_file` and `environment` are set for a service, values set by `environment` have precedence. -### expose +### `expose` `expose` defines the (incoming) port or a range of ports that Compose exposes from the container. These ports must be accessible to linked services and should not be published to the host machine. Only the internal container @@ -750,7 +750,7 @@ expose: > > If the Dockerfile for the image already exposes ports, it is visible to other containers on the network even if `expose` is not set in your Compose file. -### extends +### `extends` `extends` lets you share common configurations among different files, or even different projects entirely. With `extends` you can define a common set of service options in one place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs. @@ -811,9 +811,8 @@ The following keys should be treated as mappings: `annotations`, `build.args`, ` `labels`, `logging.options`, `sysctls`, `storage_opt`, `extra_hosts`, `ulimits`. One exception that applies to `healthcheck` is that the main mapping cannot specify -`disable: true` unless the referenced mapping also specifies `disable: true`. Compose returns an error in this case. - -For example, the input below: +`disable: true` unless the referenced mapping also specifies `disable: true`. Compose returns an error in this case. +For example, the following input: ```yaml services: @@ -844,7 +843,7 @@ Items under `blkio_config.device_read_bps`, `blkio_config.device_read_iops`, `volumes` are also treated as mappings where key is the target path inside the container. -For example, the input below: +For example, the following input: ```yaml services: @@ -872,7 +871,7 @@ If the referenced service definition contains `extends` mapping, the items under are simply copied into the new merged definition. The merging process is then kicked off again until no `extends` keys are remaining. -For example, the input below: +For example, the following input: ```yaml services: @@ -906,7 +905,7 @@ The following keys should be treated as sequences: `cap_add`, `cap_drop`, `confi Any duplicates resulting from the merge are removed so that the sequence only contains unique elements. -For example, the input below: +For example, the following input: ```yaml services: @@ -931,14 +930,14 @@ security_opt: ``` 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, +`dns`, `dns_search`, `env_file`, `tmpfs`. Unlike sequence fields mentioned previously, 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` `external_links` link service containers to services managed outside of your Compose application. `external_links` define the name of an existing service to retrieve using the platform lookup mechanism. @@ -951,7 +950,7 @@ external_links: - database:postgresql ``` -### extra_hosts +### `extra_hosts` `extra_hosts` adds hostname mappings to the container network interface configuration (`/etc/hosts` for Linux). @@ -1001,7 +1000,7 @@ configuration, which means for Linux `/etc/hosts` get extra lines: ::1 myhostv6 ``` -### group_add +### `group_add` `group_add` specifies additional groups, by name or number, which the user inside the container must be a member of. @@ -1020,7 +1019,7 @@ services: 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` {{< include "compose/services-healthcheck.md" >}} @@ -1048,7 +1047,7 @@ test: ["CMD", "curl", "-f", "http://localhost"] ``` Using `CMD-SHELL` runs the command configured as a string using the container's default shell -(`/bin/sh` for Linux). Both forms below are equivalent: +(`/bin/sh` for Linux). Both of the following forms are equivalent: ```yml test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] @@ -1066,11 +1065,11 @@ healthcheck: disable: true ``` -### hostname +### `hostname` `hostname` declares a custom host name to use for the service container. It must be a valid RFC 1123 hostname. -### image +### `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), @@ -1091,7 +1090,7 @@ pull over building the image from source, however pulling the image is the defau `image` may be omitted from a Compose file as long as a `build` section is declared. If you are not using the Compose Build Specification, Compose won't work if `image` is missing from the Compose file. -### init +### `init` `init` runs 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. @@ -1105,7 +1104,7 @@ services: The init binary that is used is platform specific. -### ipc +### `ipc` `ipc` configures the IPC isolation mode set by the service container. @@ -1119,11 +1118,11 @@ The init binary that is used is platform specific. ipc: "service:[service name]" ``` -### isolation +### `isolation` `isolation` specifies a container’s isolation technology. Supported values are platform specific. -### labels +### `labels` `labels` add metadata to containers. You can use either an array or a map. @@ -1152,7 +1151,7 @@ Compose creates containers with canonical labels: The `com.docker.compose` label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error. -### label_file +### `label_file` {{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} @@ -1173,7 +1172,7 @@ services: If a label is defined in both the `label_file` and the `labels` attribute, the value in [labels](#labels) takes precedence. -### links +### `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. @@ -1190,14 +1189,13 @@ Containers for the linked service are reachable at a hostname identical to the a if no alias is specified. Links are not required to enable services to communicate. When no specific network configuration is set, -any service is 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` does not override the network configuration and services not -attached to a shared network are not be able to communicate. Compose doesn't warn you about a configuration mismatch. +any service is able to reach any other service at that service’s name on the `default` network. +If services specify the networks they are attached to, `links` does not override the network configuration. Services that are not connected to a shared network are not be able to communicate with each other. Compose doesn't warn you about a 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. +[`depends_on`](#depends_on), so they determine the order of service startup. -### logging +### `logging` `logging` defines the logging configuration for the service. @@ -1211,28 +1209,28 @@ logging: 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. -### mac_address +### `mac_address` > Available with Docker Compose version 2.24.0 and later. -`mac_address` sets a MAC address for the service container. +`mac_address` sets a Mac address for the service container. > [!NOTE] -> Container runtimes might reject this value (ie. Docker Engine >= v25.0). In that case, you should use [networks.mac_address](#mac_address) instead. +> Container runtimes might reject this value, for example Docker Engine >= v25.0. In that case, you should use [networks.mac_address](#mac_address) instead. -### mem_limit +### `mem_limit` `mem_limit` configures a limit on the amount of memory a container can allocate, set as a string expressing a [byte value](extension.md#specifying-byte-values). When set, `mem_limit` must be consistent with the `limits.memory` attribute in the [Deploy Specification](deploy.md#memory). -### mem_reservation +### `mem_reservation` `mem_reservation` configures a reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](extension.md#specifying-byte-values). When set, `mem_reservation` must be consistent with the `reservations.memory` attribute in the [Deploy Specification](deploy.md#memory). -### mem_swappiness +### `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. @@ -1242,7 +1240,7 @@ anonymous memory pages used by a container. The default value is platform specific. -### memswap_limit +### `memswap_limit` `memswap_limit` defines the amount of memory the container is allowed to swap to disk. This is a modifier attribute that only has meaning if [`memory`](deploy.md#memory) is also set. Using swap lets the container write excess @@ -1255,7 +1253,7 @@ There is a performance penalty for applications that swap memory to disk often. - 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. -### network_mode +### `network_mode` `network_mode` sets a service container's network mode. @@ -1275,7 +1273,7 @@ For more information container networks, see the [Docker Engine documentation](/ When set, the [`networks`](#networks) attribute is not allowed and Compose rejects any Compose file containing both attributes. -### networks +### `networks` {{< include "compose/services-networks.md" >}} @@ -1288,7 +1286,7 @@ services: ``` For more information about the `networks` top-level element, see [Networks](networks.md). -#### aliases +#### `aliases` `aliases` declares alternative hostnames for the service on the network. Other containers on the same network can use either the service name or an alias to connect to one of the service's containers. @@ -1345,7 +1343,7 @@ networks: admin: ``` -#### ipv4_address, ipv6_address +#### `ipv4_address`, `ipv6_address` Specify a static IP address for a service container when joining the network. @@ -1370,7 +1368,7 @@ networks: - subnet: "2001:3984:3989::/64" ``` -#### link_local_ips +#### `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 @@ -1393,13 +1391,13 @@ networks: driver: bridge ``` -#### mac_address +#### `mac_address` {{< introduced compose 2.23.2 "/manuals/compose/releases/release-notes.md#2232" >}} -`mac_address` sets the MAC address used by the service container when connecting to this particular network. +`mac_address` sets the Mac address used by the service container when connecting to this particular network. -#### priority +#### `priority` `priority` indicates in which order Compose connects the service’s containers to its networks. If unspecified, the default value is 0. @@ -1424,22 +1422,22 @@ networks: app_net_3: ``` -### oom_kill_disable +### `oom_kill_disable` If `oom_kill_disable` is set, Compose configures the platform so it won't kill the container in case of memory starvation. -### oom_score_adj +### `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` `pid` sets the PID mode for container created by Compose. Supported values are platform specific. -### pids_limit +### `pids_limit` `pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs. @@ -1449,7 +1447,7 @@ pids_limit: 10 When set, `pids_limit` must be consistent with the `pids` attribute in the [Deploy Specification](deploy.md#pids). -### platform +### `platform` `platform` defines the target platform the containers for the service run on. It uses the `os[/arch[/variant]]` syntax. @@ -1464,7 +1462,7 @@ platform: windows/amd64 platform: linux/arm64/v8 ``` -### ports +### `ports` {{< include "compose/services-ports.md" >}} @@ -1491,7 +1489,7 @@ Either specify both ports (`HOST:CONTAINER`), or just the container port. In the the container runtime automatically allocates any unassigned port of the host. `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). Examples: @@ -1515,7 +1513,7 @@ ports: #### Long syntax -The long form syntax allows the configuration of additional fields that can't be +The long form syntax lets you configure additional fields that can't be expressed in the short form. - `target`: The container port @@ -1545,7 +1543,7 @@ ports: mode: host ``` -### post_start +### `post_start` {{< introduced compose 2.30.0 "../../manuals/compose/releases/release-notes.md#2300" >}} @@ -1570,7 +1568,7 @@ services: For more information, see [Use lifecycle hooks](/manuals/compose/how-tos/lifecycle.md). -### pre_stop +### `pre_stop` {{< introduced compose 2.30.0 "../../manuals/compose/releases/release-notes.md#2300" >}} @@ -1578,11 +1576,11 @@ For more information, see [Use lifecycle hooks](/manuals/compose/how-tos/lifecyc Configuration is equivalent to [post_start](#post_start). -### privileged +### `privileged` `privileged` configures the service container to run with elevated privileges. Support and actual impacts are platform specific. -### profiles +### `profiles` `profiles` defines a list of named profiles for the service to be enabled under. If unassigned, the service is always started but if assigned, it is only started if the profile is activated. @@ -1602,7 +1600,7 @@ services: - debug ``` -### pull_policy +### `pull_policy` `pull_policy` defines the decisions Compose makes when it starts to pull images. Possible values are: @@ -1614,11 +1612,11 @@ services: `if_not_present` is considered an alias for this value for backward compatibility. * `build`: Compose builds the image. Compose rebuilds the image if it's already present. -### read_only +### `read_only` `read_only` configures the service container to be created with a read-only filesystem. -### restart +### `restart` `restart` defines the policy that the platform applies on container termination. @@ -1641,7 +1639,7 @@ You can find more detailed information on restart policies in the [Restart Policies (--restart)](/reference/cli/docker/container/run.md#restart) section of the Docker run reference page. -### runtime +### `runtime` `runtime` specifies which runtime to use for the service’s containers. @@ -1656,12 +1654,12 @@ web: The default is `runc`. To use a different runtime, see [Alternative runtimes](/manuals/engine/daemon/alternative-runtimes.md). -### scale +### `scale` `scale` specifies the default number of containers to deploy for this service. When both are set, `scale` must be consistent with the `replicas` attribute in the [Deploy Specification](deploy.md#replicas). -### secrets +### `secrets` {{< include "compose/services-secrets.md" >}} @@ -1703,8 +1701,8 @@ 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 container, or absolute path of the file if an alternate location is required. 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. +- `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`. - `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file to be mounted in `/run/secrets/` in the service's task containers, in octal notation. The default value is world-readable permissions (mode `0444`). @@ -1730,7 +1728,7 @@ secrets: file: ./server.cert ``` -### security_opt +### `security_opt` `security_opt` overrides the default labeling scheme for each container. @@ -1742,19 +1740,19 @@ security_opt: For further default labeling schemes you can override, see [Security configuration](/reference/cli/docker/container/run.md#security-opt). -### shm_size +### `shm_size` `shm_size` configures the size of the shared memory (`/dev/shm` partition on Linux) allowed by the service container. It's specified as a [byte value](extension.md#specifying-byte-values). -### stdin_open +### `stdin_open` `stdin_open` configures a service's container to run with an allocated stdin. This is the same as running a container with the -`-i` flag. For more information, see [Keep STDIN open](/reference/cli/docker/container/run.md#interactive). +`-i` flag. For more information, see [Keep stdin open](/reference/cli/docker/container/run.md#interactive). Supported values are `true` or `false`. -### stop_grace_period +### `stop_grace_period` `stop_grace_period` specifies how long Compose must wait when attempting to stop a container if it doesn't handle SIGTERM (or whichever stop signal has been specified with @@ -1768,7 +1766,7 @@ as a [duration](extension.md#specifying-durations). Default value is 10 seconds for the container to exit before sending SIGKILL. -### stop_signal +### `stop_signal` `stop_signal` defines the signal that Compose uses to stop the service containers. If unset containers are stopped by Compose by sending `SIGTERM`. @@ -1777,7 +1775,7 @@ If unset containers are stopped by Compose by sending `SIGTERM`. stop_signal: SIGUSR1 ``` -### storage_opt +### `storage_opt` `storage_opt` defines storage driver options for a service. @@ -1786,7 +1784,7 @@ storage_opt: size: '1G' ``` -### sysctls +### `sysctls` `sysctls` defines kernel parameters to set in the container. `sysctls` can use either an array or a map. @@ -1807,7 +1805,7 @@ 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](/reference/cli/docker/container/run.md#sysctl). -### tmpfs +### `tmpfs` `tmpfs` mounts a temporary file system inside the container. It can be a single value or a list. @@ -1834,16 +1832,16 @@ services: - /run ``` -### tty +### `tty` `tty` configures a service's container to run with a TTY. This is the same as running a container with the `-t` or `--tty` flag. For more information, see [Allocate a pseudo-TTY](/reference/cli/docker/container/run.md#tty). Supported values are `true` or `false`. -### ulimits +### `ulimits` -`ulimits` overrides the default ulimits for a container. It's specified either as an integer for a single limit +`ulimits` overrides the default `ulimits` for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits. ```yml @@ -1854,11 +1852,11 @@ ulimits: hard: 40000 ``` -### user +### `user` -`user` overrides the user used to run the container process. The default is set by the image (i.e. Dockerfile `USER`). If it's not set, then `root`. +`user` overrides the user used to run the container process. The default is set by the image, for example Dockerfile `USER`. If it's not set, then `root`. -### userns_mode +### `userns_mode` `userns_mode` sets the user namespace for the service. Supported values are platform specific and may depend on platform configuration. @@ -1867,7 +1865,7 @@ on platform configuration. userns_mode: "host" ``` -### uts +### `uts` {{< introduced compose 2.15.1 "/manuals/compose/releases/release-notes.md#2151" >}} @@ -1880,7 +1878,7 @@ it is the runtime's decision to assign a UTS namespace, if supported. Available uts: "host" ``` -### volumes +### `volumes` {{< include "compose/services-volumes.md" >}} @@ -1934,7 +1932,7 @@ The short syntax uses a single string with colon-separated values to specify a v #### Long syntax -The long form syntax allows the configuration of additional fields that can't be +The long form syntax lets you configure additional fields that can't be expressed in the short form. - `type`: The mount type. Either `volume`, `bind`, `tmpfs`, `npipe`, or `cluster` @@ -1963,7 +1961,7 @@ expressed in the short form. > Compose now takes advantage of [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md) and automatically creates file shares for bind mounts. > Ensure you're signed in to Docker with a paid subscription and have enabled both **Access experimental features** and **Manage Synchronized file shares with Compose** in Docker Desktop's settings. -### volumes_from +### `volumes_from` `volumes_from` mounts all of the volumes from another service or container. You can optionally specify read-only access `ro` or read-write `rw`. If no access level is specified, then read-write access is used. @@ -1978,6 +1976,6 @@ volumes_from: - container:container_name:rw ``` -### working_dir +### `working_dir` `working_dir` overrides the container's working directory which is specified by the image, for example Dockerfile's `WORKDIR`. diff --git a/content/reference/compose-file/volumes.md b/content/reference/compose-file/volumes.md index fb026e2669a..333d8e666a7 100644 --- a/content/reference/compose-file/volumes.md +++ b/content/reference/compose-file/volumes.md @@ -47,7 +47,7 @@ Running `docker compose up` creates the volume if it doesn't already exist. Othe An entry under the top-level `volumes` section can be empty, in which case it uses the container engine's default configuration for creating a volume. Optionally, you can configure it with the following keys: -### driver +### `driver` Specifies which volume driver should be used. If the driver is not available, Compose returns an error and doesn't deploy the application. @@ -57,7 +57,7 @@ volumes: driver: foobar ``` -### driver_opts +### `driver_opts` `driver_opts` specifies a list of options as key-value pairs to pass to the driver for this volume. The options are driver-dependent. @@ -70,14 +70,14 @@ volumes: device: ":/docker/example" ``` -### external +### `external` If set to `true`: - `external` specifies that this volume already exists on the platform and its lifecycle is managed outside of that of the application. Compose then doesn't create the volume and returns an error if the volume doesn't exist. - All other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid. -In the example below, instead of attempting to create a volume called +In the following example, 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. @@ -93,7 +93,7 @@ volumes: external: true ``` -### labels +### `labels` `labels` are used to add metadata to volumes. You can use either an array or a dictionary. @@ -119,7 +119,7 @@ volumes: Compose sets `com.docker.compose.project` and `com.docker.compose.volume` labels. -### name +### `name` `name` sets a custom name for a volume. The name field can be used to reference volumes that contain special characters. The name is used as is and is not scoped with the stack name.