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

Update Compose docs to reflect changes in 1.18 release 

Signed-off-by: Joffrey F <joffrey@docker.com>
This commit is contained in:
Joffrey F 2017-12-07 17:19:23 -08:00 committed by Misty Stanley-Jones
parent 0793f49593
commit 6e4339fc4d
6 changed files with 272 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
compose/compose-file/compose-file-v2.md
View File

@ -195,6 +195,19 @@ at build time is the value in the environment where Compose is running.
> **Note**: YAML boolean values (`true`, `false`, `yes`, `no`, `on`, `off`) must
> be enclosed in quotes, so that the parser interprets them as strings.
#### extra_hosts
Add hostname mappings at build-time. Use the same values as the docker client `--add-host` parameter.
extra_hosts:
- "somehost:162.242.195.82"
- "otherhost:50.31.209.229"
An entry with the ip address and hostname will be created in `/etc/hosts` inside containers for this build, e.g:
162.242.195.82 somehost
50.31.209.229 otherhost
#### labels
> Added in [version 2.1](compose-versioning.md#version-21) file format
@ -948,6 +961,7 @@ port (a random host port will be chosen).
- "127.0.0.1:8001:8001"
- "127.0.0.1:5000-5010:5000-5010"
- "6060:6060/udp"
- "12400-12500:1240"
### scale
@ -1038,17 +1052,22 @@ Disables the user namespace for this service, if Docker daemon is configured wit
See [dockerd](/engine/reference/commandline/dockerd.md#disable-user-namespace-for-a-container) for
more information.
### volumes, volume\_driver
### volumes
Mount paths or named volumes, optionally specifying a path on the host machine
(`HOST:CONTAINER`), or an access mode (`HOST:CONTAINER:ro`).
For [version 2 files](compose-versioning.md#version-2), named volumes need to be specified with the
Mount host folders or named volumes. Named volumes need to be specified with the
[top-level `volumes` key](#volume-configuration-reference).
You can mount a relative path on the host, which will expand relative to
the directory of the Compose configuration file being used. Relative paths
should always begin with `.` or `..`.
#### Short syntax
The short syntax uses the generic `[SOURCE:]TARGET[:MODE]` format, where
`SOURCE` can be either a host path or volume name. `TARGET` is the container
path where the volume will be mounted. Standard modes are `ro` for read-only
and `rw` for read-write (default).
volumes:
# Just specify a path and let the Engine create a volume
- /var/lib/mysql
@ -1065,26 +1084,69 @@ should always begin with `.` or `..`.
# Named volume
- datavolume:/var/lib/mysql
If you do not use a host path, you may specify a `volume_driver`.
#### Long syntax
> [Added in version 2.3 file format](compose-versioning.md#version-23).
The long form syntax allows the configuration of additional fields that can't be
expressed in the short form.
- `type`: the mount type `volume`, `bind`, `tmpfs` or `npipe`
- `source`: the source of the mount, a path on the host for a bind mount, or the
name of a volume defined in the
[top-level `volumes` key](#volume-configuration-reference). Not applicable for a tmpfs mount.
- `target`: the path in the container where the volume will be mounted
- `read_only`: flag to set the volume as read-only
- `bind`: configure additional bind options
- `propagation`: the propagation mode used for the bind
- `volume`: configure additional volume options
- `nocopy`: flag to disable copying of data from a container when a volume is
created
```none
version: "3.2"
services:
web:
image: nginx:alpine
ports:
- "80:80"
volumes:
- type: volume
source: mydata
target: /data
volume:
nocopy: true
- type: bind
source: ./static
target: /opt/app/static
networks:
webnet:
volumes:
mydata:
```
> **Note:** When creating bind mounts, using the long syntax requires the
> referenced folder to be created beforehand. Using the short syntax will
> create the folder on the fly if it doesn't exist.
> See the [bind mounts documentation](/engine/admin/volumes/bind-mounts.md/#differences-between--v-and---mount-behavior)
> for more information.
### volume\_driver
Specify a default volume driver to be used for all declared volumes on this
service.
volume_driver: mydriver
There are several things to note, depending on which
[Compose file version](#versioning) you're using:
> **Note:** In [version 2 files](compose-versioning.md#version-2), this
> option will only apply to anonymous volumes (those specified in the image,
> or specified under `volumes` without an explicit named volume or host path).
> To configure the driver for a named volume, use the `driver` key under the
> entry in the [top-level `volumes` option](#volume-configuration-reference).
- You can use `volume_driver` in [version 2 files](compose-versioning.md#version-2),
but it will only apply to anonymous volumes (those specified in the image,
or specified under `volumes` without an explicit named volume or host path).
To configure the driver for a named volume, use the `driver` key under the
entry in the
[top-level `volumes` option](#volume-configuration-reference).
- For [version 1 files](compose-versioning.md#version-1), both named volumes and
container volumes use the specified driver. This changes in version 2 per the above reference to anonymous volumes.
- No path expansion will be done if you have also specified a `volume_driver`.
For example, if you specify a mapping of `./foo:/data`, the `./foo` part
will be passed straight to the volume driver without being expanded.
See [Docker Volumes](/engine/userguide/dockervolumes.md) and
[Volume Plugins](/engine/extend/plugins_volume.md) for more information.
@ -1124,13 +1186,15 @@ then read-write will be used.
{: id="cpu-and-other-resources"}
### cpu_count, cpu_percent, cpu\_shares, cpu\_quota, cpus, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, mem\_reservation, oom_score_adj, privileged, read\_only, shm\_size, stdin\_open, tty, user, working\_dir
### cpu_count, cpu_percent, cpu\_shares, cpu\_quota, cpus, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, mem\_reservation, oom_kill_disable, oom_score_adj, privileged, read\_only, shm\_size, stdin\_open, tty, user, working\_dir
Each of these is a single value, analogous to its
[docker run](/engine/reference/run.md) counterpart.
> **Note:** The following options were added in [version 2.2](compose-versioning.md#version-22):
> `cpu_count`, `cpu_percent`, `cpus`.
> The following options were added in [version 2.1](compose-versioning.md#version-21):
> `oom_kill_disable`
cpu_count: 2
cpu_percent: 50
@ -1153,6 +1217,7 @@ Each of these is a single value, analogous to its
privileged: true
oom_score_adj: 500
oom_kill_disable: true
read_only: true
shm_size: 64M
@ -1449,11 +1514,29 @@ refer to it within the Compose file:
external:
name: actual-name-of-network
#### host or none
Not supposed for version 2 `docker-compose` files. Use
Not supported for version 2 `docker-compose` files. Use
[network_mode](#network_mode) instead.
### name
> [Added in version 2.1 file format](compose-versioning.md#version-21)
Set a custom name for this network.
version: '2.1'
networks:
network1:
name: my-app-net
It can also be used in conjuction with the `external` property:
version: '2.1'
networks:
network1:
external: true
name: my-app-net
## Variable substitution
{% include content/compose-var-sub.md %}

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

@ -314,6 +314,23 @@ those used by other software.
- "com.example.department=Finance"
- "com.example.label-with-empty-value"
#### shm_size
> Added in [version 3.5](compose-versioning.md#version-35) file format
Set the size of the `/dev/shm` partition for this build's containers. Specify
as an integer value representing the number of bytes or as a string expressing
a [byte value](#specifying-byte-values).
build:
context: .
shm_size: '2gb'
build:
context: .
shm_size: 10000000
### cap_add, cap_drop
Add or drop container capabilities.
@ -1785,6 +1802,22 @@ format that looks like this:
The supported units are `us`, `ms`, `s`, `m` and `h`.
## Specifying byte values
Some configuration options, such as the `shm_size` sub-option for
[`build`](#build), accept a byte value as a string in a format
that looks like this:
2b
1024kb
2048k
300m
1gb
The supported units are `b`, `k`, `m` and `g`, and their alternative notation `kb`,
`mb` and `gb`. Please note that decimal values are not supported at this time.
## Volume configuration reference
While it is possible to declare [volumes](#volumes) on the file as part of the
@ -1902,6 +1935,25 @@ conflicting with those used by other software.
- "com.example.department=IT/Ops"
- "com.example.label-with-empty-value"
### name
> [Added in version 3.4 file format](compose-versioning.md#version-34)
Set a custom name for this volume.
version: '3.4'
volumes:
data:
name: my-app-data
It can also be used in conjuction with the `external` property:
version: '3.4'
volumes:
data:
external: true
name: my-app-data
## Network configuration reference
The top-level `networks` key lets you specify networks to be created.
@ -2105,6 +2157,25 @@ refer to it within the Compose file:
external:
name: actual-name-of-network
### name
> [Added in version 3.5 file format](compose-versioning.md#version-35)
Set a custom name for this network.
version: '3.5'
networks:
network1:
name: my-app-net
It can also be used in conjuction with the `external` property:
version: '3.5'
networks:
network1:
external: true
name: my-app-net
## configs configuration reference
The top-level `configs` declaration defines or references
@ -2116,6 +2187,8 @@ stack. The source of the config is either `file` or `external`.
- `external`: If set to true, specifies that this config has already been
created. Docker will not attempt to create it, and if it does not exist, a
`config not found` error occurs.
- `name`: The actual name of the config object in Docker. Introduced with the
3.5 file format.
In this example, `my_first_config` will be created (as
`<stack_name>_my_first_config)`when the stack is deployed,
@ -2159,6 +2232,8 @@ stack. The source of the secret is either `file` or `external`.
- `external`: If set to true, specifies that this secret has already been
created. Docker will not attempt to create it, and if it does not exist, a
`secret not found` error occurs.
- `name`: The actual name of the config object in Docker. Introduced with the
3.5 file format.
In this example, `my_first_secret` will be created (as
`<stack_name>_my_first_secret)`when the stack is deployed,

1
compose/reference/build.md
View File

@ -13,6 +13,7 @@ Options:
--force-rm Always remove intermediate containers.
--no-cache Do not use cache when building the image.
--pull Always attempt to pull a newer version of the image.
-m, --memory MEM Sets memory limit for the bulid container.
--build-arg key=val Set build-time variables for one service.
```

20
compose/reference/down.md
View File

@ -9,15 +9,17 @@ notoc: true
Usage: down [options]
Options:
--rmi type Remove images. Type must be one of:
'all': Remove all images used by any service.
'local': Remove only images that don't have a custom tag
set by the `image` field.
-v, --volumes Remove named volumes declared in the `volumes` section
of the Compose file and anonymous volumes
attached to containers.
--remove-orphans Remove containers for services not defined in the
Compose file
--rmi type Remove images. Type must be one of:
'all': Remove all images used by any service.
'local': Remove only images that don't have a
custom tag set by the `image` field.
-v, --volumes Remove named volumes declared in the `volumes`
section of the Compose file and anonymous volumes
attached to containers.
--remove-orphans Remove containers for services not defined in the
Compose file
-t, --timeout TIMEOUT Specify a shutdown timeout in seconds.
(default: 10)
```
Stops containers and removes containers, networks, volumes, and images

5
compose/reference/run.md
View File

@ -6,7 +6,9 @@ notoc: true
---
```
Usage: run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] SERVICE [COMMAND] [ARGS...]
Usage:
run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...]
SERVICE [COMMAND] [ARGS...]
Options:
-d Detached mode: Run container in the background, print
@ -14,6 +16,7 @@ Options:
--name NAME Assign a name to the container
--entrypoint CMD Override the entrypoint of the image.
-e KEY=VAL Set an environment variable (can be used multiple times)
-l, --label KEY=VAL Add or override a label (can be used multiple times)
-u, --user="" Run as specified username or uid
--no-deps Don't start linked services.
--rm Remove container after run. Ignored in detached mode.

75
release-notes/docker-compose.md
View File

@ -5,6 +5,81 @@ keywords: release notes, compose
toc_max: 2
---
## 1.18.0 (2017-12-15)
### New features
#### Compose file version 3.5
- Introduced version 3.5 of the `docker-compose.yml` specification.
This version requires to be used with Docker Engine 17.06.0 or above
- Added support for the `shm_size` parameter in build configurations
- Added support for the `isolation` parameter in service definitions
- Added support for custom names for network, secret and config definitions
#### Compose file version 2.3
- Added support for `extra_hosts` in build configuration
- Added support for the [long syntax](/compose/compose-file.md#long-syntax-3) for volume entries, as previously
introduced in the 3.2 format. Note that using this syntax will create
[mounts](/engine/admin/volumes/bind-mounts.md) instead of volumes.
#### Compose file version 2.1 and up
- Added support for the `oom_kill_disable` parameter in service definitions
(2.x only)
- Added support for custom names for network definitions (2.x only)
#### All formats
- Values interpolated from the environment will now be converted to the
proper type when used in non-string fields.
- Added support for `--label` in `docker-compose run`
- Added support for `--timeout` in `docker-compose down`
- Added support for `--memory` in `docker-compose build`
- Setting `stop_grace_period` in service definitions now also sets the
container's `stop_timeout`
### Bugfixes
- Fixed an issue where Compose was still handling service hostname according
to legacy engine behavior, causing hostnames containing dots to be cut up
- Fixed a bug where the `X-Y:Z` syntax for ports was considered invalid
by Compose
- Fixed an issue with CLI logging causing duplicate messages and inelegant
output to occur
- Fixed a bug where the valid `${VAR:-}` syntax would cause Compose to
error out
- Fixed a bug where `env_file` entries using an UTF-8 BOM were being read
incorrectly
- Fixed a bug where missing secret files would generate an empty directory
in their place
- Added validation for the `test` field in healthchecks
- Added validation for the `subnet` field in IPAM configurations
- Added validation for `volumes` properties when using the long syntax in
service definitions
- The CLI now explicit prevents using `-d` and `--timeout` together
in `docker-compose up`
## 1.17.0 (2017-11-03)
### New features