docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Spec split (#16740) 

* split spec

* spec split

* trial branch

* fix

* branch update

* landing page

* add description

* add description

* update file path

* tweak

* fix build

* split spec

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* spec split

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* trial branch

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* fix

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* branch update

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* landing page

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* add description

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* add description

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* update file path

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* tweak

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* fix build

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* missing new line

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* first batch of fix links

* second batch of link fix

* update toc

---------

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
Co-authored-by: CrazyMax <crazy-max@users.noreply.github.com>
This commit is contained in:
Allie Sadler 2023-03-22 12:00:04 +00:00 committed by GitHub
parent e04f063645
commit 855cda4011
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 281 additions and 2545 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
_config.yml
View File

@ -215,3 +215,44 @@ fetch-remote:
- dest: "build/attestations/attestation-storage.md" - dest: "build/attestations/attestation-storage.md"
src: src:
- "docs/attestations/attestation-storage.md" - "docs/attestations/attestation-storage.md"
- repo: "https://github.com/compose-spec/compose-spec"
default_branch: "master"
ref: "master"
paths:
- dest: "compose/compose-file/status.md"
src:
- "01-status.md"
- dest: "compose/compose-file/model.md"
src:
- "02-model.md"
- dest: "compose/compose-file/compose-file.md"
src:
- "03-compose-file.md"
- dest: "compose/compose-file/version-and-name.md"
src:
- "04-version-and-name.md"
- dest: "compose/compose-file/services.md"
src:
- "05-services.md"
- dest: "compose/compose-file/networks.md"
src:
- "06-networks.md"
- dest: "compose/compose-file/volumes.md"
src:
- "07-volumes.md"
- dest: "compose/compose-file/configs.md"
src:
- "08-configs.md"
- dest: "compose/compose-file/secrets.md"
src:
- "09-secrets.md"
- dest: "compose/compose-file/fragments.md"
src:
- "10-fragments.md"
- dest: "compose/compose-file/extension.md"
src:
- "11-extension.md"
- dest: "compose/compose-file/interpolation.md"
src:
- "12-interpolation.md"

30
_data/toc.yaml
View File

@ -884,8 +884,34 @@ reference:
path: /engine/reference/builder/ path: /engine/reference/builder/
- sectiontitle: Compose file reference - sectiontitle: Compose file reference
section: section:
- path: /compose/compose-file/ - sectiontitle: Compose specification
title: Compose Specification 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/build/04-version-and-name/
title: Version and name top-level element
- path: /compose/compose-file/05-services/
title: Services top-level element
- path: /compose/compose-file/06-networks/
title: Network top-level element
- path: /compose/compose-file/07-volumes/
title: Volumes top-level element
- path: /compose/compose-file/08-configs/
title: Configs top-level element
- path: /compose/compose-file/09-secrets/
title: Secrets top-level element
- path: /compose/compose-file/10-fragments/
title: Fragments
- path: /compose/compose-file/11-extensions/
title: Extensions
- path: /compose/compose-file/12-interpolation/
title: Interpolation
- path: /compose/compose-file/build/ - path: /compose/compose-file/build/
title: Compose file build title: Compose file build
- path: /compose/compose-file/deploy/ - path: /compose/compose-file/deploy/

4
build/bake/compose-file.md
View File

@ -98,7 +98,7 @@ Unlike the [HCL format](file-definition.md#hcl-definition), there are some
limitations with the compose format: limitations with the compose format:
* Specifying variables or global scope attributes is not yet supported * Specifying variables or global scope attributes is not yet supported
* `inherits` service field is not supported, but you can use [YAML anchors](https://docs.docker.com/compose/compose-file/#fragments){:target="blank" rel="noopener" class=""} * `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md){:target="blank" rel="noopener" class=""}
to reference other services like the example above to reference other services like the example above
## `.env` file ## `.env` file
@ -155,7 +155,7 @@ $ docker buildx bake --print
## Extension field with `x-bake` ## Extension field with `x-bake`
Even if some fields are not (yet) available in the compose specification, you Even if some fields are not (yet) available in the compose specification, you
can use the [special extension](../../compose/compose-file/index.md#extension) can use the [special extension](../../compose/compose-file/11-extension.md)
field `x-bake` in your compose file to evaluate extra fields: field `x-bake` in your compose file to evaluate extra fields:
```yaml ```yaml

7
compose/compose-file/01-status.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Status of the specification
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/02-model.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Compose application model
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/03-compose-file.md Normal file
View File

@ -0,0 +1,7 @@
---
title: The Compose file
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/04-version-and-name.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Version and name top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/05-services.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Services top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/06-networks.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Networks top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/07-volumes.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Volumes top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/08-configs.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Configs top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/09-secrets.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Secrets top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/10-fragments.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Fragments
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/11-extension.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Extensions
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

7
compose/compose-file/12-interpolation.md Normal file
View File

@ -0,0 +1,7 @@
---
title: Interpolation
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

16
compose/compose-file/build.md
View File

@ -229,7 +229,7 @@ Unsupported cache target MUST be ignored and not prevent user from building imag
### extra_hosts ### extra_hosts
`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](index.md#extra_hosts). `extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](05-services.md#extra_hosts).
```yml ```yml
extra_hosts: extra_hosts:
@ -247,7 +247,7 @@ configuration, which means for Linux `/etc/hosts` will get extra lines:
### isolation ### isolation
`isolation` specifies a build’s container isolation technology. Like [isolation](index.md#isolation) supported values `isolation` specifies a build’s container isolation technology. Like [isolation](05-services.md#isolation) supported values
are platform-specific. are platform-specific.
### labels ### labels
@ -288,7 +288,7 @@ available in the local image store.
### shm_size ### shm_size
`shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify `shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify
as an integer value representing the number of bytes or as a string expressing a [byte value](index.md#specifying-byte-values). as an integer value representing the number of bytes or as a string expressing a [byte value](11-extension.md#specifying-byte-values).
```yml ```yml
build: build:
@ -313,11 +313,11 @@ build:
``` ```
### secrets ### secrets
`secrets` grants access to sensitive data defined by [secrets](index.md#secrets) on a per-service build basis. Two `secrets` grants access to sensitive data defined by [secrets](05-services.md#secrets) on a per-service build basis. Two
different syntax variants are supported: the short syntax and the long syntax. different syntax variants are supported: the short syntax and the long syntax.
Compose implementations MUST report an error if the secret isn't defined in the Compose implementations MUST report an error if the secret isn't defined in the
[`secrets`](index.md#secrets-top-level-element) section of the Compose file. [`secrets`](09-secrets.md) section of the Compose file.
#### Short syntax #### Short syntax
@ -380,12 +380,12 @@ secrets:
Service builds MAY be granted access to multiple secrets. Long and short syntax for secrets MAY be used in the Service builds MAY be granted access to multiple secrets. Long and short syntax for secrets MAY be used in the
same Compose file. Defining a secret in the top-level `secrets` MUST NOT imply granting any service build access to it. same Compose file. Defining a secret in the top-level `secrets` MUST NOT imply granting any service build access to it.
Such grant must be explicit within the service specification as a [secrets](index.md#secrets) service element. Such grant must be explicit within the service specification as a [secrets](05-services.md#secrets) service element.
### tags ### tags
`tags` defines a list of tag mappings that MUST be associated to the build image. This list comes in addition of `tags` defines a list of tag mappings that MUST be associated to the build image. This list comes in addition of
the `image` [property defined in the service section](index.md#image) the `image` [property defined in the service section](05-services.md#image)
```yml ```yml
tags: tags:
@ -395,7 +395,7 @@ tags:
### platforms ### platforms
`platforms` defines a list of target [platforms](index.md#platform). `platforms` defines a list of target [platforms](05-services.md#platform).
```yml ```yml
build: build:

6
compose/compose-file/deploy.md
View File

@ -155,7 +155,7 @@ services:
`memory` configures a limit or reservation on the amount of memory a container `memory` configures a limit or reservation on the amount of memory a container
can allocate, set as a string expressing a can allocate, set as a string expressing a
[byte value](index.md#specifying-byte-values). [byte value](11-extension.md#specifying-byte-values).
#### pids #### pids
@ -249,11 +249,11 @@ deploy:
`restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose implementations MUST consider `restart` field set by service configuration. `restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose implementations MUST consider `restart` field set by service configuration.
- `condition`: One of `none`, `on-failure` or `any` (default: `any`). - `condition`: One of `none`, `on-failure` or `any` (default: `any`).
- `delay`: How long to wait between restart attempts, specified as a [duration](index.md#specifying-durations) (default: 0). - `delay`: How long to wait between restart attempts, specified as a [duration](11-extension.md#specifying-durations) (default: 0).
- `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not - `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not
succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value. succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value.
For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts MUST be attempted. For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts MUST be attempted.
- `window`: How long to wait before deciding if a restart has succeeded, specified as a [duration](index.md#specifying-durations) (default: - `window`: How long to wait before deciding if a restart has succeeded, specified as a [duration](11-extension.md#specifying-durations) (default:
decide immediately). decide immediately).
```yml ```yml

2605
compose/compose-file/index.md
View File

File diff suppressed because it is too large Load Diff

10
compose/environment-variables/set-environment-variables.md
View File

@ -43,7 +43,7 @@ services:
The `.env` file should be placed at the root of the project directory next to your `docker-compose.yml` file. You can use an alternative path with one of the following methods: The `.env` file should be placed at the root of the project directory next to your `docker-compose.yml` file. You can use an alternative path with one of the following methods:
- The [`--file` option in the CLI](../reference/index.md#use--f-to-specify-name-and-path-of-one-or-more-compose-files) - The [`--file` option in the CLI](../reference/index.md#use--f-to-specify-name-and-path-of-one-or-more-compose-files)
- The [`--env-file` option in the CLI](#substitute-with---env-file) - The [`--env-file` option in the CLI](#substitute-with---env-file)
- Using the [`env_file` attribute in the Compose file](../compose-file/index.md#env_file) - Using the [`env_file` attribute in the Compose file](../compose-file/05-services.md#env_file)
For more information on formatting an environment file, see [Use an environment file](env-file.md). For more information on formatting an environment file, see [Use an environment file](env-file.md).
@ -56,7 +56,7 @@ For more information on formatting an environment file, see [Use an environment
### Use the `environment` attribute ### Use the `environment` attribute
You can set environment variables in a service's containers with the You can set environment variables in a service's containers with the
[`environment` attribute](../compose-file/index.md#environment) in your Compose file. It works in the same way as `docker run -e VARIABLE=VALUE ...` [`environment` attribute](../compose-file/05-services.md#environment) in your Compose file. It works in the same way as `docker run -e VARIABLE=VALUE ...`
```yaml ```yaml
web: web:
@ -75,12 +75,12 @@ web:
The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run. The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run.
See [`environment` attribute](../compose-file/index.md#environment) for more information. See [`environment` attribute](../compose-file/05-services.md#environment) for more information.
### Use the `env_file` attribute ### Use the `env_file` attribute
You can pass multiple environment variables from an external file through to You can pass multiple environment variables from an external file through to
a service's containers with the [`env_file` option](../compose-file/index.md#env_file). This works in the same way as `docker run --env-file=FILE ...`: a service's containers with the [`env_file` option](../compose-file/05-services.md#env_file). This works in the same way as `docker run --env-file=FILE ...`:
```yaml ```yaml
web: web:
@ -94,7 +94,7 @@ If multiple files are specified, they are evaluated in order and can override va
> >
>With this option, environment variables declared in the file cannot then be referenced again separately in the Compose file or used to configure Compose. >With this option, environment variables declared in the file cannot then be referenced again separately in the Compose file or used to configure Compose.
See [`env_file` attribute](../compose-file/index.md#env_file) for more information. See [`env_file` attribute](../compose-file/05-services.md#env_file) for more information.
### Substitute from the shell ### Substitute from the shell

2
compose/extends.md
View File

@ -446,4 +446,4 @@ services:
## Reference information ## Reference information
[`extends`](compose-file/index.md#extends) [`extends`](compose-file/05-services.md#extends)

14
compose/networking.md
View File

@ -82,14 +82,14 @@ services:
image: postgres image: postgres
``` ```
See the [links reference](compose-file/index.md#links) for more information. See the [links reference](compose-file/05-services.md#links) for more information.
## Multi-host networking ## Multi-host networking
When deploying a Compose application on a Docker Engine with [Swarm mode enabled](../engine/swarm/index.md), When deploying a Compose application on a Docker Engine with [Swarm mode enabled](../engine/swarm/index.md),
you can make use of the built-in `overlay` driver to enable multi-host communication. you can make use of the built-in `overlay` driver to enable multi-host communication.
Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](compose-file/index.md#attachable) property to `false`. Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](compose-file/06-networks.md#attachable) property to `false`.
Consult the [Swarm mode section](../engine/swarm/index.md), to see how to set up Consult the [Swarm mode section](../engine/swarm/index.md), to see how to set up
a Swarm cluster, and the [Getting started with multi-host networking](../network/network-tutorial-overlay.md) a Swarm cluster, and the [Getting started with multi-host networking](../network/network-tutorial-overlay.md)
@ -131,9 +131,9 @@ networks:
bar: "2" bar: "2"
``` ```
Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/index.md#ipv4_address-ipv6_address) for each attached network. Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/05-services.md#ipv4_address-ipv6_address) for each attached network.
Networks can also be given a [custom name](compose-file/index.md#name): Networks can also be given a [custom name](compose-file/06-networks.md#name):
```yaml ```yaml
services: services:
@ -165,7 +165,7 @@ networks:
## Use a pre-existing network ## Use a pre-existing network
If you want your containers to join a pre-existing network, use the [`external` option](compose-file/index.md#external) If you want your containers to join a pre-existing network, use the [`external` option](compose-file/06-networks.md#external)
```yaml ```yaml
services: services:
# ... # ...
@ -181,5 +181,5 @@ Instead of attempting to create a network called `[projectname]_default`, Compos
For full details of the network configuration options available, see the following references: For full details of the network configuration options available, see the following references:
- [Top-level `networks` key](compose-file/index.md#networks-top-level-element) - [Top-level `networks` key](compose-file/06-networks)
- [Service-level `networks` key](compose-file/index.md#networks) - [Service-level `networks` key](compose-file/05-services.md#networks)

2
compose/production.md
View File

@ -23,7 +23,7 @@ production. These changes might include:
- Binding to different ports on the host - Binding to different ports on the host
- Setting environment variables differently, such as reducing the verbosity of - Setting environment variables differently, such as reducing the verbosity of
logging, or to specify settings for external services such as an email server logging, or to specify settings for external services such as an email server
- Specifying a restart policy like [`restart: always`](compose-file/index.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime - Specifying a restart policy like [`restart: always`](compose-file/05-services.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime
- Adding extra services such as a log aggregator - Adding extra services such as a log aggregator
For this reason, consider defining an additional Compose file, say For this reason, consider defining an additional Compose file, say

4
compose/profiles.md
View File

@ -18,7 +18,7 @@ development tasks.
## Assigning profiles to services ## Assigning profiles to services
Services are associated with profiles through the Services are associated with profiles through the
[`profiles` attribute](compose-file/index.md#profiles) which takes an [`profiles` attribute](compose-file/05-services.md#profiles) which takes an
array of profile names: array of profile names:
```yaml ```yaml
@ -183,4 +183,4 @@ $ COMPOSE_PROFILES=dev docker compose up phpmyadmin
## Reference information ## Reference information
[`profiles`](compose-file/index.md#profiles) [`profiles`](compose-file/05-services.md#profiles)

6
compose/startup-order.md
View File

@ -7,7 +7,7 @@ notoc: true
{% include compose-eol.md %} {% include compose-eol.md %}
You can control the order of service startup and shutdown with the You can control the order of service startup and shutdown with the
[depends_on](compose-file/index.md#depends_on) option. Compose always starts and stops [depends_on](compose-file/05-services.md#depends_on) option. Compose always starts and stops
containers in dependency order, where dependencies are determined by containers in dependency order, where dependencies are determined by
`depends_on`, `links`, `volumes_from`, and `network_mode: "service:..."`. `depends_on`, `links`, `volumes_from`, and `network_mode: "service:..."`.
@ -25,6 +25,6 @@ The solution for detecting the ready state of a service is to use the `conditio
## Reference information ## Reference information
- [`depends_on`](compose-file/index.md#depends_on) - [`depends_on`](compose-file/05-services.md#depends_on)
- [`healthcheck`](compose-file/index.md#healthcheck) - [`healthcheck`](compose-file/05-services.md#depends_on)

2
storage/volumes.md
View File

@ -245,7 +245,7 @@ volumes:
``` ```
For more information about using volumes with Compose, refer to the For more information about using volumes with Compose, refer to the
[Volumes](../compose/compose-file/index.md#volumes) [Volumes](../compose/compose-file/07-volumes.md)
section in the Compose specification. section in the Compose specification.
### Start a service with volumes ### Start a service with volumes