Add Compose file reference (legacy)/

Author: socheatsok78

Compose file reference (legacy)/compose-versioning.md

@@ -0,0 +1,474 @@
+There are three legacy versions of the Compose file format:
+
+- Version 1. This is specified by omitting a `version` key at the root of the YAML.
+
+- Version 2.x. This is specified with a `version: '2'` or `version: '2.1'`, etc., entry at the root of the YAML.
+
+- Version 3.x, designed to be cross-compatible between Compose and the Docker Engine's
+[swarm mode](https://docs.docker.com/engine/swarm/). This is specified with a `version: '3'` or `version: '3.1'`, etc., entry at the root of the YAML.
+
+The latest and recommended version of the Compose file format is defined by the [Compose Specification](https://docs.docker.com/compose/compose-file/). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**.
+
+
+> **Note** 
+>
+> If you're using [multiple Compose files](https://docs.docker.com/compose/multiple-compose-files/) or
+> [extending services](https://docs.docker.com/compose/multiple-compose-files/extends/),
+> each file must be of the same version - you cannot, for example,
+> mix version 1 and 2 in a single project.
+
+Several things differ depending on which version you use:
+
+- The structure and permitted configuration keys
+- The minimum Docker Engine version you must be running
+- Compose's behaviour with regards to networking
+
+These differences are explained below.
+
+### Version 2
+
+Compose files using the version 2 syntax must indicate the version number at
+the root of the document. All [services](compose-file-v2.md#service-configuration-reference)
+must be declared under the `services` key.
+
+Version 2 files are supported by **Compose 1.6.0+** and require a Docker Engine
+of version **1.10.0+**.
+
+Named [volumes](compose-file-v2.md#volume-configuration-reference) can be declared under the
+`volumes` key, and [networks](compose-file-v2.md#network-configuration-reference) can be declared
+under the `networks` key.
+
+By default, every container joins an application-wide default network, and is
+discoverable at a hostname that's the same as the service name. This means
+[links](compose-file-v2.md#links) are largely unnecessary. For more details, see
+[Networking in Compose](https://docs.docker.com/compose/networking/).
+
+> **Note**
+>
+> With Compose version 2, when specifying the Compose file version to use, make sure to
+> specify both the _major_ and _minor_ numbers. If no minor version is given,
+> `0` is used by default and not the latest minor version. As a result, features added in later versions will not be supported. For example:
+>
+> ```yaml
+> version: "2"
+> ```
+>
+> is equivalent to:
+>
+> ```yaml
+> version: "2.0"
+> ```
+
+Simple example:
+
+    version: "{{% param "compose_file_v2" %}}"
+    services:
+      web:
+        build: .
+        ports:
+         - "8000:5000"
+        volumes:
+         - .:/code
+      redis:
+        image: redis
+
+A more extended example, defining volumes and networks:
+
+    version: "{{% param "compose_file_v2" %}}"
+    services:
+      web:
+        build: .
+        ports:
+         - "8000:5000"
+        volumes:
+         - .:/code
+        networks:
+          - front-tier
+          - back-tier
+      redis:
+        image: redis
+        volumes:
+          - redis-data:/var/lib/redis
+        networks:
+          - back-tier
+    volumes:
+      redis-data:
+        driver: local
+    networks:
+      front-tier:
+        driver: bridge
+      back-tier:
+        driver: bridge
+
+Several other options were added to support networking, such as:
+
+* [`aliases`](compose-file-v2.md#aliases)
+
+* The [`depends_on`](compose-file-v2.md#depends_on) option can be used in place of links to indicate dependencies
+between services and startup order.
+
+      version: "{{% param "compose_file_v2" %}}"
+      services:
+        web:
+          build: .
+          depends_on:
+            - db
+            - redis
+        redis:
+          image: redis
+        db:
+          image: postgres
+
+* [`ipv4_address`, `ipv6_address`](compose-file-v2.md#ipv4_address-ipv6_address)
+
+[Variable substitution](compose-file-v2.md#variable-substitution) also was added in Version 2.
+
+### Version 2.1
+
+An upgrade of [version 2](#version-2) that introduces new parameters only
+available with Docker Engine version **1.12.0+**. Version 2.1 files are
+supported by **Compose 1.9.0+**.
+
+Introduces the following additional parameters:
+
+- [`link_local_ips`](compose-file-v2.md#link_local_ips)
+- [`isolation`](compose-file-v2.md#isolation-1) in build configurations and
+  service definitions
+- `labels` for [volumes](compose-file-v2.md#volume-configuration-reference),
+  [networks](compose-file-v2.md#network-configuration-reference), and
+  [build](compose-file-v3.md#build)
+- `name` for [volumes](compose-file-v2.md#volume-configuration-reference)
+- [`userns_mode`](compose-file-v2.md#userns_mode)
+- [`healthcheck`](compose-file-v2.md#healthcheck)
+- [`sysctls`](compose-file-v2.md#sysctls)
+- [`pids_limit`](compose-file-v2.md#pids_limit)
+- [`oom_kill_disable`](compose-file-v2.md#cpu-and-other-resources)
+- [`cpu_period`](compose-file-v2.md#cpu-and-other-resources)
+
+### Version 2.2
+
+An upgrade of [version 2.1](#version-21) that introduces new parameters only
+available with Docker Engine version **1.13.0+**.  Version 2.2 files are
+supported by **Compose 1.13.0+**. This version also allows you to specify
+default scale numbers inside the service's configuration.
+
+Introduces the following additional parameters:
+
+- [`init`](compose-file-v2.md#init)
+- [`scale`](compose-file-v2.md#scale)
+- [`cpu_rt_runtime` and `cpu_rt_period`](compose-file-v2.md#cpu_rt_runtime-cpu_rt_period)
+- [`network`](compose-file-v2.md#network) for [build configurations](compose-file-v2.md#build)
+
+### Version 2.3
+
+An upgrade of [version 2.2](#version-22) that introduces new parameters only
+available with Docker Engine version **17.06.0+**. Version 2.3 files are
+supported by **Compose 1.16.0+**.
+
+Introduces the following additional parameters:
+
+- [`target`](compose-file-v2.md#target), [`extra_hosts`](compose-file-v2.md#extra_hosts-1) 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)
+- ["Long syntax" for volumes](compose-file-v2.md#long-syntax)
+- [`runtime`](compose-file-v2.md#runtime) for service definitions
+- [`device_cgroup_rules`](compose-file-v2.md#device_cgroup_rules)
+
+### Version 2.4
+
+An upgrade of [version 2.3](#version-23) that introduces new parameters only
+available with Docker Engine version **17.12.0+**. Version 2.4 files are
+supported by **Compose 1.21.0+**.
+
+Introduces the following additional parameters:
+
+- [`platform`](compose-file-v2.md#platform) for service definitions
+- Support for extension fields at the root of service, network, and volume
+  definitions
+
+### Version 3
+
+Designed to be cross-compatible between Compose and the Docker Engine's
+[swarm mode](/engine/swarm/), version 3 removes several options and adds
+several more.
+
+- Removed: `volume_driver`, `volumes_from`, `cpu_shares`, `cpu_quota`,
+  `cpuset`, `mem_limit`, `memswap_limit`, `extends`, `group_add`. See
+  the [upgrading](#upgrading) guide for how to migrate away from these.
+
+- Added: [deploy](compose-file-v3.md#deploy)
+
+If only the major version is given (`version: '3'`),
+the latest minor version is used by default.
+
+### Version 3.1
+
+An upgrade of [version 3](#version-3) that introduces new parameters only
+available with Docker Engine version **1.13.1+**, and higher.
+
+Introduces the following additional parameters:
+
+- [`secrets`](compose-file-v3.md#secrets)
+
+### Version 3.2
+
+An upgrade of [version 3](#version-3) that introduces new parameters only
+available with Docker Engine version **17.04.0+**, and higher.
+
+Introduces the following additional parameters:
+
+- [`cache_from`](compose-file-v3.md#cache_from) in [build configurations](compose-file-v3.md#build)
+- Long syntax for [ports](compose-file-v3.md#ports) and [volume mounts](compose-file-v3.md#volumes)
+- [`attachable`](compose-file-v3.md#attachable) network driver option
+- [deploy `endpoint_mode`](compose-file-v3.md#endpoint_mode)
+- [deploy placement `preference`](compose-file-v3.md#placement)
+
+### Version 3.3
+
+An upgrade of [version 3](#version-3) that introduces new parameters only
+available with Docker Engine version **17.06.0+**, and higher.
+
+Introduces the following additional parameters:
+
+- [build `labels`](compose-file-v3.md#build)
+- [`credential_spec`](compose-file-v3.md#credential_spec)
+- [`configs`](compose-file-v3.md#configs)
+
+### 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`](compose-file-v3.md#target) and [`network`](compose-file-v3.md#network) in
+  [build configurations](compose-file-v3.md#build)
+- `start_period` for [`healthchecks`](compose-file-v3.md#healthcheck)
+- `order` for [update configurations](compose-file-v3.md#update_config)
+- `name` for [volumes](compose-file-v3.md#volume-configuration-reference)
+
+### Version 3.5
+
+An upgrade of [version 3](#version-3) that introduces new parameters. It is
+only available with Docker Engine version **17.12.0** and higher.
+
+Introduces the following additional parameters:
+
+- [`isolation`](compose-file-v3.md#isolation) in service definitions
+- `name` for networks, secrets and configs
+- `shm_size` in [build configurations](compose-file-v3.md#build)
+
+### Version 3.6
+
+An upgrade of [version 3](#version-3) that introduces new parameters. It is
+only available with Docker Engine version **18.02.0** and higher.
+
+Introduces the following additional parameters:
+
+- [`tmpfs` size](compose-file-v3.md#long-syntax-3) for `tmpfs`-type mounts
+
+### Version 3.7
+
+An upgrade of [version 3](#version-3) that introduces new parameters. It is
+only available with Docker Engine version **18.06.0** and higher.
+
+Introduces the following additional parameters:
+
+- [`init`](compose-file-v3.md#init) in service definitions
+- [`rollback_config`](compose-file-v3.md#rollback_config) in deploy configurations
+- Support for extension fields at the root of service, network, volume, secret
+  and config definitions
+
+### Version 3.8
+
+An upgrade of [version 3](#version-3) that introduces new parameters. It is
+only available with Docker Engine version **19.03.0** and higher.
+
+Introduces the following additional parameters:
+
+- [`max_replicas_per_node`](compose-file-v3.md#max_replicas_per_node) in placement
+  configurations
+- `template_driver` option for [config](compose-file-v3.md#configs-configuration-reference)
+   and [secret](compose-file-v3.md#secrets-configuration-reference) configurations. This
+   option is only supported when deploying swarm services using
+   `docker stack deploy`.
+- `driver` and `driver_opts` option for [secret](compose-file-v3.md#secrets-configuration-reference)
+   configurations. This option is only supported when deploying swarm services
+   using `docker stack deploy`.
+
+### Version 1 (Deprecated)
+
+Compose versions below 1.6.x are 
+
+Compose files that do not declare a version are considered "version 1".  In those
+files, all the [services](compose-file-v3.md#service-configuration-reference) are
+declared at the root of the document.
+
+Version 1 is supported by Compose up to 1.6.x** and has been deprecated.
+
+Version 1 files cannot declare named
+[volumes](compose-file-v3.md#volume-configuration-reference), [networks](compose-file-v3.md#network-configuration-reference) or
+[build arguments](compose-file-v3.md#args).
+
+Compose does not take advantage of [networking](https://docs.docker.com/compose/networking/) when you
+use version 1: every container is placed on the default `bridge` network and is
+reachable from every other container at its IP address. You need to use
+`links` to enable discovery between containers.
+
+Example:
+
+    web:
+      build: .
+      ports:
+       - "8000:5000"
+      volumes:
+       - .:/code
+      links:
+       - redis
+    redis:
+      image: redis
+
+## Upgrading
+
+### Version 2.x to 3.x
+
+Between versions 2.x and 3.x, the structure of the Compose file is the same, but
+several options have been removed:
+
+-   `volume_driver`: Instead of setting the volume driver on the service, define
+    a volume using the
+    [top-level `volumes` option](compose-file-v3.md#volume-configuration-reference)
+    and specify the driver there.
+
+        version: "3.8"
+        services:
+          db:
+            image: postgres
+            volumes:
+              - data:/var/lib/postgresql/data
+        volumes:
+          data:
+            driver: mydriver
+
+-   `volumes_from`: To share a volume between services, define it using the
+    [top-level `volumes` option](compose-file-v3.md#volume-configuration-reference)
+    and reference it from each service that shares it using the
+    [service-level `volumes` option](compose-file-v3.md#driver).
+
+-   `cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`: These
+    have been replaced by the [resources](compose-file-v3.md#resources) key under
+    `deploy`. `deploy` configuration only takes effect when using
+    `docker stack deploy`, and is ignored by `docker-compose`.
+
+-   `extends`: This option has been removed for `version: "3.x"` Compose files.
+    For more information on `extends`, see
+    [Extending services](https://docs.docker.com/compose/multiple-compose-files/extends/).
+-   `group_add`: This option has been removed for `version: "3.x"` Compose files.
+-   `pids_limit`: This option has not been introduced in `version: "3.x"` Compose files.
+-   `link_local_ips` in `networks`: This option has not been introduced in
+    `version: "3.x"` Compose files.
+
+#### Compatibility mode
+
+`docker-compose` 1.20.0 introduces a new `--compatibility` flag designed to
+help developers transition to version 3 more easily. When enabled,
+`docker-compose` reads the `deploy` section of each service's definition and
+attempts to translate it into the equivalent version 2 parameter. Currently,
+the following deploy keys are translated:
+
+- [resources](compose-file-v3.md#resources) limits and memory reservations
+- [replicas](compose-file-v3.md#replicas)
+- [restart_policy](compose-file-v3.md#restart_policy) `condition` and `max_attempts`
+
+All other keys are ignored and produce a warning if present. You can review
+the configuration that will be used to deploy by using the `--compatibility`
+flag with the `config` command.
+
+> Do not use this in production
+>
+> We recommend against using `--compatibility` mode in production. The
+> resulting configuration is only an approximate using non-Swarm mode
+> properties, it may produce unexpected results.
+
+### Version 1 to 2.x
+
+In the majority of cases, moving from version 1 to 2 is a very simple process:
+
+1. Indent the whole file by one level and put a `services:` key at the top.
+2. Add a `version: '2'` line at the top of the file.
+
+It's more complicated if you're using particular configuration features:
+
+-   `dockerfile`: This now lives under the `build` key:
+
+        build:
+          context: .
+          dockerfile: Dockerfile-alternate
+
+-   `log_driver`, `log_opt`: These now live under the `logging` key:
+
+        logging:
+          driver: syslog
+          options:
+            syslog-address: "tcp://192.168.0.42:123"
+
+-   `links` with environment variables: environment variables created by
+    links, such as `CONTAINERNAME_PORT`, ` have been deprecated for some time. In the new Docker network system,
+    they have been removed. You should either connect directly to the
+    appropriate hostname or set the relevant environment variable yourself,
+    using the link hostname:
+
+        web:
+          links:
+            - db
+          environment:
+            - DB_PORT=tcp://db:5432
+
+-   `external_links`: Compose uses Docker networks when running version 2
+    projects, so links behave slightly differently. In particular, two
+    containers must be connected to at least one network in common in order to
+    communicate, even if explicitly linked together.
+
+    Either connect the external container to your app's
+    [default network](https://docs.docker.com/compose/networking/), or connect both the external container and
+    your service's containers to an
+    [external network](https://docs.docker.com/compose/networking/).
+
+-   `net`: This is now replaced by [network_mode](compose-file-v3.md#network_mode):
+
+        net: host    ->  network_mode: host
+        net: bridge  ->  network_mode: bridge
+        net: none    ->  network_mode: none
+
+    If you're using `net: "container:[service name]"`, you must now use
+    `network_mode: "service:[service name]"` instead.
+
+        net: "container:web"  ->  network_mode: "service:web"
+
+    If you're using `net: "container:[container name/id]"`, the value does not
+    need to change.
+
+        net: "container:cont-name"  ->  network_mode: "container:cont-name"
+        net: "container:abc12345"   ->  network_mode: "container:abc12345"
+
+-   `volumes` with named volumes: these must now be explicitly declared in a
+    top-level `volumes` section of your Compose file. If a service mounts a
+    named volume called `data`, you must declare a `data` volume in your
+    top-level `volumes` section. The whole file might look like this:
+
+        version: "{{% param "compose_file_v2" %}}"
+        services:
+          db:
+            image: postgres
+            volumes:
+              - data:/var/lib/postgresql/data
+        volumes:
+          data: {}
+
+    By default, Compose creates a volume whose name is prefixed with your
+    project name. If you want it to just be called `data`, declare it as
+    external:
+
+        volumes:
+          data:
+            external: true