mirror of https://github.com/docker/docs.git
Engdocs 1941 (#19083)
* move content in * vendor * fix broken link * fix lint errors * fix build * fix build * fix build * fix toc * services.md * fix build again
This commit is contained in:
Allie Sadler
GitHub
parent
b0483ac3c2
commit
83f11aeb52
|
|
@ -1,24 +0,0 @@
|
|||
# Status of this document
|
||||
|
||||
This document specifies the Compose file format used to define multi-containers applications. Distribution of this document is unlimited.
|
||||
|
||||
## 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. It is also designed for 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 that attributes will be actually implemented.
|
||||
|
||||
The specification defines the expected configuration syntax and behavior. Unless noted, supporting any of these is optional.
|
||||
|
||||
A Compose implementation to parse a Compose file using unsupported attributes should warn users. We recommend the following implementors
|
||||
to support those running modes:
|
||||
|
||||
* Default: warn the user about unsupported attributes, but ignore them
|
||||
* Strict: warn the 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)
|
||||
|
||||
From this point onwards, references made to 'Compose' can be interpreted as 'a Compose implementation'.
|
||||
|
|
@ -1,61 +0,0 @@
|
|||
# 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 is supported. Default values can be defined inline using typical shell syntax:
|
||||
|
||||
- `${VARIABLE:-default}` evaluates to `default` if `VARIABLE` is unset or
|
||||
empty in the environment.
|
||||
- `${VARIABLE-default}` evaluates to `default` only if `VARIABLE` is unset
|
||||
in the environment.
|
||||
|
||||
Similarly, the following syntax allows you to specify mandatory variables:
|
||||
|
||||
- `${VARIABLE:?err}` exits with an error message containing `err` if
|
||||
`VARIABLE` is unset or empty in the environment.
|
||||
- `${VARIABLE?err}` exits with an error message containing `err` only 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 Compose.
|
||||
|
||||
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.
|
||||
|
||||
```yml
|
||||
web:
|
||||
build: .
|
||||
command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
|
||||
```
|
||||
|
||||
If Compose can't resolve a substituted variable and no default value is defined, it displays a warning and substitutes 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 is applied before a merge on a per-file basis.
|
||||
|
||||
Interpolation applies only to YAML values, not to keys. For the few places where keys are actually arbitrary
|
||||
user-defined strings, such as [labels](05-services.md#labels) or [environment](05-services.md#environment), an alternate equal sign syntax
|
||||
must be used for interpolation to apply. For example:
|
||||
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
labels:
|
||||
"$VAR_NOT_INTERPOLATED_BY_COMPOSE": "BAR"
|
||||
```
|
||||
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
labels:
|
||||
- "$VAR_INTERPOLATED_BY_COMPOSE=BAR"
|
||||
```
|
||||
|
|
@ -3,5 +3,4 @@
|
|||
# github.com/docker/buildx v0.12.1
|
||||
# github.com/docker/scout-cli v1.2.0
|
||||
# github.com/docker/cli v25.0.0-rc.1+incompatible
|
||||
# github.com/compose-spec/compose-spec v0.0.0-20231121152139-478928e7c9f8
|
||||
# github.com/docker/compose/v2 v2.24.0
|
||||
# github.com/docker/compose/v2 v2.24.0
|
||||
|
|
@ -1,22 +1,28 @@
|
|||
# The Compose application model
|
||||
---
|
||||
title: Understand the Compose application model
|
||||
description: Understand the Compose application model with an illustrative example
|
||||
keywords: compose, docker compose, compose specification, compose model
|
||||
aliases:
|
||||
- /compose/compose-file/02-model/
|
||||
---
|
||||
|
||||
The Compose Specification lets you 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](05-services.md). 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](compose-file/05-services.md). 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](06-networks.md). In the Compose 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](compose-file/06-networks.md). In the Compose 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](07-volumes.md). 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](compose-file/07-volumes.md). 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 [configs](08-configs.md) concept. 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 [configs](compose-file/08-configs.md) concept. 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](09-secrets.md) 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.
|
||||
A [secret](compose-file/09-secrets.md) 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.
|
||||
|
||||
>**Note**
|
||||
>
|
||||
> With volumes, configs and secrets you can have a simple declaration at the top-level and then add more platform-specific information at the service level.
|
||||
|
||||
A project is an individual deployment of an application specification on a platform. A project's name, set with the top-level [`name`](04-version-and-name.md) attribute, is used to group
|
||||
A project is an individual deployment of an application specification on a platform. A project's name, set with the top-level [`name`](compose-file/04-version-and-name.md) attribute, is used to group
|
||||
resources together and isolate them from other applications or other installation of the same Compose specified application with distinct parameters. If you are creating resources on a platform, you must prefix resource names by project and
|
||||
set the label `com.docker.compose.project`.
|
||||
|
||||
|
|
@ -124,4 +130,4 @@ This example illustrates the distinction between volumes, configs and secrets. W
|
|||
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. Compose uses a platform-specific lookup mechanism to retrieve runtime values.
|
||||
and are declared `external` as they are not managed as part of the application lifecycle. Compose uses a platform-specific lookup mechanism to retrieve runtime values.
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Version and name top-level elements
|
||||
---
|
||||
title: Version and name top-level elements
|
||||
description: Understand when and if to set the version and name top-level element
|
||||
keywords: compose, compose specification, services, compose file reference
|
||||
---
|
||||
|
||||
## Version top-level element
|
||||
|
||||
|
|
@ -8,7 +12,7 @@ Compose doesn't use `version` to select an exact schema to validate the Compose
|
|||
prefers the most recent schema when it's implemented.
|
||||
|
||||
Compose validates whether it 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, you'll receive a warning message. Compose offers options to ignore unknown fields (as defined by ["loose"](01-status.md#requirements-and-optional-attributes) mode).
|
||||
because the Compose file was written with fields defined by a newer version of the Specification, you'll receive a warning message.
|
||||
|
||||
## Name top-level element
|
||||
|
||||
|
|
@ -26,4 +30,4 @@ services:
|
|||
environment:
|
||||
- COMPOSE_PROJECT_NAME
|
||||
command: echo "I'm running ${COMPOSE_PROJECT_NAME}"
|
||||
```
|
||||
```
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Services top-level element
|
||||
---
|
||||
title: Services top-level elements
|
||||
description: Explore all the attributes the services top-level element can have.
|
||||
keywords: compose, compose specification, services, compose file reference
|
||||
---
|
||||
|
||||
A service is an abstract definition of a computing resource within an application which can be scaled or replaced
|
||||
independently from other components. Services are backed by a set of containers, run by the platform
|
||||
|
|
@ -161,7 +165,6 @@ cap_drop:
|
|||
```
|
||||
|
||||
## cgroup
|
||||
|
||||
`cgroup` specifies the cgroup namespace to join. When unset, it is the container runtime's decision to
|
||||
select which cgroup namespace to use, if supported.
|
||||
|
||||
|
|
@ -537,6 +540,18 @@ env_file:
|
|||
- ./b.env
|
||||
```
|
||||
|
||||
List elements can also be declared as a mapping, which then lets you set an additional
|
||||
attribute `required`. This defaults to `true`. When `required` is set to `false` and the `.env` file is missing,
|
||||
Compose silently ignores the entry.
|
||||
|
||||
```yml
|
||||
env_file:
|
||||
- path: ./default.env
|
||||
required: true # default
|
||||
- path: ./override.env
|
||||
required: false
|
||||
```
|
||||
|
||||
Relative path 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`.
|
||||
|
||||
|
|
@ -612,14 +627,18 @@ When both `env_file` and `environment` are set for a service, values set by `env
|
|||
|
||||
## expose
|
||||
|
||||
`expose` defines the ports that Compose exposes from the container. These ports must be
|
||||
`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
|
||||
ports can be specified.
|
||||
|
||||
Syntax is `<portnum>/[<proto>]` or `<startport-endport>/[<proto>]` for a port range.
|
||||
When not explicitly set, `tcp` protocol is used.
|
||||
|
||||
```yml
|
||||
expose:
|
||||
- "3000"
|
||||
- "8000"
|
||||
- "8080-8085/tcp
|
||||
```
|
||||
|
||||
> **Note**
|
||||
|
|
@ -850,12 +869,28 @@ external_links:
|
|||
`extra_hosts` adds hostname mappings to the container network interface configuration (`/etc/hosts` for Linux).
|
||||
|
||||
### Short syntax
|
||||
Short syntax uses plain strings in a list. Values must set hostname and IP address for additional hosts in the form of `HOSTNAME:IP`.
|
||||
Short syntax uses plain strings in a list. Values must set hostname and IP address for additional hosts in the form of `HOSTNAME=IP`.
|
||||
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "somehost=162.242.195.82"
|
||||
- "otherhost=50.31.209.229"
|
||||
- "myhostv6=::1"
|
||||
```
|
||||
|
||||
IPv6 addresses can be enclosed in square brackets, for example:
|
||||
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "myhostv6=[::1]"
|
||||
```
|
||||
|
||||
The separator `=` is preferred, but `:` can also be used. For example:
|
||||
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "somehost:162.242.195.82"
|
||||
- "otherhost:50.31.209.229"
|
||||
- "myhostv6:::1"
|
||||
```
|
||||
|
||||
### Long syntax
|
||||
|
|
@ -865,14 +900,16 @@ Alternatively, `extra_hosts` can be set as a mapping between hostname(s) and IP(
|
|||
extra_hosts:
|
||||
somehost: "162.242.195.82"
|
||||
otherhost: "50.31.209.229"
|
||||
myhostv6: "::1"
|
||||
```
|
||||
|
||||
Compose creates a matching entry with the IP address and hostname in the container's network
|
||||
configuration, which means for Linux `/etc/hosts` get extra lines:
|
||||
|
||||
```
|
||||
```console
|
||||
162.242.195.82 somehost
|
||||
50.31.209.229 otherhost
|
||||
::1 myhostv6
|
||||
```
|
||||
|
||||
## group_add
|
||||
|
|
@ -1291,7 +1328,7 @@ 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.
|
||||
be within -1000,1000 range.
|
||||
|
||||
## pid
|
||||
|
||||
|
|
@ -1300,7 +1337,7 @@ Supported values are platform specific.
|
|||
|
||||
## pids_limit
|
||||
|
||||
_DEPRECATED: use [deploy.reservations.pids](deploy.md#pids)_
|
||||
_DEPRECATED: use [deploy.resources.limits.pids](deploy.md#pids)_
|
||||
|
||||
`pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs.
|
||||
|
||||
|
|
@ -1347,7 +1384,7 @@ If host IP is not set, it binds to all network interfaces. Ports can be either a
|
|||
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,
|
||||
Compose automatically allocates any unassigned port of the host.
|
||||
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).
|
||||
|
|
@ -1380,8 +1417,8 @@ expressed in the short form.
|
|||
- `target`: The container port
|
||||
- `published`: The publicly exposed port. It is defined as a string and can be set as a range using syntax `start-end`. It means the actual port is assigned a remaining available port, within the set range.
|
||||
- `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.
|
||||
- `protocol`: The port protocol (`tcp` or `udp`). Defaults to `tcp`.
|
||||
- `mode`: `host`: For publishing a host port on each node, or `ingress` for a port to be load balanced. Defaults to `ingress`.
|
||||
|
||||
```yml
|
||||
ports:
|
||||
|
|
@ -1473,9 +1510,8 @@ web:
|
|||
|
||||
## scale
|
||||
|
||||
_DEPRECATED: use [deploy/replicas](deploy.md#replicas)_
|
||||
|
||||
`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
|
||||
|
||||
|
|
@ -1760,4 +1796,4 @@ volumes_from:
|
|||
|
||||
## working_dir
|
||||
|
||||
`working_dir` overrides the container's working directory which is specified by the image, for example Dockerfile's `WORKDIR`.
|
||||
`working_dir` overrides the container's working directory which is specified by the image, for example Dockerfile's `WORKDIR`.
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Networks top-level element
|
||||
---
|
||||
title: Networks top-level elements
|
||||
description: Explore all the attributes the networks top-level element can have.
|
||||
keywords: compose, compose specification, networks, compose file reference
|
||||
---
|
||||
|
||||
Networks are the layer that allow services to communicate with each other.
|
||||
|
||||
|
|
@ -135,7 +139,7 @@ networks:
|
|||
|
||||
### enable_ipv6
|
||||
|
||||
`enable_ipv6` enables IPv6 networking. For an example, see step four of [Create an IPv6 network](https://docs.docker.com/config/daemon/ipv6/).
|
||||
`enable_ipv6` enables IPv6 networking. For an example, see step four of [Create an IPv6 network](../../config/daemon/ipv6.md).
|
||||
|
||||
## external
|
||||
|
||||
|
|
@ -246,4 +250,4 @@ networks:
|
|||
network1:
|
||||
external: true
|
||||
name: "${NETWORK_ID}"
|
||||
```
|
||||
```
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Volumes top-level element
|
||||
---
|
||||
title: Volumes top-level elements
|
||||
description: Explore all the attributes the volumes top-level element can have.
|
||||
keywords: compose, compose specification, volumes, compose file reference
|
||||
---
|
||||
|
||||
Volumes are persistent data stores implemented by the container engine. Compose offers a neutral way for services to mount volumes, and configuration parameters to allocate them to infrastructure.
|
||||
|
||||
|
|
@ -137,4 +141,3 @@ volumes:
|
|||
external:
|
||||
name: actual-name-of-volume
|
||||
```
|
||||
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Configs top-level element
|
||||
---
|
||||
title: Configs top-level elements
|
||||
description: Explore all the attributes the configs top-level element can have.
|
||||
keywords: compose, compose specification, configs, compose file reference
|
||||
---
|
||||
|
||||
Configs allow services to adapt their behaviour without the need to rebuild a Docker image.
|
||||
|
||||
|
|
@ -72,4 +76,4 @@ configs:
|
|||
name: "${HTTP_CONFIG_KEY}"
|
||||
```
|
||||
|
||||
If `external` is set to `true`, all other attributes apart from `name` are irrelevant. If Compose detecs any other attribute, it rejects the Compose file as invalid.
|
||||
If `external` is set to `true`, all other attributes apart from `name` are irrelevant. If Compose detecs any other attribute, it rejects the Compose file as invalid.
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Secrets top-level element
|
||||
---
|
||||
title: Secrets top-level elements
|
||||
description: Explore all the attributes the secrets top-level element can have.
|
||||
keywords: compose, compose specification, secrets, compose file reference
|
||||
---
|
||||
|
||||
Secrets are a flavor of [Configs](08-configs.md) focusing on sensitive data, with specific constraint for this usage.
|
||||
|
||||
|
|
@ -61,4 +65,4 @@ secrets:
|
|||
|
||||
If `external` is set to `true`, all other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.
|
||||
|
||||
Your Compose file needs to explicitly grant access to the secrets to relevant services in your application.
|
||||
Your Compose file needs to explicitly grant access to the secrets to relevant services in your application.
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Fragments
|
||||
---
|
||||
title: Fragments
|
||||
description: Understand how to use fragments
|
||||
keywords: compose, compose specification, fragments, compose file reference
|
||||
---
|
||||
|
||||
With Compose, you can use built-in [YAML](https://www.yaml.org/spec/1.2/spec.html#id2765878) features to make your Compose file neater and more efficient. Anchors and aliases let you create re-usable blocks. This is useful if you start to find common configurations that span multiple services. Having re-usable blocks minimizes potential mistakes.
|
||||
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Extension
|
||||
---
|
||||
title: Extensions
|
||||
description: Understand how to use extensions
|
||||
keywords: compose, compose specification, extensions, compose file reference
|
||||
---
|
||||
|
||||
As with [Fragments](10-fragments.md), Extensions can be used to make your Compose file more efficient and easier to maintain. Extensions can also be used with [anchors and aliases](10-fragments.md).
|
||||
|
||||
|
|
@ -125,7 +129,7 @@ This section is informative. At the time of writing, the following prefixes are
|
|||
Values 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).
|
||||
|
||||
```
|
||||
```text
|
||||
2b
|
||||
1024kb
|
||||
2048k
|
||||
|
|
@ -139,9 +143,9 @@ Values express a duration as a string in the form of `{value}{unit}`.
|
|||
The supported units are `us` (microseconds), `ms` (milliseconds), `s` (seconds), `m` (minutes) and `h` (hours).
|
||||
Values can combine multiple values without separator.
|
||||
|
||||
```
|
||||
```text
|
||||
10ms
|
||||
40s
|
||||
1m30s
|
||||
1h5m30s20ms
|
||||
```
|
||||
```
|
||||
|
|
@ -0,0 +1,125 @@
|
|||
---
|
||||
title: Interpolation
|
||||
description: Learn about interpolation
|
||||
keywords: compose, compose specification, interpolation, compose file reference
|
||||
---
|
||||
|
||||
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 is supported. Default values can be defined inline using typical shell syntax:
|
||||
|
||||
- `${VARIABLE:-default}` evaluates to `default` if `VARIABLE` is unset or
|
||||
empty in the environment.
|
||||
- `${VARIABLE-default}` evaluates to `default` only if `VARIABLE` is unset
|
||||
in the environment.
|
||||
|
||||
Similarly, the following syntax allows you to specify mandatory variables:
|
||||
|
||||
- `${VARIABLE:?err}` exits with an error message containing `err` if
|
||||
`VARIABLE` is unset or empty in the environment.
|
||||
- `${VARIABLE?err}` exits with an error message containing `err` only 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 Compose.
|
||||
|
||||
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.
|
||||
|
||||
```yml
|
||||
web:
|
||||
build: .
|
||||
command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
|
||||
```
|
||||
|
||||
If Compose can't resolve a substituted variable and no default value is defined, it displays a warning and substitutes 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 is applied before a merge on a per-file basis.
|
||||
|
||||
Interpolation applies only to YAML values, not to keys. For the few places where keys are actually arbitrary
|
||||
user-defined strings, such as [labels](05-services.md#labels) or [environment](05-services.md#environment), an alternate equal sign syntax
|
||||
must be used for interpolation to apply. For example:
|
||||
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
labels:
|
||||
"$VAR_NOT_INTERPOLATED_BY_COMPOSE": "BAR"
|
||||
```
|
||||
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
labels:
|
||||
- "$VAR_INTERPOLATED_BY_COMPOSE=BAR"
|
||||
```
|
||||
|
||||
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 is supported. Default values can be defined inline using typical shell syntax:
|
||||
|
||||
- `${VARIABLE:-default}` evaluates to `default` if `VARIABLE` is unset or
|
||||
empty in the environment.
|
||||
- `${VARIABLE-default}` evaluates to `default` only if `VARIABLE` is unset
|
||||
in the environment.
|
||||
|
||||
Similarly, the following syntax allows you to specify mandatory variables:
|
||||
|
||||
- `${VARIABLE:?err}` exits with an error message containing `err` if
|
||||
`VARIABLE` is unset or empty in the environment.
|
||||
- `${VARIABLE?err}` exits with an error message containing `err` only 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 Compose.
|
||||
|
||||
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.
|
||||
|
||||
```yml
|
||||
web:
|
||||
build: .
|
||||
command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
|
||||
```
|
||||
|
||||
If Compose can't resolve a substituted variable and no default value is defined, it displays a warning and substitutes 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 is applied before a merge on a per-file basis.
|
||||
|
||||
Interpolation applies only to YAML values, not to keys. For the few places where keys are actually arbitrary
|
||||
user-defined strings, such as [labels](05-services.md#labels) or [environment](05-services.md#environment), an alternate equal sign syntax
|
||||
must be used for interpolation to apply. For example:
|
||||
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
labels:
|
||||
"$VAR_NOT_INTERPOLATED_BY_COMPOSE": "BAR"
|
||||
```
|
||||
|
||||
```yml
|
||||
services:
|
||||
foo:
|
||||
labels:
|
||||
- "$VAR_INTERPOLATED_BY_COMPOSE=BAR"
|
||||
```
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Merge and override
|
||||
---
|
||||
title: Merge
|
||||
description: Learn about merging rules
|
||||
keywords: compose, compose specification, merge, compose file reference
|
||||
---
|
||||
|
||||
Compose lets you define a Compose application model through [multiple Compose files](https://docs.docker.com/compose/multiple-compose-files/).
|
||||
When doing so, Compose follows the rules declared in this section to merge Compose files.
|
||||
|
|
@ -176,4 +180,4 @@ services:
|
|||
read_only: false
|
||||
environment: {}
|
||||
ports: []
|
||||
```
|
||||
```
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Include
|
||||
---
|
||||
title: Include
|
||||
description: Learn about include
|
||||
keywords: compose, compose specification, include, compose file reference
|
||||
---
|
||||
|
||||
A Compose application can declare dependency on another Compose application. This is useful if:
|
||||
- You want to reuse other Compose files.
|
||||
|
|
@ -106,4 +110,4 @@ include:
|
|||
```
|
||||
|
||||
The local project's environment has precedence over the values set by the Compose file, so that the local project can
|
||||
override values for customization.
|
||||
override values for customization.
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Profiles
|
||||
---
|
||||
title: Profiles
|
||||
description: Learn about profiles
|
||||
keywords: compose, compose specification, profiles, compose file reference
|
||||
---
|
||||
|
||||
With profiles you can define a set of active profiles so your Compose application model is adjusted for various usages and environments.
|
||||
The exact mechanism is implementation specific and may include command line flags, environment variables, etc.
|
||||
|
|
@ -59,4 +63,4 @@ In the above example:
|
|||
profile `debug` is automatically enabled and service `bar` is pulled in as a dependency starting both
|
||||
services `zot` and `bar`.
|
||||
|
||||
See how you can use `profiles` in [Docker Compose](https://docs.docker.com/compose/profiles/).
|
||||
See how you can use `profiles` in [Docker Compose](../profiles.md).
|
||||
|
|
@ -8,18 +8,6 @@ title: Overview
|
|||
toc_max: 4
|
||||
toc_min: 1
|
||||
grid:
|
||||
- title: Status of the Specification
|
||||
description: Read about the status of the specification.
|
||||
icon: select_check_box
|
||||
link: /compose/compose-file/01-status/
|
||||
- title: The Compose application model
|
||||
description: Learn about the Compose application model.
|
||||
icon: storage
|
||||
link: /compose/compose-file/02-model/
|
||||
- title: The Compose file
|
||||
description: Understand the Compose file.
|
||||
icon: web_stories
|
||||
link: /compose/compose-file/03-compose-file/
|
||||
- title: Version and name top-level element
|
||||
description: Understand version and name attributes for Compose.
|
||||
icon: feed
|
||||
|
|
@ -54,13 +42,15 @@ aliases:
|
|||
> Find more information about the [key features and use cases of Docker Compose](../features-uses.md) or [try the get started guide](../gettingstarted.md).
|
||||
{ .tip }
|
||||
|
||||
The [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md) is the latest and recommended version of the Compose file format. It helps you define a [Compose file](03-compose-file.md) which is used to configure your Docker application’s services, networks, volumes, and more.
|
||||
The Compose Specification is the latest and recommended version of the Compose file format. It helps you define a [Compose file](../compose-yaml-file.md) which is used to configure your Docker application’s services, networks, volumes, and more.
|
||||
|
||||
Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose V2) of the Docker Compose CLI.
|
||||
Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose V2) of the Docker Compose CLI.
|
||||
|
||||
The Compose Specification on Docker Docs is the Docker Compose implementation. If you wish to implement your own version of the Compose Specification, see the [Compose Specication repository](https://github.com/compose-spec/compose-spec).
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Compose V1 no longer receives updates and will not be available in new releases of Docker Desktop after June 2023.
|
||||
> Compose V1 no longer receives updates and is not available in new releases of Docker Desktop.
|
||||
>
|
||||
> Compose V2 is included with all currently supported versions of Docker Desktop.
|
||||
> For more information, see [Migrate to Compose V2](/compose/migrate).
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
# Compose Build Specification
|
||||
---
|
||||
title: Compose Build Specification
|
||||
description: Learn about the Compose Build Specification
|
||||
keywords: compose, compose specification, compose file reference, compose build specification
|
||||
---
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
|
|
@ -289,18 +293,34 @@ Illustrative examples of how this is used in Buildx can be found
|
|||
|
||||
`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](05-services.md#extra_hosts).
|
||||
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "somehost=162.242.195.82"
|
||||
- "otherhost=50.31.209.229"
|
||||
- "myhostv6=::1"
|
||||
```
|
||||
IPv6 addresses can be enclosed in square brackets, for example:
|
||||
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "myhostv6=[::1]"
|
||||
```
|
||||
|
||||
The separator `=` is preferred, but `:` can also be used. For example:
|
||||
|
||||
```yml
|
||||
extra_hosts:
|
||||
- "somehost:162.242.195.82"
|
||||
- "otherhost:50.31.209.229"
|
||||
- "myhostv6:::1"
|
||||
```
|
||||
|
||||
Compose creates matching entry with the IP address and hostname in the container's network
|
||||
configuration, which means for Linux `/etc/hosts` will get extra lines:
|
||||
|
||||
```
|
||||
```text
|
||||
162.242.195.82 somehost
|
||||
50.31.209.229 otherhost
|
||||
::1 myhostv6
|
||||
```
|
||||
|
||||
### isolation
|
||||
|
|
@ -541,4 +561,4 @@ Composes reports an error in the following cases:
|
|||
context: "."
|
||||
platforms:
|
||||
- "linux/arm64"
|
||||
```
|
||||
```
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Compose Deploy Specification
|
||||
---
|
||||
title: Compose Deploy Specification
|
||||
description: Learn about the Compose Deploy Specification
|
||||
keywords: compose, compose specification, compose file reference, compose deploy specification
|
||||
---
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
|
|
@ -287,4 +291,4 @@ deploy:
|
|||
parallelism: 2
|
||||
delay: 10s
|
||||
order: stop-first
|
||||
```
|
||||
```
|
||||
|
|
@ -1,4 +1,8 @@
|
|||
# Compose Develop Specification
|
||||
---
|
||||
title: Compose Develop Specification
|
||||
description: Learn about the Compose Develop Specification
|
||||
keywords: compose, compose specification, compose file reference, compose develop specification
|
||||
---
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
|
|
@ -44,7 +48,7 @@ The `develop` subsection defines configuration options that are applied by Compo
|
|||
### 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](https://docs.docker.com/compose/file-watch/).
|
||||
Compose to monitor source code for changes. For more information, see [Use Compose Watch](../file-watch.md).
|
||||
|
||||
#### action
|
||||
|
||||
|
|
@ -77,5 +81,4 @@ inside the path, which doesn't match any `ignore` rule, triggers the configured
|
|||
#### 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.
|
||||
|
||||
with container filesystem, so that the latter is always running with up-to-date content.
|
||||
|
|
@ -1,18 +1,24 @@
|
|||
# Compose file
|
||||
---
|
||||
title: Understand the Compose file
|
||||
description: Understand the Compose application model with an illustrative example
|
||||
keywords: compose, docker compose, compose specification, compose model
|
||||
aliases:
|
||||
- /compose/compose-file/03-compose-file/
|
||||
---
|
||||
|
||||
The Compose file is a [YAML](http://yaml.org/) file defining:
|
||||
- [Version](04-version-and-name.md) (Optional)
|
||||
- [Services](05-services.md) (Required)
|
||||
- [Networks](06-networks.md)
|
||||
- [Volumes](07-volumes.md)
|
||||
- [Configs](08-configs.md)
|
||||
- [Secrets](09-secrets.md)
|
||||
- [Version](compose-file/04-version-and-name.md) (Optional)
|
||||
- [Services](compose-file/05-services.md) (Required)
|
||||
- [Networks](compose-file/06-networks.md)
|
||||
- [Volumes](compose-file/07-volumes.md)
|
||||
- [Configs](compose-file/08-configs.md)
|
||||
- [Secrets](compose-file/09-secrets.md)
|
||||
|
||||
The default path for a Compose file is `compose.yaml` (preferred) or `compose.yml` that is placed in the working directory.
|
||||
Compose also supports `docker-compose.yaml` and `docker-compose.yml` for backwards compatibility of earlier versions.
|
||||
If both files exist, Compose prefers the canonical `compose.yaml`.
|
||||
|
||||
You can use [fragments](10-fragments.md) and [extensions](11-extension.md) to keep your Compose file efficient and easy to maintain.
|
||||
You can use [fragments](compose-file/10-fragments.md) and [extensions](compose-file/11-extension.md) to keep your Compose file efficient and easy to maintain.
|
||||
|
||||
Multiple Compose files can be [merged](13-merge.md) together to define the application model. The combination of YAML files are implemented by appending or overriding YAML elements based on the Compose file order you set.
|
||||
Simple attributes and maps get overridden by the highest order Compose file, lists get merged by appending. Relative
|
||||
|
|
@ -20,4 +26,4 @@ paths are resolved based on the first Compose file's parent folder, whenever com
|
|||
merged are hosted in other folders. As some Compose file elements can both be expressed as single strings or complex objects, merges apply to
|
||||
the expanded form.
|
||||
|
||||
If you want to reuse other Compose files, or factor out parts of you application model into separate Compose files, you can also use [`include`](14-include.md). This is useful if your Compose application is dependent on another application which is managed by a different team, or needs to be shared with others.
|
||||
If you want to reuse other Compose files, or factor out parts of you application model into separate Compose files, you can also use [`include`](compose-file/14-include.md). This is useful if your Compose application is dependent on another application which is managed by a different team, or needs to be shared with others.
|
||||
|
|
@ -38,75 +38,3 @@ engine/reference/builder.md:
|
|||
keywords: |
|
||||
dockerfile, docker file, docker copy, dockerfile exec, docker entrypoint,
|
||||
dockerfile entrypoint, dockerfile arg, docker args, entrypoint, shell dockerfile
|
||||
|
||||
compose/compose-file/01-status.md:
|
||||
description: |
|
||||
Understand about the status of the Compose Specification, which is the most recent Compose file format used to define multi-containers applications.
|
||||
keywords: |
|
||||
compose, compose specification, status, compose file reference
|
||||
|
||||
compose/compose-file/02-model.md:
|
||||
description: |
|
||||
Learn about the compose application model.
|
||||
keywords: |
|
||||
compose, compose specification, application model, compose file reference
|
||||
|
||||
compose/compose-file/03-compose-file.md:
|
||||
description: |
|
||||
Understand the compose file.
|
||||
keywords: |
|
||||
compose, compose specification, compose yaml file, compose file reference
|
||||
|
||||
compose/compose-file/05-services.md:
|
||||
description: |
|
||||
Explore all the attributes the services top-level element can have.
|
||||
keywords: |
|
||||
compose, compose specification, services, compose file reference
|
||||
|
||||
compose/compose-file/06-networks.md:
|
||||
description: |
|
||||
Explore all the attributes the networks top-level element can have.
|
||||
keywords: |
|
||||
compose, compose specification, networks, compose file reference
|
||||
|
||||
compose/compose-file/07-volumes.md:
|
||||
description: |
|
||||
Explore all the attributes the volumes top-level element can have.
|
||||
keywords: |
|
||||
compose, compose specification, volumes, compose file reference
|
||||
|
||||
compose/compose-file/08-configs.md:
|
||||
description: |
|
||||
Explore all the attributes the configs top-level element can have.
|
||||
keywords: |
|
||||
compose, compose specification, configs, compose file reference
|
||||
|
||||
compose/compose-file/09-secrets.md:
|
||||
description: |
|
||||
Explore all the attributes the secrets top-level element can have.
|
||||
keywords: |
|
||||
compose, compose specification, secrets, compose file reference
|
||||
|
||||
compose/compose-file/14-include.md:
|
||||
description: |
|
||||
Explore all the attributes the includes top-level element can have.
|
||||
keywords: |
|
||||
compose, compose specification, includes, compose file reference
|
||||
|
||||
compose/compose-file/build.md:
|
||||
description: |
|
||||
Learn about the optional Build Specification.
|
||||
keywords: |
|
||||
compose, build specification, compose file reference
|
||||
|
||||
compose/compose-file/deploy.md:
|
||||
description: |
|
||||
Learn about the optional Deploy Specification.
|
||||
keywords: |
|
||||
compose, deploy specification, compose file reference
|
||||
|
||||
compose/compose-file/develop.md:
|
||||
description: |
|
||||
Learn about the optional Develop Specification.
|
||||
keywords: |
|
||||
compose, develop specification, compose file reference
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ long: |-
|
|||
|
||||
* [.dockerignore](../../../engine/reference/builder.md#dockerignore-file)
|
||||
* [Dockerfile](../../../engine/reference/builder.md)
|
||||
* [compose.yaml](../../../compose/compose-file/03-compose-file.md)
|
||||
* [compose.yaml](../../../compose/compose-yaml-file.md)
|
||||
|
||||
usage: docker init [OPTIONS]
|
||||
pname: docker
|
||||
|
|
|
|||
|
|
@ -959,12 +959,6 @@ Reference:
|
|||
section:
|
||||
- path: /compose/compose-file/
|
||||
title: Overview
|
||||
- path: /compose/compose-file/01-status/
|
||||
title: Status of the specification
|
||||
- path: /compose/compose-file/02-model/
|
||||
title: Compose application model
|
||||
- path: /compose/compose-file/03-compose-file/
|
||||
title: The Compose file
|
||||
- path: /compose/compose-file/04-version-and-name/
|
||||
title: Version and name top-level element
|
||||
- path: /compose/compose-file/05-services/
|
||||
|
|
@ -1945,6 +1939,10 @@ Manuals:
|
|||
title: Overview
|
||||
- path: /compose/features-uses/
|
||||
title: Key features and use cases
|
||||
- path: /compose/compose-application-model/
|
||||
title: Understand the Compose application model
|
||||
- path: /compose/compose-yaml-file/
|
||||
title: Understand the Compose file
|
||||
- path: /compose/history/
|
||||
title: History and development of Compose
|
||||
- sectiontitle: Install Docker Compose
|
||||
|
|
|
|||
1
go.mod
1
go.mod
|
|
@ -5,7 +5,6 @@ go 1.21
|
|||
toolchain go1.21.1
|
||||
|
||||
require (
|
||||
github.com/compose-spec/compose-spec v0.0.0-20231121152139-478928e7c9f8 // indirect
|
||||
github.com/docker/buildx v0.12.1 // indirect
|
||||
github.com/docker/cli v25.0.0-rc.1+incompatible // indirect
|
||||
github.com/docker/compose/v2 v2.24.0 // indirect
|
||||
|
|
|
|||
39
hugo.yaml
39
hugo.yaml
|
|
@ -280,45 +280,6 @@ module:
|
|||
- source: docs/reference/commandline/dockerd.md
|
||||
target: content/engine/reference/commandline/dockerd.md
|
||||
|
||||
- path: github.com/compose-spec/compose-spec
|
||||
mounts:
|
||||
- source: 01-status.md
|
||||
target: content/compose/compose-file/01-status.md
|
||||
- source: 02-model.md
|
||||
target: content/compose/compose-file/02-model.md
|
||||
- source: 03-compose-file.md
|
||||
target: content/compose/compose-file/03-compose-file.md
|
||||
- source: 04-version-and-name.md
|
||||
target: content/compose/compose-file/04-version-and-name.md
|
||||
- source: 05-services.md
|
||||
target: content/compose/compose-file/05-services.md
|
||||
- source: 06-networks.md
|
||||
target: content/compose/compose-file/06-networks.md
|
||||
- source: 07-volumes.md
|
||||
target: content/compose/compose-file/07-volumes.md
|
||||
- source: 08-configs.md
|
||||
target: content/compose/compose-file/08-configs.md
|
||||
- source: 09-secrets.md
|
||||
target: content/compose/compose-file/09-secrets.md
|
||||
- source: 10-fragments.md
|
||||
target: content/compose/compose-file/10-fragments.md
|
||||
- source: 11-extension.md
|
||||
target: content/compose/compose-file/11-extension.md
|
||||
- source: 12-interpolation.md
|
||||
target: content/compose/compose-file/12-interpolation.md
|
||||
- source: 13-merge.md
|
||||
target: content/compose/compose-file/13-merge.md
|
||||
- source: 14-include.md
|
||||
target: content/compose/compose-file/14-include.md
|
||||
- source: 15-profiles.md
|
||||
target: content/compose/compose-file/15-profiles.md
|
||||
- source: build.md
|
||||
target: content/compose/compose-file/build.md
|
||||
- source: deploy.md
|
||||
target: content/compose/compose-file/deploy.md
|
||||
- source: develop.md
|
||||
target: content/compose/compose-file/develop.md
|
||||
|
||||
- path: github.com/docker/compose/v2
|
||||
mounts:
|
||||
- source: docs/reference
|
||||
|
|
|
|||
Loading…
Reference in New Issue