From 83f11aeb521bc9424fb08bf9901ae26dab233783 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Fri, 12 Jan 2024 14:39:18 +0000 Subject: [PATCH] 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 --- .../compose-spec/compose-spec/01-status.md | 24 ---- .../compose-spec/12-interpolation.md | 61 --------- _vendor/modules.txt | 3 +- .../compose/compose-application-model.md | 22 +-- .../compose-file}/04-version-and-name.md | 10 +- .../compose/compose-file}/05-services.md | 64 +++++++-- .../compose/compose-file}/06-networks.md | 10 +- .../compose/compose-file}/07-volumes.md | 7 +- .../compose/compose-file}/08-configs.md | 8 +- .../compose/compose-file}/09-secrets.md | 8 +- .../compose/compose-file}/10-fragments.md | 6 +- .../compose/compose-file}/11-extension.md | 12 +- .../compose/compose-file/12-interpolation.md | 125 ++++++++++++++++++ .../compose/compose-file}/13-merge.md | 8 +- .../compose/compose-file}/14-include.md | 8 +- .../compose/compose-file}/15-profiles.md | 8 +- content/compose/compose-file/_index.md | 20 +-- .../compose/compose-file}/build.md | 28 +++- .../compose/compose-file}/deploy.md | 8 +- .../compose/compose-file}/develop.md | 11 +- .../compose/compose-yaml-file.md | 24 ++-- data/frontmatter.yaml | 72 ---------- data/init-cli/docker_init.yaml | 2 +- data/toc.yaml | 10 +- go.mod | 1 - hugo.yaml | 39 ------ 26 files changed, 314 insertions(+), 285 deletions(-) delete mode 100644 _vendor/github.com/compose-spec/compose-spec/01-status.md delete mode 100644 _vendor/github.com/compose-spec/compose-spec/12-interpolation.md rename _vendor/github.com/compose-spec/compose-spec/02-model.md => content/compose/compose-application-model.md (70%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/04-version-and-name.md (84%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/05-services.md (97%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/06-networks.md (96%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/07-volumes.md (95%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/08-configs.md (92%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/09-secrets.md (91%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/10-fragments.md (94%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/11-extension.md (95%) create mode 100644 content/compose/compose-file/12-interpolation.md rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/13-merge.md (96%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/14-include.md (96%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/15-profiles.md (92%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/build.md (97%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/deploy.md (97%) rename {_vendor/github.com/compose-spec/compose-spec => content/compose/compose-file}/develop.md (92%) rename _vendor/github.com/compose-spec/compose-spec/03-compose-file.md => content/compose/compose-yaml-file.md (55%) diff --git a/_vendor/github.com/compose-spec/compose-spec/01-status.md b/_vendor/github.com/compose-spec/compose-spec/01-status.md deleted file mode 100644 index dede8b3071..0000000000 --- a/_vendor/github.com/compose-spec/compose-spec/01-status.md +++ /dev/null @@ -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'. diff --git a/_vendor/github.com/compose-spec/compose-spec/12-interpolation.md b/_vendor/github.com/compose-spec/compose-spec/12-interpolation.md deleted file mode 100644 index a0a30c829e..0000000000 --- a/_vendor/github.com/compose-spec/compose-spec/12-interpolation.md +++ /dev/null @@ -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" -``` diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 8cefea290b..a7d9c9e7a8 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -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 \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/02-model.md b/content/compose/compose-application-model.md similarity index 70% rename from _vendor/github.com/compose-spec/compose-spec/02-model.md rename to content/compose/compose-application-model.md index 3e00d9bcc8..962ac61a4b 100644 --- a/_vendor/github.com/compose-spec/compose-spec/02-model.md +++ b/content/compose/compose-application-model.md @@ -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. \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/04-version-and-name.md b/content/compose/compose-file/04-version-and-name.md similarity index 84% rename from _vendor/github.com/compose-spec/compose-spec/04-version-and-name.md rename to content/compose/compose-file/04-version-and-name.md index cf833d69d3..21f21161da 100644 --- a/_vendor/github.com/compose-spec/compose-spec/04-version-and-name.md +++ b/content/compose/compose-file/04-version-and-name.md @@ -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}" -``` +``` \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/05-services.md b/content/compose/compose-file/05-services.md similarity index 97% rename from _vendor/github.com/compose-spec/compose-spec/05-services.md rename to content/compose/compose-file/05-services.md index 99c3da464c..7b3dd1860f 100644 --- a/_vendor/github.com/compose-spec/compose-spec/05-services.md +++ b/content/compose/compose-file/05-services.md @@ -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 `/[]` or `/[]` 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`. \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/06-networks.md b/content/compose/compose-file/06-networks.md similarity index 96% rename from _vendor/github.com/compose-spec/compose-spec/06-networks.md rename to content/compose/compose-file/06-networks.md index 9423563cf4..fa5315d8e0 100644 --- a/_vendor/github.com/compose-spec/compose-spec/06-networks.md +++ b/content/compose/compose-file/06-networks.md @@ -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}" -``` +``` \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/07-volumes.md b/content/compose/compose-file/07-volumes.md similarity index 95% rename from _vendor/github.com/compose-spec/compose-spec/07-volumes.md rename to content/compose/compose-file/07-volumes.md index 7efb4ecf85..c030993bba 100644 --- a/_vendor/github.com/compose-spec/compose-spec/07-volumes.md +++ b/content/compose/compose-file/07-volumes.md @@ -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 ``` - diff --git a/_vendor/github.com/compose-spec/compose-spec/08-configs.md b/content/compose/compose-file/08-configs.md similarity index 92% rename from _vendor/github.com/compose-spec/compose-spec/08-configs.md rename to content/compose/compose-file/08-configs.md index e4be965c95..aaa39122d0 100644 --- a/_vendor/github.com/compose-spec/compose-spec/08-configs.md +++ b/content/compose/compose-file/08-configs.md @@ -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. \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/09-secrets.md b/content/compose/compose-file/09-secrets.md similarity index 91% rename from _vendor/github.com/compose-spec/compose-spec/09-secrets.md rename to content/compose/compose-file/09-secrets.md index 5b85b3a183..12681f3ad9 100644 --- a/_vendor/github.com/compose-spec/compose-spec/09-secrets.md +++ b/content/compose/compose-file/09-secrets.md @@ -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. \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/10-fragments.md b/content/compose/compose-file/10-fragments.md similarity index 94% rename from _vendor/github.com/compose-spec/compose-spec/10-fragments.md rename to content/compose/compose-file/10-fragments.md index 47af51e9e7..c2c5ced00d 100644 --- a/_vendor/github.com/compose-spec/compose-spec/10-fragments.md +++ b/content/compose/compose-file/10-fragments.md @@ -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. diff --git a/_vendor/github.com/compose-spec/compose-spec/11-extension.md b/content/compose/compose-file/11-extension.md similarity index 95% rename from _vendor/github.com/compose-spec/compose-spec/11-extension.md rename to content/compose/compose-file/11-extension.md index c0c1627f96..419c9712d2 100644 --- a/_vendor/github.com/compose-spec/compose-spec/11-extension.md +++ b/content/compose/compose-file/11-extension.md @@ -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 -``` +``` \ No newline at end of file diff --git a/content/compose/compose-file/12-interpolation.md b/content/compose/compose-file/12-interpolation.md new file mode 100644 index 0000000000..04ab6a783e --- /dev/null +++ b/content/compose/compose-file/12-interpolation.md @@ -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" +``` \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/13-merge.md b/content/compose/compose-file/13-merge.md similarity index 96% rename from _vendor/github.com/compose-spec/compose-spec/13-merge.md rename to content/compose/compose-file/13-merge.md index 960c5c39ec..06d6cafb9b 100644 --- a/_vendor/github.com/compose-spec/compose-spec/13-merge.md +++ b/content/compose/compose-file/13-merge.md @@ -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: [] -``` +``` \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/14-include.md b/content/compose/compose-file/14-include.md similarity index 96% rename from _vendor/github.com/compose-spec/compose-spec/14-include.md rename to content/compose/compose-file/14-include.md index 5ad3649bbc..e5031a3d23 100644 --- a/_vendor/github.com/compose-spec/compose-spec/14-include.md +++ b/content/compose/compose-file/14-include.md @@ -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. \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/15-profiles.md b/content/compose/compose-file/15-profiles.md similarity index 92% rename from _vendor/github.com/compose-spec/compose-spec/15-profiles.md rename to content/compose/compose-file/15-profiles.md index bbfc04f61a..a7266007ad 100644 --- a/_vendor/github.com/compose-spec/compose-spec/15-profiles.md +++ b/content/compose/compose-file/15-profiles.md @@ -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). \ No newline at end of file diff --git a/content/compose/compose-file/_index.md b/content/compose/compose-file/_index.md index b45fdb40b5..a223befeda 100644 --- a/content/compose/compose-file/_index.md +++ b/content/compose/compose-file/_index.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). diff --git a/_vendor/github.com/compose-spec/compose-spec/build.md b/content/compose/compose-file/build.md similarity index 97% rename from _vendor/github.com/compose-spec/compose-spec/build.md rename to content/compose/compose-file/build.md index cd1af93018..da9a11995e 100644 --- a/_vendor/github.com/compose-spec/compose-spec/build.md +++ b/content/compose/compose-file/build.md @@ -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" - ``` + ``` \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/deploy.md b/content/compose/compose-file/deploy.md similarity index 97% rename from _vendor/github.com/compose-spec/compose-spec/deploy.md rename to content/compose/compose-file/deploy.md index 156205fedf..ba002195d0 100644 --- a/_vendor/github.com/compose-spec/compose-spec/deploy.md +++ b/content/compose/compose-file/deploy.md @@ -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 -``` +``` \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/develop.md b/content/compose/compose-file/develop.md similarity index 92% rename from _vendor/github.com/compose-spec/compose-spec/develop.md rename to content/compose/compose-file/develop.md index 9b7fbf4a99..1609cf8862 100644 --- a/_vendor/github.com/compose-spec/compose-spec/develop.md +++ b/content/compose/compose-file/develop.md @@ -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. \ No newline at end of file diff --git a/_vendor/github.com/compose-spec/compose-spec/03-compose-file.md b/content/compose/compose-yaml-file.md similarity index 55% rename from _vendor/github.com/compose-spec/compose-spec/03-compose-file.md rename to content/compose/compose-yaml-file.md index 8c5c01908b..32caa5aad2 100644 --- a/_vendor/github.com/compose-spec/compose-spec/03-compose-file.md +++ b/content/compose/compose-yaml-file.md @@ -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. \ No newline at end of file diff --git a/data/frontmatter.yaml b/data/frontmatter.yaml index fb7457c6f6..a0c7f878b4 100644 --- a/data/frontmatter.yaml +++ b/data/frontmatter.yaml @@ -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 diff --git a/data/init-cli/docker_init.yaml b/data/init-cli/docker_init.yaml index 25b9951c2d..6d45e1f5e1 100644 --- a/data/init-cli/docker_init.yaml +++ b/data/init-cli/docker_init.yaml @@ -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 diff --git a/data/toc.yaml b/data/toc.yaml index d9fb04618d..9fe252244a 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -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 diff --git a/go.mod b/go.mod index b9e774af20..2177104642 100644 --- a/go.mod +++ b/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 diff --git a/hugo.yaml b/hugo.yaml index 9e05675f16..a088a6c668 100644 --- a/hugo.yaml +++ b/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