diff --git a/_config.yml b/_config.yml index c71cd7e1387..0026f154551 100644 --- a/_config.yml +++ b/_config.yml @@ -20,7 +20,7 @@ docker_ce_stable_version: "17.09" latest_stable_docker_engine_api_version: "1.32" docker_ce_edge_version: "17.09" docker_ee_version: "17.06" -compose_version: "1.16.1" +compose_version: "1.17.0" machine_version: "0.12.2" distribution_version: "2.6" diff --git a/_includes/content/compose-extfields-sub.md b/_includes/content/compose-extfields-sub.md new file mode 100644 index 00000000000..1ae9d17f8bb --- /dev/null +++ b/_includes/content/compose-extfields-sub.md @@ -0,0 +1,63 @@ +It is possible to re-use configuration fragments using extension fields. Those +special fields can be of any format as long as they are located at the root of +your Compose file and their name start with the `x-` character sequence. + + version: '2.1' + x-custom: + items: + - a + - b + options: + max-size: '12m' + name: "custom" + +The contents of those fields will be ignored by Compose, but they can be +inserted in your resource definitions using [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2765878). +For example, if you want several of your services to use the same logging +configuration: + + logging: + options: + max-size: '12m' + max-file: 5 + driver: json-file + +You may write your Compose file as follows: + +version: '2.1' +x-logging: + &default-logging + options: + max-size: '12m' + max-file: 5 + driver: json-file + +services: + web: + image: myapp/web:latest + logging: *default-logging + db: + image: mysql:latest + logging: *default-logging + +It is also possible to partially override values in extension fields using +the [YAML merge type](http://yaml.org/type/merge.html). For example: + + version: '2.1' + x-volumes: + &default-volume + driver: foobar-storage + + services: + web: + image: myapp/web:latest + volumes: ["vol1", "vol2", "vol3"] + volumes: + vol1: *default-volume + vol2: + << : *default-volume + name: volume02 + vol3: + << : *default-volume + driver: default + name: volume-local diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index 0c7f1de012c..1ba1b1a208f 100644 --- a/compose/compose-file/compose-file-v2.md +++ b/compose/compose-file/compose-file-v2.md @@ -236,6 +236,23 @@ build. context: . network: custom_network_1 +#### shm_size + +> Added in [version 2.3](compose-versioning.md#version-23) 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 + #### target > Added in [version 2.3](compose-versioning.md#version-23) file format @@ -1422,6 +1439,12 @@ refer to it within the Compose file: {% include content/compose-var-sub.md %} +## Extension fields + +> [Added in version 2.1 file format](compose-versioning.md#version-21). + +{% include content/compose-extfields-sub.md %} + ## Compose documentation - [User guide](/compose/index.md) diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md index f0ca5303224..3f214414db5 100644 --- a/compose/compose-file/compose-versioning.md +++ b/compose/compose-file/compose-versioning.md @@ -223,7 +223,8 @@ supported by **Compose 1.16.0+**. Introduces the following additional parameters: -- [`target`](compose-file-v2.md#target) for [build configurations](compose-file-v2.md#build) +- [`target`](compose-file-v2.md#target) and [`shm_size`](compose-file-v2.md#shm_size) + for [build configurations](compose-file-v2.md#build) - `start_period` for [`healthchecks`](compose-file-v2.md#healthcheck) ### Version 3 @@ -251,6 +252,18 @@ Introduces the following additional parameters: - [`configs`](/compose/compose-file/index.md#configs) - [deploy `endpoint_mode`](/compose/compose-file/index.md#endpointmode) +### Version 3.4 + +An upgrade of [version 3](#version-3) that introduces new parameters. It is +only available with Docker Engine version **17.09.0** and higher. + +Introduces the following additional parameters: + +- `target` and `network` in [build configurations](index.md#build) +- `start_period` for [`healthchecks`](index.md#healthcheck) +- `order` for [update configurations](index.md#update_config) +- `name` for [volumes](index.md#volume-configuration-reference) + ## Upgrading ### Version 2.x to 3.x diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index f5168df2914..b862a4f6215 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -2150,6 +2150,12 @@ stack. {% include content/compose-var-sub.md %} +## Extension fields + +> [Added in version 3.4 file format](compose-versioning.md#version-34). + +{% include content/compose-extfields-sub.md %} + ## Compose documentation - [User guide](/compose/index.md) diff --git a/compose/reference/create.md b/compose/reference/create.md index b45f165a701..ceb2ef58a8e 100644 --- a/compose/reference/create.md +++ b/compose/reference/create.md @@ -7,6 +7,7 @@ notoc: true ``` Creates containers for a service. +This command is deprecated. Use the `up` command with `--no-start` instead. Usage: create [options] [SERVICE...] diff --git a/compose/reference/up.md b/compose/reference/up.md index c2304998fcc..ef26eec7a25 100644 --- a/compose/reference/up.md +++ b/compose/reference/up.md @@ -20,14 +20,15 @@ Options: --no-recreate If containers already exist, don't recreate them. Incompatible with --force-recreate. --no-build Don't build an image, even if it's missing. + --no-start Don't start the services after creating them. --build Build images before starting containers. --abort-on-container-exit Stops all containers if any container was stopped. Incompatible with -d. -t, --timeout TIMEOUT Use this timeout in seconds for container shutdown when attached or when containers are already running. (default: 10) - --remove-orphans Remove containers for services not defined in - the Compose file + --remove-orphans Remove containers for services not + defined in the Compose file --exit-code-from SERVICE Return the exit code of the selected service container. Implies --abort-on-container-exit. --scale SERVICE=NUM Scale SERVICE to NUM instances. Overrides the `scale` diff --git a/release-notes/docker-compose.md b/release-notes/docker-compose.md index 6056a0bd81a..ae00a3efc99 100644 --- a/release-notes/docker-compose.md +++ b/release-notes/docker-compose.md @@ -5,6 +5,63 @@ keywords: release notes, compose toc_max: 2 --- +## 1.17.0 (2017-11-03) + +### New features + +#### Compose file version 3.4 + +- Introduced version 3.4 of the `docker-compose.yml` specification. + This version requires to be used with Docker Engine 17.06.0 or above. + +- Added support for `cache_from`, `network` and `target` options in build + configurations + +- Added support for the `order` parameter in the `update_config` section + +- Added support for setting a custom name in volume definitions using + the `name` parameter + +#### Compose file version 2.3 + +- Added support for `shm_size` option in build configuration + +#### Compose file version 2.x + +- Added support for extension fields (`x-*`). Also available for v3.4 files + +#### All formats + +- Added new `--no-start` to the `up` command, allowing users to create all + resources (networks, volumes, containers) without starting services. + The `create` command is deprecated in favor of this new option + +### Bugfixes + +- Fixed a bug where `extra_hosts` values would be overridden by extension + files instead of merging together + +- Fixed a bug where the validation for v3.2 files would prevent using the + `consistency` field in service volume definitions + +- Fixed a bug that would cause a crash when configuration fields expecting + unique items would contain duplicates + +- Fixed a bug where mount overrides with a different mode would create a + duplicate entry instead of overriding the original entry + +- Fixed a bug where build labels declared as a list wouldn't be properly + parsed + +- Fixed a bug where the output of `docker-compose config` would be invalid + for some versions if the file contained custom-named external volumes + +- Improved error handling when issuing a build command on Windows using an + unsupported file version + +- Fixed an issue where networks with identical names would sometimes be + created when running `up` commands concurrently. + ## 1.16.0 (2017-08-31) ### New features