mirror of https://github.com/docker/docs.git
ENGDOCS-1690 (#18298)
* vendor: github.com/compose-spec/compose-spec v0.0.0-20230927132538-f223c5150d5d Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> * ENGDOCS-1690 --------- Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> Co-authored-by: Allie Sadler <alliesadler@f693mt7fh6.home>
This commit is contained in:
Allie Sadler
GitHub
parent
c9cce3c318
commit
8d8014a8bb
|
|
@ -16,7 +16,7 @@ A [secret](09-secrets.md) is a specific flavor of configuration data for sensiti
|
|||
>
|
||||
> 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 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`](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`.
|
||||
|
||||
|
|
@ -82,7 +82,7 @@ The example application is composed of the following parts:
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
ports:
|
||||
- "443:8043"
|
||||
networks:
|
||||
|
|
@ -94,7 +94,7 @@ services:
|
|||
- server-certificate
|
||||
|
||||
backend:
|
||||
image: awesome/database
|
||||
image: example/database
|
||||
volumes:
|
||||
- db-data:/etc/data
|
||||
networks:
|
||||
|
|
|
|||
|
|
@ -418,6 +418,10 @@ Compose guarantees dependency services marked with
|
|||
|
||||
`deploy` specifies the configuration for the deployment and lifecycle of services, as defined [in the Compose Deploy Specification](deploy.md).
|
||||
|
||||
### develop
|
||||
|
||||
`develop` specifies the development configuration for maintaining a container in sync with source, as defined in the [Development Section](develop.md).
|
||||
|
||||
### device_cgroup_rules
|
||||
|
||||
`device_cgroup_rules` defines a list of device cgroup rules for this container.
|
||||
|
|
@ -1138,18 +1142,18 @@ is able to reach same `backend` service at `backend` or `mysql` on the `admin` n
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
networks:
|
||||
- front-tier
|
||||
- back-tier
|
||||
|
||||
monitoring:
|
||||
image: awesome/monitoring
|
||||
image: example/monitoring
|
||||
networks:
|
||||
- admin
|
||||
|
||||
backend:
|
||||
image: awesome/backend
|
||||
image: example/backend
|
||||
networks:
|
||||
back-tier:
|
||||
aliases:
|
||||
|
|
@ -1174,7 +1178,7 @@ The corresponding network configuration in the [top-level networks section](06-n
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
networks:
|
||||
front-tier:
|
||||
ipv4_address: 172.16.238.10
|
||||
|
|
@ -1492,7 +1496,7 @@ to the contents of the file `./server.cert`.
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
secrets:
|
||||
- server-certificate
|
||||
secrets:
|
||||
|
|
@ -1525,7 +1529,7 @@ the secret's lifecycle is not directly managed by Compose.
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
secrets:
|
||||
- source: server-certificate
|
||||
target: server.cert
|
||||
|
|
@ -1667,7 +1671,7 @@ and a bind mount defined for a single service.
|
|||
```yml
|
||||
services:
|
||||
backend:
|
||||
image: awesome/backend
|
||||
image: example/backend
|
||||
volumes:
|
||||
- type: volume
|
||||
source: db-data
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ is connected to `front-tier` and `back-tier` networks.
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
networks:
|
||||
- front-tier
|
||||
- back-tier
|
||||
|
|
@ -134,7 +134,7 @@ networks:
|
|||
|
||||
#### enable_ipv6
|
||||
|
||||
`enable_ipv6` enables IPv6 networking.
|
||||
`enable_ipv6` enables IPv6 networking. For an example, see step four of [Create an IPv6 network](https://docs.docker.com/config/daemon/ipv6/).
|
||||
|
||||
### external
|
||||
|
||||
|
|
@ -151,12 +151,12 @@ queries the platform for an existing network simply called `outside` and connect
|
|||
|
||||
services:
|
||||
proxy:
|
||||
image: awesome/proxy
|
||||
image: example/proxy
|
||||
networks:
|
||||
- outside
|
||||
- default
|
||||
app:
|
||||
image: awesome/app
|
||||
image: example/app
|
||||
networks:
|
||||
- default
|
||||
|
||||
|
|
@ -181,18 +181,18 @@ networks:
|
|||
networks:
|
||||
mynet1:
|
||||
ipam:
|
||||
driver: default
|
||||
config:
|
||||
- subnet: 172.28.0.0/16
|
||||
ip_range: 172.28.5.0/24
|
||||
gateway: 172.28.5.254
|
||||
aux_addresses:
|
||||
host1: 172.28.1.5
|
||||
host2: 172.28.1.6
|
||||
host3: 172.28.1.7
|
||||
options:
|
||||
foo: bar
|
||||
baz: "0"
|
||||
driver: default
|
||||
config:
|
||||
- subnet: 172.28.0.0/16
|
||||
ip_range: 172.28.5.0/24
|
||||
gateway: 172.28.5.254
|
||||
aux_addresses:
|
||||
host1: 172.28.1.5
|
||||
host2: 172.28.1.6
|
||||
host3: 172.28.1.7
|
||||
options:
|
||||
foo: bar
|
||||
baz: "0"
|
||||
```
|
||||
|
||||
### internal
|
||||
|
|
@ -246,4 +246,3 @@ networks:
|
|||
external: true
|
||||
name: "${NETWORK_ID}"
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ The following example shows a two-service setup where a database's data director
|
|||
```yml
|
||||
services:
|
||||
backend:
|
||||
image: awesome/database
|
||||
image: example/database
|
||||
volumes:
|
||||
- db-data:/etc/data
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ called `db-data` and mounts it into the `backend` service's containers.
|
|||
```yml
|
||||
services:
|
||||
backend:
|
||||
image: awesome/database
|
||||
image: example/database
|
||||
volumes:
|
||||
- db-data:/etc/data
|
||||
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ to avoid repetition but overrides `name` attribute:
|
|||
|
||||
services:
|
||||
backend:
|
||||
image: awesome/database
|
||||
image: example/database
|
||||
volumes:
|
||||
- db-data
|
||||
- metrics
|
||||
|
|
|
|||
|
|
@ -2,10 +2,11 @@
|
|||
|
||||
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).
|
||||
|
||||
Use the prefix `x-` on any top-level element to modularize configurations that you want to reuse. They can be used
|
||||
within any structure in a Compose file as Compose ignores any fields that start with `x-`. This is the sole exception where Compose silently ignores unrecognized fields.
|
||||
Use the prefix `x-` as a top-level element to modularize configurations that you want to reuse.
|
||||
Compose ignores any fields that start with `x-`, this is the sole exception where Compose silently ignores unrecognized fields.
|
||||
|
||||
The contents of any `x-` section is unspecified by the Compose specification, so it can be used to enable custom features. If Compose encounters an unknown extension field it doesn't fail and may warn you about the unknown field.
|
||||
They also can be used within any structure in a Compose file where user-defined keys are not expected.
|
||||
Compose use those to enable experimental features, the same way browsers add support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords)
|
||||
|
||||
### Example 1
|
||||
|
||||
|
|
@ -17,13 +18,10 @@ x-custom:
|
|||
|
||||
services:
|
||||
webapp:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
x-foo: bar
|
||||
```
|
||||
|
||||
For platform extensions, it's highly recommended that you prefix extensions by platform or vendor name, the same way browsers add
|
||||
support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords)
|
||||
|
||||
```yml
|
||||
service:
|
||||
backend:
|
||||
|
|
@ -101,7 +99,7 @@ x-keys: &keys
|
|||
KEY: VALUE
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
environment:
|
||||
<< : [*default-environment, *keys]
|
||||
YET_ANOTHER: VARIABLE
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
## Merge and override
|
||||
|
||||
Compose lets you define a Compose application model through multiple Compose files.
|
||||
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.
|
||||
|
||||
### Mapping
|
||||
|
|
|
|||
|
|
@ -45,11 +45,11 @@ The following example illustrates Compose Build Specification concepts with a co
|
|||
```yaml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
build: ./webapp
|
||||
|
||||
backend:
|
||||
image: awesome/database
|
||||
image: example/database
|
||||
build:
|
||||
context: backend
|
||||
dockerfile: ../backend.Dockerfile
|
||||
|
|
@ -60,11 +60,11 @@ services:
|
|||
|
||||
When used to build service images from source, the Compose file creates three Docker images:
|
||||
|
||||
* `awesome/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder throws an error.
|
||||
* `awesome/database`: A Docker image is built using `backend` sub-directory within the Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to the context path, which means `..` resolves to the Compose file parent folder, so `backend.Dockerfile` is a sibling file.
|
||||
* `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder throws an error.
|
||||
* `example/database`: A Docker image is built using `backend` sub-directory within the Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to the context path, which means `..` resolves to the Compose file parent folder, so `backend.Dockerfile` is a sibling file.
|
||||
* A Docker image is built using the `custom` directory with the user's HOME as the Docker context. Compose displays a warning about the non-portable path used to build image.
|
||||
|
||||
On push, both `awesome/webapp` and `awesome/database` Docker images are pushed to the default registry. The `custom` service image is skipped as no `image` attribute is set and Compose displays a warning about this missing attribute.
|
||||
On push, both `example/webapp` and `example/database` Docker images are pushed to the default registry. The `custom` service image is skipped as no `image` attribute is set and Compose displays a warning about this missing attribute.
|
||||
|
||||
## Attributes
|
||||
|
||||
|
|
@ -353,6 +353,30 @@ has been updated on registry (see [pull](#pull)).
|
|||
`pull` requires the image builder to pull referenced images (`FROM` Dockerfile directive), even if those are already
|
||||
available in the local image store.
|
||||
|
||||
### network
|
||||
|
||||
Set the network containers connect to for the `RUN` instructions during build.
|
||||
|
||||
```yaml
|
||||
build:
|
||||
context: .
|
||||
network: host
|
||||
```
|
||||
|
||||
```yaml
|
||||
build:
|
||||
context: .
|
||||
network: custom_network_1
|
||||
```
|
||||
|
||||
Use `none` to disable networking during build:
|
||||
|
||||
```yaml
|
||||
build:
|
||||
context: .
|
||||
network: none
|
||||
```
|
||||
|
||||
### shm_size
|
||||
|
||||
`shm_size` sets the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker images. Specify
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ are platform specific but the Compose Deploy Specification defines two canonical
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
ports:
|
||||
- "8080:80"
|
||||
deploy:
|
||||
|
|
@ -41,7 +41,7 @@ This assumes the platform has some native concept of "service" that can match th
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
deploy:
|
||||
labels:
|
||||
com.example.description: "This label will appear on the web service"
|
||||
|
|
@ -54,7 +54,7 @@ services:
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
deploy:
|
||||
mode: global
|
||||
```
|
||||
|
|
@ -109,7 +109,7 @@ running at any given time.
|
|||
```yml
|
||||
services:
|
||||
fronted:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
deploy:
|
||||
mode: replicated
|
||||
replicas: 6
|
||||
|
|
@ -126,7 +126,7 @@ as:
|
|||
```yml
|
||||
services:
|
||||
frontend:
|
||||
image: awesome/webapp
|
||||
image: example/webapp
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
|
|
|
|||
|
|
@ -0,0 +1,80 @@
|
|||
# Compose Develop Specification
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> Develop is an optional part of the Compose Specification
|
||||
|
||||
## Introduction
|
||||
|
||||
Compose focuses on the development use-case of running applications on a local machine. It also supports some development hooks to improve the velocity of your local workflow, also known as your "inner loop". This document defines how Compose behaves to efficiently assist the developer.
|
||||
|
||||
This section defines the development constraints and workflows set by Compose. Only a subset of
|
||||
Compose file services may require a `develop` subsection.
|
||||
|
||||
## Illustrative example
|
||||
|
||||
```yaml
|
||||
services:
|
||||
frontend:
|
||||
image: example/webapp
|
||||
build: ./webapp
|
||||
develop:
|
||||
watch:
|
||||
# sync static content
|
||||
- path: ./webapp/html
|
||||
action: sync
|
||||
target: /var/www
|
||||
ignore:
|
||||
- node_modules/
|
||||
|
||||
backend:
|
||||
image: example/backend
|
||||
build: ./backend
|
||||
develop:
|
||||
watch:
|
||||
# rebuild image and recreate service
|
||||
- path: ./backend/src
|
||||
action: rebuild
|
||||
```
|
||||
|
||||
## Attributes
|
||||
|
||||
The `develop` subsection defines configuration options that are applied by Compose to assist you during development of a service with optimized workflows.
|
||||
|
||||
### 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/).
|
||||
|
||||
#### action
|
||||
|
||||
`action` defines the action to take when changes are detected. If `action` is set to:
|
||||
|
||||
- `rebuild`, Compose rebuilds the service image based on the `build` section and recreates the service with the updated image.
|
||||
- `sync`, Compose keeps the existing service container(s) running, but synchronizes source files with container content according to the `target` attribute.
|
||||
|
||||
|
||||
#### ignore
|
||||
|
||||
The `ignore` attribute can be used to define a list of patterns for paths to be ignored. Any updated file
|
||||
that matches a pattern, or belongs to a folder that matches a pattern, won't trigger services to be re-created.
|
||||
The syntax is the same as `.dockerignore` file:
|
||||
|
||||
- `*` matches 0 or more characters in a file name.
|
||||
- `?` matches a single character in file name.
|
||||
- `*/*` matches two nested folders with arbitrary names
|
||||
- `**` matches an arbitrary number of nested folders
|
||||
|
||||
If the build context includes a `.dockerignore` file, the patterns in this file is loaded as implicit content
|
||||
for the `ignores` file, and values set in the Compose model are appended.
|
||||
|
||||
#### path
|
||||
|
||||
`path` attribute defines the path to source code (relative to the project directory) to monitor for changes. Updates to any file
|
||||
inside the path, which doesn't match any `ignore` rule, triggers the configured action.
|
||||
|
||||
#### target
|
||||
|
||||
`target` 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.
|
||||
|
||||
|
|
@ -5,4 +5,4 @@
|
|||
# github.com/docker/cli v24.0.5+incompatible
|
||||
# github.com/docker/compose-cli v1.0.35
|
||||
# github.com/distribution/distribution v2.8.2+incompatible
|
||||
# github.com/compose-spec/compose-spec v0.0.0-20230824062516-848a47ad5d0e
|
||||
# github.com/compose-spec/compose-spec v0.0.0-20230927132538-f223c5150d5d
|
||||
|
|
|
|||
|
|
@ -969,6 +969,8 @@ Reference:
|
|||
title: Compose Build Specification
|
||||
- path: /compose/compose-file/deploy/
|
||||
title: Compose Deploy Specification
|
||||
- path: /compose/compose-file/develop/
|
||||
title: Compose Develop Specification
|
||||
- sectiontitle: Legacy versions
|
||||
section:
|
||||
- path: /compose/compose-file/compose-versioning/
|
||||
|
|
|
|||
2
go.mod
2
go.mod
|
|
@ -3,7 +3,7 @@ module github.com/docker/docs
|
|||
go 1.20
|
||||
|
||||
require (
|
||||
github.com/compose-spec/compose-spec v0.0.0-20230824062516-848a47ad5d0e // indirect
|
||||
github.com/compose-spec/compose-spec v0.0.0-20230927132538-f223c5150d5d // indirect
|
||||
github.com/distribution/distribution v2.8.2+incompatible // indirect
|
||||
github.com/docker/buildx v0.11.2 // indirect
|
||||
github.com/docker/cli v24.0.5+incompatible // indirect
|
||||
|
|
|
|||
2
go.sum
2
go.sum
|
|
@ -30,6 +30,8 @@ github.com/compose-spec/compose-spec v0.0.0-20230810081227-631f10f1aabc h1:E93Pp
|
|||
github.com/compose-spec/compose-spec v0.0.0-20230810081227-631f10f1aabc/go.mod h1:SkxF2HOKkzpp+mNdvGONzi3g2shI/M94GkMgsE0JLuk=
|
||||
github.com/compose-spec/compose-spec v0.0.0-20230824062516-848a47ad5d0e h1:qmkQEx3/l6a4ofsiU+b1gDRkANoy55uyc3EXp1n77/Y=
|
||||
github.com/compose-spec/compose-spec v0.0.0-20230824062516-848a47ad5d0e/go.mod h1:SkxF2HOKkzpp+mNdvGONzi3g2shI/M94GkMgsE0JLuk=
|
||||
github.com/compose-spec/compose-spec v0.0.0-20230927132538-f223c5150d5d h1:EHvVBP6ZYAz5KXU5/iA3K6Z7G7haxPm44g/08tueZSw=
|
||||
github.com/compose-spec/compose-spec v0.0.0-20230927132538-f223c5150d5d/go.mod h1:SkxF2HOKkzpp+mNdvGONzi3g2shI/M94GkMgsE0JLuk=
|
||||
github.com/containerd/fuse-overlayfs-snapshotter v1.0.2/go.mod h1:nRZceC8a7dRm3Ao6cJAwuJWPFiBPaibHiFntRUnzhwU=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/distribution/distribution v2.8.2+incompatible h1:k9+4DKdOG+quPFZXT/mUsiQrGu9vYCp+dXpuPkuqhk8=
|
||||
|
|
|
|||
Loading…
Reference in New Issue