From b139eb505595295a2a54015c9239d1c057bddc23 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Tue, 7 Sep 2021 14:06:53 +0200 Subject: [PATCH 1/8] compose V2 G.A Signed-off-by: Nicolas De Loof --- _config.yml | 2 +- _data/toc.yaml | 2 +- _includes/content/compose-extfields-sub.md | 3 - compose/cli-command.md | 56 +-------- compose/environment-variables.md | 29 ++--- compose/extends.md | 10 +- compose/faq.md | 8 +- compose/gettingstarted.md | 30 +++-- compose/gpu-support.md | 8 +- compose/index.md | 26 +++-- compose/install.md | 128 +++------------------ compose/networking.md | 10 +- compose/production.md | 8 +- compose/profiles.md | 29 +++-- compose/release-notes.md | 4 + 15 files changed, 102 insertions(+), 251 deletions(-) diff --git a/_config.yml b/_config.yml index 475084a166b..f9e8ac4fd7f 100644 --- a/_config.yml +++ b/_config.yml @@ -22,7 +22,7 @@ exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html", # You can't have - characters in these for non-YAML reasons latest_engine_api_version: "1.41" docker_ce_version: "20.10" -compose_version: "1.29.2" +compose_version: "2.0.0" compose_file_v3: "3.9" compose_file_v2: "2.4" machine_version: "0.16.0" diff --git a/_data/toc.yaml b/_data/toc.yaml index a8215fa5057..89c29305c1f 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1316,7 +1316,7 @@ manuals: - path: /compose/cli-command/ title: Overview - path: /compose/cli-command-compatibility/ - title: Compose v2 compatibility + title: Compatibility - path: /compose/install/ title: Install Compose - path: /compose/gettingstarted/ diff --git a/_includes/content/compose-extfields-sub.md b/_includes/content/compose-extfields-sub.md index c7adc8b2768..fd0a63a98ae 100644 --- a/_includes/content/compose-extfields-sub.md +++ b/_includes/content/compose-extfields-sub.md @@ -9,7 +9,6 @@ your Compose file and their name start with the `x-` character sequence. > of service, volume, network, config and secret definitions. ```yaml -version: "{{ site.compose_file_v3 }}" x-custom: items: - a @@ -35,7 +34,6 @@ logging: You may write your Compose file as follows: ```yaml -version: "{{ site.compose_file_v3 }}" x-logging: &default-logging options: @@ -56,7 +54,6 @@ It is also possible to partially override values in extension fields using the [YAML merge type](https://yaml.org/type/merge.html). For example: ```yaml -version: "{{ site.compose_file_v3 }}" x-volumes: &default-volume driver: foobar-storage diff --git a/compose/cli-command.md b/compose/cli-command.md index 4df09a259e0..53d323c9fb0 100644 --- a/compose/cli-command.md +++ b/compose/cli-command.md @@ -1,23 +1,14 @@ --- -description: Compose V2 RC1 in the Docker CLI -keywords: compose, V2, release candidate RC 1 -title: Compose V2 release candidate +description: Compose V2 +keywords: compose, V2 +title: Compose V2 --- ## Compose V2 and the new `docker compose` command -> Important -> -> The new Compose V2, which supports the `compose` command as part of the Docker CLI, is available as a release candidate with the Docker Desktop 3.6 release. -> -> Compose V2 integrates compose functions into the Docker platform, continuing to support most of the previous `docker-compose` features and flags. You can test the Compose V2 by simply replacing the dash (`-`) with a space, and by running `docker compose`, instead of `docker-compose`. -> -> As Docker Compose V2 is a release candidate, we recommend that you extensively test before using it in production environments. -{: .important} - Starting with Docker Desktop 3.4.0, you can run Compose V2 commands without modifying your invocations, by enabling the drop-in replacement of the previous `docker-compose` with the new command. See the section [Installing Compose v2](#installing-compose-v2) for detailed instructions how to enable the drop-in replacement. -We will gradually turn this option on automatically for Docker Desktop users, so that users can seamlessly move to Docker Compose V2 without the need to upgrade any of their scripts. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. +We turn this option on automatically for Docker Desktop users, so that users can seamlessly move to Docker Compose V2 without the need to upgrade any of their scripts. If you run into any problems with Compose V2, you can easily switch back to Compose V1 by either by making changes in Docker Desktop Settings, or by running the command `docker-compose disable-v2`. Your feedback is important to us. Let us know your feedback on the new 'compose' command by creating an issue in the [Compose](https://github.com/docker/compose/issues){:target="_blank" rel="noopener" class="_"} GitHub repository. {: .important} @@ -31,42 +22,3 @@ While docker-compose is still supported and maintained, Compose V2 implementatio Additionally, Compose V2 also supports [Apple silicon](../desktop/mac/apple-silicon.md). For more information about the flags that are supported in the new compose command, see the [docker-compose compatibility list](cli-command-compatibility.md). - -## Installing Compose V2 - -This section contains instructions on how to install Compose V2. - -### Install on Mac and Windows - -**Docker Desktop for Mac and for Windows version 3.2.1** and above includes the new Compose command along with the Docker CLI. Therefore, Windows and Mac users do not need to install the Compose V2 separately. - -**Docker Desktop for Mac and for Windows version 3.4.0** and above also includes `docker-compose` drop-in replacement, allowing users to choose to use Compose V2 when using the `docker-compose` command. - -We will progressively turn Docker Compose V2 on automatically for Docker Desktop users, so that users can seamlessly move to Docker Compose V2 without the need to change any of their scripts. If you run into any problems with Compose V2, you can simply switch back to Compose v1, either in Docker Desktop, or in the CLI. - -For Docker Desktop installation instructions, see: - -- [Install Docker Desktop on Mac](../desktop/mac/install.md) -- [Install Docker Desktop on Windows](../desktop/windows/install.md) - -To disable Docker Compose V2 using Docker Desktop: - -1. From the Docker menu, click **Preferences** (**Settings** on Windows) > **Experimental features**. -2. Clear the **Use Docker Compose V2** check box. - -To disable Docker Compose V2 using the CLI, run: - -```console -$ docker-compose disable-v2 -``` - -### Install on Linux - -You can install Compose V2 by downloading the adequate binary for your system -from the [project release page](https://github.com/docker/compose/releases){:target="_blank" rel="noopener" class="_"} and copying it into `$HOME/.docker/cli-plugins` as `docker-compose`. - -```console -$ mkdir -p ~/.docker/cli-plugins/ -$ curl -SL https://github.com/docker/compose/releases/download/v2.0.0-rc.3/docker-compose-linux-amd64 -o ~/.docker/cli-plugins/docker-compose -$ chmod +x ~/.docker/cli-plugins/docker-compose -``` diff --git a/compose/environment-variables.md b/compose/environment-variables.md index 698c127bc65..4f553e59cae 100644 --- a/compose/environment-variables.md +++ b/compose/environment-variables.md @@ -48,19 +48,18 @@ $ cat .env TAG=v1.5 $ cat docker-compose.yml -version: '3' services: web: image: "webapp:${TAG}" ``` -When you run `docker-compose up`, the `web` service defined above uses the +When you run `docker compose up`, the `web` service defined above uses the image `webapp:v1.5`. You can verify this with the [config command](reference/config.md), which prints your resolved application config to the terminal: ```console -$ docker-compose config +$ docker compose config version: '3' services: @@ -75,7 +74,7 @@ uses that instead: ```console $ export TAG=v2.0 -$ docker-compose config +$ docker compose config version: '3' services: @@ -92,7 +91,7 @@ appropriately, for example, `.env.ci`, `.env.dev`, `.env.prod`. Passing the file done using the `--env-file` option: ```console -$ docker-compose --env-file ./config/.env.dev up +$ docker compose --env-file ./config/.env.dev up ``` This file path is relative to the current working directory where the Docker Compose @@ -107,7 +106,6 @@ TAG=v1.6 $ cat docker-compose.yml -version: '3' services: web: image: "webapp:${TAG}" @@ -116,8 +114,7 @@ services: The `.env` file is loaded by default: ```console -$ docker-compose config -version: '3' +$ docker compose config services: web: image: 'webapp:v1.5' @@ -126,8 +123,7 @@ services: Passing the `--env-file ` argument overrides the default file path: ```console -$ docker-compose --env-file ./config/.env.dev config -version: '3' +$ docker compose --env-file ./config/.env.dev config services: web: image: 'webapp:v1.6' @@ -136,7 +132,7 @@ services: When an invalid file path is being passed as `--env-file` argument, Compose returns an error: ```console -$ docker-compose --env-file ./doesnotexist/.env.dev config +$ docker compose --env-file ./doesnotexist/.env.dev config ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev ``` @@ -184,19 +180,19 @@ web: - web-variables.env ``` -## Set environment variables with 'docker-compose run' +## Set environment variables with 'docker compose run' Similar to `docker run -e`, you can set environment variables on a one-off -container with `docker-compose run -e`: +container with `docker compose run -e`: ```console -$ docker-compose run -e DEBUG=1 web python console.py +$ docker compose run -e DEBUG=1 web python console.py ``` You can also pass a variable from the shell by not giving it a value: ```console -$ docker-compose run -e DEBUG web python console.py +$ docker compose run -e DEBUG web python console.py ``` The value of the `DEBUG` variable in the container is taken from the value for @@ -219,7 +215,6 @@ $ cat ./Docker/api/api.env NODE_ENV=test $ cat docker-compose.yml -version: '3' services: api: image: 'node:6-alpine' @@ -233,7 +228,7 @@ When you run the container, the environment variable defined in the Compose file takes precedence. ```console -$ docker-compose exec api node +$ docker compose exec api node > process.env.NODE_ENV 'production' diff --git a/compose/extends.md b/compose/extends.md index 2e5677dc6a5..cd5362c747a 100644 --- a/compose/extends.md +++ b/compose/extends.md @@ -31,7 +31,7 @@ the rules described in To use multiple override files, or an override file with a different name, you can use the `-f` option to specify the list of files. Compose merges files in the order they're specified on the command line. See the -[`docker-compose` command reference](reference/index.md) for more information +[`docker compose` command reference](reference/index.md) for more information about using `-f`. When you use multiple configuration files, you must make sure all paths in the @@ -99,7 +99,7 @@ cache: - 6379:6379 ``` -When you run `docker-compose up` it reads the overrides automatically. +When you run `docker compose up` it reads the overrides automatically. Now, it would be nice to use this Compose app in a production environment. So, create another override file (which might be stored in a different git @@ -122,7 +122,7 @@ cache: To deploy with this production Compose file you can run ```console -$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d +$ docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d ``` This deploys all three services using the configuration in @@ -161,11 +161,11 @@ export or backup. - db ``` -To start a normal environment run `docker-compose up -d`. To run a database +To start a normal environment run `docker compose up -d`. To run a database backup, include the `docker-compose.admin.yml` as well. ```console -$ docker-compose -f docker-compose.yml -f docker-compose.admin.yml \ +$ docker compose -f docker-compose.yml -f docker-compose.admin.yml \ run dbadmin db-backup ``` diff --git a/compose/faq.md b/compose/faq.md index 899a2203274..a032a9f532e 100644 --- a/compose/faq.md +++ b/compose/faq.md @@ -63,13 +63,13 @@ or the [`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compos ## What's the difference between `up`, `run`, and `start`? -Typically, you want `docker-compose up`. Use `up` to start or restart all the +Typically, you want `docker compose up`. Use `up` to start or restart all the services defined in a `docker-compose.yml`. In the default "attached" mode, you see all the logs from all the containers. In "detached" mode (`-d`), Compose exits after starting the containers, but the containers continue to run in the background. -The `docker-compose run` command is for running "one-off" or "adhoc" tasks. It +The `docker compose run` command is for running "one-off" or "adhoc" tasks. It requires the service name you want to run and only starts containers for services that the running service depends on. Use `run` to run tests or perform an administrative task such as removing or adding data to a data volume @@ -77,7 +77,7 @@ container. The `run` command acts like `docker run -ti` in that it opens an interactive terminal to the container and returns an exit status matching the exit status of the process in the container. -The `docker-compose start` command is useful only to restart containers +The `docker compose start` command is useful only to restart containers that were previously created, but were stopped. It never creates new containers. @@ -88,7 +88,7 @@ any JSON file should be valid Yaml. To use a JSON file with Compose, specify the filename to use, for example: ```console -$ docker-compose -f docker-compose.json up +$ docker compose -f docker-compose.json up ``` ## Should I include my code with `COPY`/`ADD` or a volume? diff --git a/compose/gettingstarted.md b/compose/gettingstarted.md index 4e9295cdeb3..681e9dc466d 100644 --- a/compose/gettingstarted.md +++ b/compose/gettingstarted.md @@ -120,7 +120,6 @@ Create a file called `docker-compose.yml` in your project directory and paste the following: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: build: . @@ -145,10 +144,10 @@ image pulled from the Docker Hub registry. ## Step 4: Build and run your app with Compose -1. From your project directory, start up your application by running `docker-compose up`. +1. From your project directory, start up your application by running `docker compose up`. ```console - $ docker-compose up + $ docker compose up Creating network "composetest_default" with the default driver Creating composetest_web_1 ... @@ -218,7 +217,7 @@ image pulled from the Docker Hub registry. You can inspect images with `docker inspect `. -5. Stop the application, either by running `docker-compose down` +5. Stop the application, either by running `docker compose down` from within your project directory in the second terminal, or by hitting CTRL+C in the original terminal where you started the app. @@ -228,7 +227,6 @@ Edit `docker-compose.yml` in your project directory to add a [bind mount](../storage/bind-mounts.md) for the `web` service: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: build: . @@ -250,10 +248,10 @@ mode and reload the code on change. This mode should only be used in development ## Step 6: Re-build and run the app with Compose -From your project directory, type `docker-compose up` to build the app with the updated Compose file, and run it. +From your project directory, type `docker compose up` to build the app with the updated Compose file, and run it. ```console -$ docker-compose up +$ docker compose up Creating network "composetest_default" with the default driver Creating composetest_web_1 ... @@ -308,16 +306,16 @@ counter should still be incrementing. ## Step 8: Experiment with some other commands If you want to run your services in the background, you can pass the `-d` flag -(for "detached" mode) to `docker-compose up` and use `docker-compose ps` to +(for "detached" mode) to `docker compose up` and use `docker compose ps` to see what is currently running: ```console -$ docker-compose up -d +$ docker compose up -d Starting composetest_redis_1... Starting composetest_web_1... -$ docker-compose ps +$ docker compose ps Name Command State Ports ------------------------------------------------------------------------------------- @@ -325,21 +323,21 @@ composetest_redis_1 docker-entrypoint.sh redis ... Up 6379/tcp composetest_web_1 flask run Up 0.0.0.0:5000->5000/tcp ``` -The `docker-compose run` command allows you to run one-off commands for your +The `docker compose run` command allows you to run one-off commands for your services. For example, to see what environment variables are available to the `web` service: ```console -$ docker-compose run web env +$ docker compose run web env ``` -See `docker-compose --help` to see other available commands. You can also install [command completion](completion.md) for the bash and zsh shell, which also shows you available commands. +See `docker compose --help` to see other available commands. You can also install [command completion](completion.md) for the bash and zsh shell, which also shows you available commands. -If you started Compose with `docker-compose up -d`, stop +If you started Compose with `docker compose up -d`, stop your services once you've finished with them: ```console -$ docker-compose stop +$ docker compose stop ``` You can bring everything down, removing the containers entirely, with the `down` @@ -347,7 +345,7 @@ command. Pass `--volumes` to also remove the data volume used by the Redis container: ```console -$ docker-compose down --volumes +$ docker compose down --volumes ``` At this point, you have seen the basics of how Compose works. diff --git a/compose/gpu-support.md b/compose/gpu-support.md index a1fc90d842c..a46bd9495c5 100644 --- a/compose/gpu-support.md +++ b/compose/gpu-support.md @@ -6,7 +6,7 @@ title: Enabling GPU access with Compose Compose services can define GPU device reservations if the Docker host contains such devices and the Docker Daemon is set accordingly. For this, make sure to install the [prerequisites](../config/containers/resource_constraints.md#gpu) if you have not already done so. -The examples in the following sections focus specifically on providing service containers access to GPU devices with Docker Compose. You can use either `docker-compose` or `docker compose` commands. +The examples in the following sections focus specifically on providing service containers access to GPU devices with Docker Compose. ### Use of service `runtime` property from Compose v2.3 format (legacy) @@ -60,7 +60,7 @@ services: Run with Docker Compose: ```console -$ docker-compose up +$ docker compose up Creating network "gpu_default" with the default driver Creating gpu_test_1 ... done Attaching to gpu_test_1 @@ -102,7 +102,7 @@ services: ``` ```console -$ docker-compose up +$ docker compose up Creating network "gpu_default" with the default driver Creating gpu_test_1 ... done Attaching to gpu_test_1 @@ -161,7 +161,7 @@ services: ``` ```sh -$ docker-compose up +$ docker compose up ... Created TensorFlow device (/device:GPU:0 with 13970 MB memory -> physical GPU (device: 0, name: Tesla T4, pci bus id: 0000:00:1b.0, compute capability: 7.5) ... diff --git a/compose/index.md b/compose/index.md index 638ce84ff74..ef088dc72b7 100644 --- a/compose/index.md +++ b/compose/index.md @@ -8,7 +8,16 @@ redirect_from: - /compose/swarm/ --- ->**Looking for Compose file reference?** [Find the latest version here](compose-file/index.md). +> Important +> +> The new Compose V2, which supports the `compose` command as part of the Docker CLI, is available with the Docker Desktop 4.1 release. +> +> Compose V2 integrates compose functions into the Docker platform, continuing to support most of the previous `docker-compose` features and flags. You can test the Compose V2 by simply replacing the dash (`-`) with a space, and by running `docker compose`, instead of `docker-compose`. +> +> Compose V1 will receive minimal maintenance for security issues, and will be deprecated as of December 28th, 2021. +{: .important} + +>**Looking for Compose file reference?** [Find the Compose specification here](https://compose-spec.io). Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services. @@ -28,12 +37,11 @@ anywhere. 2. Define the services that make up your app in `docker-compose.yml` so they can be run together in an isolated environment. -3. Run `docker compose up` and the [Docker compose command](cli-command.md) starts and runs your entire app. You can alternatively run `docker-compose up` using the docker-compose binary. +3. Run `docker compose up` and the [Docker compose command](cli-command.md) starts and runs your entire app. A `docker-compose.yml` looks like this: ```yaml -version: "{{ site.compose_file_v3 }}" # optional since v1.27.0 services: web: build: . @@ -51,7 +59,7 @@ volumes: ``` For more information about the Compose file, see the -[Compose file reference](compose-file/index.md). +[Compose specification](https://compose-spec.io). Compose has commands for managing the whole lifecycle of your application: @@ -101,12 +109,12 @@ for it can be defined with the `--project-directory` command line option. ### Preserve volume data when containers are created -Compose preserves all volumes used by your services. When `docker-compose up` +Compose preserves all volumes used by your services. When `docker compose up` runs, if it finds any containers from previous runs, it copies the volumes from the old container to the new container. This process ensures that any data you've created in volumes isn't lost. -If you use `docker-compose` on a Windows machine, see +If you use `docker compose` on a Windows machine, see [Environment variables](reference/envvars.md) and adjust the necessary environment variables for your specific needs. @@ -145,7 +153,7 @@ The [Compose file](compose-file/index.md) provides a way to document and configu all of the application's service dependencies (databases, queues, caches, web service APIs, etc). Using the Compose command line tool you can create and start one or more containers for each dependency with a single command -(`docker-compose up`). +(`docker compose up`). Together, these features provide a convenient way for developers to get started on a project. Compose can reduce a multi-page "developer getting @@ -159,9 +167,9 @@ environment in which to run tests. Compose provides a convenient way to create and destroy isolated testing environments for your test suite. By defining the full environment in a [Compose file](compose-file/index.md), you can create and destroy these environments in just a few commands: ```console -$ docker-compose up -d +$ docker compose up -d $ ./run_tests -$ docker-compose down +$ docker compose down ``` ### Single host deployments diff --git a/compose/install.md b/compose/install.md index 5c65ec5d7a8..fe76afd96d7 100644 --- a/compose/install.md +++ b/compose/install.md @@ -26,8 +26,7 @@ Linux systems. ## Install Compose Follow the instructions below to install Compose on Mac, Windows, Windows Server -2016, or Linux systems, or find out about alternatives like using the `pip` -Python package manager or installing Compose as a container. +2016, or Linux systems. > Install a different version > @@ -44,7 +43,6 @@ Python package manager or installing Compose as a container.
  • Windows
  • Windows Server
  • Linux
    • -
  • Alternative install options
  • Pre-release builds
    • @@ -95,7 +93,7 @@ on Microsoft Windows Server and want to install Docker Compose. Invoke-WebRequest "https://github.com/docker/compose/releases/download/{{site.compose_version}}/docker-compose-Windows-x86_64.exe" -UseBasicParsing -OutFile $Env:ProgramFiles\Docker\docker-compose.exe ``` -**Note**: On Windows Server 2019, you can add the Compose executable to `$Env:ProgramFiles\Docker`. Because this directory is registered in the system `PATH`, you can run the `docker-compose --version` command on the subsequent step with no additional configuration. +**Note**: On Windows Server 2019, you can add the Compose executable to `$Env:ProgramFiles\Docker`. Because this directory is registered in the system `PATH`, you can run the `docker compose --version` command on the subsequent step with no additional configuration. > To install a different version of Compose, substitute `{{site.compose_version}}` > with the version of Compose you want to use. @@ -103,9 +101,9 @@ on Microsoft Windows Server and want to install Docker Compose. 3. Test the installation. ```powershell - docker-compose --version + docker compose --version - docker-compose version {{site.compose_version}}, build 01110ad01 + docker compose version {{site.compose_version}}, build 01110ad01 ```
    @@ -113,96 +111,44 @@ on Microsoft Windows Server and want to install Docker Compose. ### Install Compose on Linux systems -On Linux, you can download the Docker Compose binary from the +On supported Linux distributions, you can install Docker Compose using +the `docker-compose-plugin` system package. See [Engine installation instruction](/engine/install/) + +Alternatively, you can download the Docker Compose binary from the [Compose repository release page on GitHub](https://github.com/docker/compose/releases){:target="_blank" rel="noopener" class="_"}. Follow the instructions from the link, which involve running the `curl` command in your terminal to download the binaries. These step-by-step instructions are also included below. -> For `alpine`, the following dependency packages are needed: -> `py-pip`, `python3-dev`, `libffi-dev`, `openssl-dev`, `gcc`, `libc-dev`, `rust`, `cargo` and `make`. -{: .important} - 1. Run this command to download the current stable release of Docker Compose: ```console - $ sudo curl -L "https://github.com/docker/compose/releases/download/{{site.compose_version}}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose + $ mkdir -p ~/.docker/cli-plugins + $ sudo curl -L "https://github.com/docker/compose/releases/download/{{site.compose_version}}/docker-compose-$(uname -s)-$(uname -m)" -o ~/.docker/cli-plugins/docker-compose ``` > To install a different version of Compose, substitute `{{site.compose_version}}` > with the version of Compose you want to use. - If you have problems installing with `curl`, see - [Alternative Install Options](install.md#alternative-install-options) tab above. - 2. Apply executable permissions to the binary: ```console - $ sudo chmod +x /usr/local/bin/docker-compose + $ sudo chmod +x ~/.docker/cli-plugins/docker-compose ``` -> **Note**: If the command `docker-compose` fails after installation, check your path. -> You can also create a symbolic link to `/usr/bin` or any other directory in your path. - -For example: - -```console -$ sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose -``` - -3. Optionally, install [command completion](completion.md) for the - `bash` and `zsh` shell. - -4. Test the installation. +3. Test the installation. ```console - $ docker-compose --version - docker-compose version {{site.compose_version}}, build 1110ad01 + $ docker compose --version + Docker Compose version {{site.compose_version}} ``` - -
    - -### Alternative install options - -- [Install using pip](#install-using-pip) -- [Install as a container](#install-as-a-container) - -#### Install using pip - -> For `alpine`, the following dependency packages are needed: -> `py-pip`, `python3-dev`, `libffi-dev`, `openssl-dev`, `gcc`, `libc-dev`, `rust`, `cargo`, and `make`. -{: .important} - -Compose can be installed from -[pypi](https://pypi.python.org/pypi/docker-compose) using `pip`. If you install -using `pip`, we recommend that you use a -[virtualenv](https://virtualenv.pypa.io/en/latest/) because many operating -systems have python system packages that conflict with docker-compose -dependencies. See the [virtualenv -tutorial](https://docs.python-guide.org/dev/virtualenvs/) to get -started. - -```console -$ pip install docker-compose -``` - -If you are not using virtualenv, - -```console -$ sudo pip install docker-compose -``` - -> pip version 6.0 or greater is required. - -#### Install as a container +## Uninstallation -Compose can also be run inside a container, from a small bash script wrapper. To -install compose as a container run this command: +To uninstall Docker Compose if you installed using `curl`: ```console -$ sudo curl -L --fail https://github.com/docker/compose/releases/download/{{site.compose_version}}/run.sh -o /usr/local/bin/docker-compose -$ sudo chmod +x /usr/local/bin/docker-compose +$ sudo rm ~/.docker/cli-plugins/docker-compose ```
    @@ -216,9 +162,6 @@ candidates from the [Compose repository release page on GitHub](https://github.c Follow the instructions from the link, which involves running the `curl` command in your terminal to download the binaries. -Pre-releases built from the "master" branch are also available for download at -[https://dl.bintray.com/docker-compose/master/](https://dl.bintray.com/docker-compose/master/){: target="_blank" rel="noopener" class="_"}. - > Pre-release builds allow you to try out new features before they are released, > but may be less stable. {: .important} @@ -228,43 +171,6 @@ Pre-releases built from the "master" branch are also available for download at ---- -## Upgrading - -If you're upgrading from Compose 1.2 or earlier, remove or -migrate your existing containers after upgrading Compose. This is because, as of -version 1.3, Compose uses Docker labels to keep track of containers, and your -containers need to be recreated to add the labels. - -If Compose detects containers that were created without labels, it refuses -to run, so that you don't end up with two sets of them. If you want to keep using -your existing containers (for example, because they have data volumes you want -to preserve), you can use Compose 1.5.x to migrate them with the following -command: - -```console -$ docker-compose migrate-to-labels -``` - -Alternatively, if you're not worried about keeping them, you can remove them. -Compose just creates new ones. - -```console -$ docker container rm -f -v myapp_web_1 myapp_db_1 ... -``` - -## Uninstallation - -To uninstall Docker Compose if you installed using `curl`: - -```console -$ sudo rm /usr/local/bin/docker-compose -``` - -To uninstall Docker Compose if you installed using `pip`: - -```console -$ pip uninstall docker-compose -``` > Got a "Permission denied" error? > diff --git a/compose/networking.md b/compose/networking.md index fc639f574b7..4970ae0ed70 100644 --- a/compose/networking.md +++ b/compose/networking.md @@ -22,7 +22,6 @@ identical to the container name. For example, suppose your app is in a directory called `myapp`, and your `docker-compose.yml` looks like this: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: build: . @@ -34,7 +33,7 @@ services: - "8001:5432" ``` -When you run `docker-compose up`, the following happens: +When you run `docker compose up`, the following happens: 1. A network called `myapp_default` is created. 2. A container is created using `web`'s configuration. It joins the network @@ -68,7 +67,7 @@ look like `postgres://{DOCKER_IP}:8001`. ## Update containers -If you make a configuration change to a service and run `docker-compose up` to update it, the old container is removed and the new one joins the network under a different IP address but the same name. Running containers can look up that name and connect to the new address, but the old address stops working. +If you make a configuration change to a service and run `docker compose up` to update it, the old container is removed and the new one joins the network under a different IP address but the same name. Running containers can look up that name and connect to the new address, but the old address stops working. If any containers have connections open to the old container, they are closed. It is a container's responsibility to detect this condition, look up the name again and reconnect. @@ -77,7 +76,6 @@ If any containers have connections open to the old container, they are closed. I Links allow you to define extra aliases by which a service is reachable from another service. They are not required to enable services to communicate - by default, any service can reach any other service at that service's name. In the following example, `db` is reachable from `web` at the hostnames `db` and `database`: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: @@ -108,8 +106,6 @@ Each service can specify what networks to connect to with the *service-level* `n Here's an example Compose file defining two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common - only `app` can talk to both. ```yaml -version: "{{ site.compose_file_v3 }}" - services: proxy: build: ./proxy @@ -142,7 +138,6 @@ Networks can be configured with static IP addresses by setting the [ipv4_address Networks can also be given a [custom name](compose-file/compose-file-v3.md#network-configuration-reference) (since version 3.5): ```yaml -version: "{{ site.compose_file_v3 }}" services: # ... networks: @@ -161,7 +156,6 @@ For full details of the network configuration options available, see the followi Instead of (or as well as) specifying your own networks, you can also change the settings of the app-wide default network by defining an entry under `networks` named `default`: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: build: . diff --git a/compose/production.md b/compose/production.md index c18c5210451..03748091f14 100644 --- a/compose/production.md +++ b/compose/production.md @@ -35,7 +35,7 @@ Once you've got a second configuration file, tell Compose to use it with the `-f` option: ```console -$ docker-compose -f docker-compose.yml -f production.yml up -d +$ docker compose -f docker-compose.yml -f production.yml up -d ``` See [Using multiple compose files](extends.md#different-environments) for a more @@ -48,8 +48,8 @@ recreate your app's containers. To redeploy a service called `web`, use: ```console -$ docker-compose build web -$ docker-compose up --no-deps -d web +$ docker compose build web +$ docker compose up --no-deps -d web ``` This first rebuilds the image for `web` and then stop, destroy, and recreate @@ -62,7 +62,7 @@ You can use Compose to deploy an app to a remote Docker host by setting the `DOCKER_HOST`, `DOCKER_TLS_VERIFY`, and `DOCKER_CERT_PATH` environment variables appropriately. -Once you've set up your environment variables, all the normal `docker-compose` +Once you've set up your environment variables, all the normal `docker compose` commands work with no further configuration. ## Compose documentation diff --git a/compose/profiles.md b/compose/profiles.md index 0a203924a29..0ca3acff663 100644 --- a/compose/profiles.md +++ b/compose/profiles.md @@ -21,7 +21,6 @@ Services are associated with profiles through the array of profile names: ```yaml -version: "{{ site.compose_file_v3 }}" services: frontend: image: frontend @@ -46,7 +45,7 @@ Here the services `frontend` and `phpmyadmin` are assigned to the profiles respective profiles are enabled. Services without a `profiles` attribute will _always_ be enabled, i.e. in this -case running `docker-compose up` would only start `backend` and `db`. +case running `docker compose up` would only start `backend` and `db`. Valid profile names follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`. @@ -61,8 +60,8 @@ To enable a profile supply the `--profile` [command-line option](reference/index use the [`COMPOSE_PROFILES` environment variable](reference/envvars.md#compose_profiles): ```sh -$ docker-compose --profile debug up -$ COMPOSE_PROFILES=debug docker-compose up +$ docker compose --profile debug up +$ COMPOSE_PROFILES=debug docker compose up ``` The above command would both start your application with the `debug` profile enabled. @@ -73,8 +72,8 @@ Multiple profiles can be specified by passing multiple `--profile` flags or a comma-separated list for the `COMPOSE_PROFILES` environment variable: ```sh -$ docker-compose --profile frontend --profile debug up -$ COMPOSE_PROFILES=frontend,debug docker-compose up +$ docker compose --profile frontend --profile debug up +$ COMPOSE_PROFILES=frontend,debug docker compose up ``` ## Auto-enabling profiles and dependency resolution @@ -85,7 +84,6 @@ manually. This can be used for one-off services and debugging tools. As an example consider this configuration: ```yaml -version: "{{ site.compose_file_v3 }}" services: backend: image: backend @@ -104,21 +102,20 @@ services: ```sh # will only start backend and db -$ docker-compose up -d +$ docker compose up -d # this will run db-migrations (and - if necessary - start db) # by implicitly enabling profile `tools` -$ docker-compose run db-migrations +$ docker compose run db-migrations ``` -But keep in mind that `docker-compose` will only automatically enable the +But keep in mind that `docker compose` will only automatically enable the profiles of the services on the command line and not of any dependencies. This means that all services the targeted service `depends_on` must have a common profile with it, be always enabled (by omitting `profiles`) or have a matching profile enabled explicitly: ```yaml -version: "{{ site.compose_file_v3 }}" services: web: image: web @@ -142,14 +139,14 @@ services: ```sh # will only start "web" -$ docker-compose up -d +$ docker compose up -d # this will start mock-backend (and - if necessary - db) # by implicitly enabling profile `dev` -$ docker-compose up -d mock-backend +$ docker compose up -d mock-backend # this will fail because profile "dev" is disabled -$ docker-compose up phpmyadmin +$ docker compose up phpmyadmin ``` Although targeting `phpmyadmin` will automatically enable its profiles - i.e. @@ -166,8 +163,8 @@ or enable a profile of `db` explicitly: ```sh # profile "debug" is enabled automatically by targeting phpmyadmin -$ docker-compose --profile dev up phpmyadmin -$ COMPOSE_PROFILES=dev docker-compose up phpmyadmin +$ docker compose --profile dev up phpmyadmin +$ COMPOSE_PROFILES=dev docker compose up phpmyadmin ``` diff --git a/compose/release-notes.md b/compose/release-notes.md index 21a7f6081a3..26defbc6bfd 100644 --- a/compose/release-notes.md +++ b/compose/release-notes.md @@ -7,6 +7,10 @@ redirect_from: - /release-notes/docker-compose/ --- +## 2.0.0 + + TODO + ## 1.29.2 (2021-05-10) From 73cc83ea62e6d147376ab85b1789f8b55ce37513 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Mon, 13 Sep 2021 11:15:41 +0200 Subject: [PATCH 2/8] document dotEnv file format as supported by Compose V2 Signed-off-by: Nicolas De Loof --- compose/env-file.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/compose/env-file.md b/compose/env-file.md index 2e44989926e..992428418dd 100644 --- a/compose/env-file.md +++ b/compose/env-file.md @@ -20,7 +20,12 @@ The project directory is specified by the order of precedence: ## Syntax rules -The following syntax rules apply to the `.env` file: +The "dotEnv" file format is a _de facto_ convention, not a standard with no clear specification, +and as such syntax might differ between tools using this file format. + +The following syntax rules apply to the `.env` file as supported by Docker Compose: + +### Compose 1.x - Compose expects each line in an `env` file to be in `VAR=VAL` format. - Lines beginning with `#` are processed as comments and ignored. @@ -28,6 +33,37 @@ The following syntax rules apply to the `.env` file: - There is no special handling of quotation marks. This means that **they are part of the VAL**. +### Compose 2.x + +Compose V2 adopt the [Ruby-style dotEnv file syntax](https://github.com/bkeepers/dotenv#usage), +which means: + +- Compose expects each line in an `env` file to be in `VAR=VAL` format. Can be preceeded by `export ` which will be ignored +- Lines beginning with `#` are processed as comments and ignored. +- Blank lines are ignored. +- Multi-line values can be wrapped using double quotes. +- Values can be wrapped by single or double quotes, which will be remived from actual value +- Variables defined by dolar sign `$` inside value are substitued, unless value is wrapped by single quotes + +``` +# Some comment, ignored +USER=docker + +# $word won't be considered a variable thanks to single quotes +PASSWORD='pas$word' + +# ${USER} will be substitued by value from USER variable +DATABASE_URL="postgres://${USER}@localhost/my_database" + +# export is ignored by Docker Compose, but usefull to use the same file for shell scripts +export S3_BUCKET=YOURS3BUCKET + +# A multi-line value, wrapped by double quotes +PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- +... +-----END DSA PRIVATE KEY-----" +``` + ## Compose file and CLI variables The environment variables you define here are used for From 8d03d9e9e470c8f8d84afe54a5ebe54cb4809e2f Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Tue, 14 Sep 2021 09:42:50 +0200 Subject: [PATCH 3/8] doc focus on V2, subsection about V1-V2 transition Signed-off-by: Nicolas De Loof --- _data/toc.yaml | 12 +++++----- ...mand-compatibility.md => compatibility.md} | 0 compose/{cli-command.md => transition.md} | 24 +++++++++---------- 3 files changed, 18 insertions(+), 18 deletions(-) rename compose/{cli-command-compatibility.md => compatibility.md} (100%) rename compose/{cli-command.md => transition.md} (96%) diff --git a/_data/toc.yaml b/_data/toc.yaml index 89c29305c1f..11c89a8adcb 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1311,12 +1311,6 @@ manuals: section: - path: /compose/ title: Overview of Docker Compose - - sectiontitle: Compose V2 - section: - - path: /compose/cli-command/ - title: Overview - - path: /compose/cli-command-compatibility/ - title: Compatibility - path: /compose/install/ title: Install Compose - path: /compose/gettingstarted/ @@ -1341,6 +1335,12 @@ manuals: title: Sample apps with Compose - path: /compose/release-notes/ title: Release notes + - sectiontitle: Compose V1 + section: + - path: /compose/transition/ + title: Transition + - path: /compose/compatibility/ + title: Compatibility - sectiontitle: Docker Hub section: diff --git a/compose/cli-command-compatibility.md b/compose/compatibility.md similarity index 100% rename from compose/cli-command-compatibility.md rename to compose/compatibility.md diff --git a/compose/cli-command.md b/compose/transition.md similarity index 96% rename from compose/cli-command.md rename to compose/transition.md index 53d323c9fb0..32643a41ded 100644 --- a/compose/cli-command.md +++ b/compose/transition.md @@ -1,18 +1,9 @@ --- -description: Compose V2 -keywords: compose, V2 -title: Compose V2 +description: Compose V1 to V2 +keywords: compose +title: Compose V1 to V2 --- -## Compose V2 and the new `docker compose` command - -Starting with Docker Desktop 3.4.0, you can run Compose V2 commands without modifying your invocations, by enabling the drop-in replacement of the previous `docker-compose` with the new command. See the section [Installing Compose v2](#installing-compose-v2) for detailed instructions how to enable the drop-in replacement. - -We turn this option on automatically for Docker Desktop users, so that users can seamlessly move to Docker Compose V2 without the need to upgrade any of their scripts. If you run into any problems with Compose V2, you can easily switch back to Compose V1 by either by making changes in Docker Desktop Settings, or by running the command `docker-compose disable-v2`. - -Your feedback is important to us. Let us know your feedback on the new 'compose' command by creating an issue in the [Compose](https://github.com/docker/compose/issues){:target="_blank" rel="noopener" class="_"} GitHub repository. -{: .important} - ## Context of Docker Compose evolution Introduction of the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"} makes a clean distinction between the Compose YAML file model and the `docker-compose` implementation. Making this change has enabled a number of enhancements, including adding the `compose` command directly into the Docker CLI, being able to “up” a Compose application on cloud platforms by simply switching the Docker context, and launching of [Amazon ECS](/cloud/ecs-integration) and [Microsoft ACI](/cloud/aci-integration). As the Compose specification evolves, new features land faster in the Docker CLI. @@ -22,3 +13,12 @@ While docker-compose is still supported and maintained, Compose V2 implementatio Additionally, Compose V2 also supports [Apple silicon](../desktop/mac/apple-silicon.md). For more information about the flags that are supported in the new compose command, see the [docker-compose compatibility list](cli-command-compatibility.md). + +## Compose V2 and the new `docker compose` command + +Starting with Docker Desktop 3.4.0, you can run Compose V2 commands without modifying your invocations, by enabling the drop-in replacement of the previous `docker-compose` with the new command. See the section [Installing Compose v2](#installing-compose-v2) for detailed instructions how to enable the drop-in replacement. + +We turn this option on automatically for Docker Desktop users, so that users can seamlessly move to Docker Compose V2 without the need to upgrade any of their scripts. If you run into any problems with Compose V2, you can easily switch back to Compose V1 by either by making changes in Docker Desktop Settings, or by running the command `docker-compose disable-v2`. + +Your feedback is important to us. Let us know your feedback on the new 'compose' command by creating an issue in the [Compose](https://github.com/docker/compose/issues){:target="_blank" rel="noopener" class="_"} GitHub repository. +{: .important} \ No newline at end of file From 9db04c97a9f12ebc455d105dccceb828b68147f3 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Tue, 14 Sep 2021 09:45:10 +0200 Subject: [PATCH 4/8] typo Signed-off-by: Nicolas De Loof --- compose/env-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compose/env-file.md b/compose/env-file.md index 992428418dd..89320a82a22 100644 --- a/compose/env-file.md +++ b/compose/env-file.md @@ -42,7 +42,7 @@ which means: - Lines beginning with `#` are processed as comments and ignored. - Blank lines are ignored. - Multi-line values can be wrapped using double quotes. -- Values can be wrapped by single or double quotes, which will be remived from actual value +- Values can be wrapped by single or double quotes, which will be removed from actual value - Variables defined by dolar sign `$` inside value are substitued, unless value is wrapped by single quotes ``` From 60f4398ff6923be064ed0bc719c1f4d84058081e Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Tue, 14 Sep 2021 10:48:03 +0200 Subject: [PATCH 5/8] compose V1 End of life Signed-off-by: Nicolas De Loof --- _data/toc.yaml | 12 ++++++------ compose/index.md | 4 ++-- compose/transition.md | 19 ++++++++++++++++++- 3 files changed, 26 insertions(+), 9 deletions(-) diff --git a/_data/toc.yaml b/_data/toc.yaml index 11c89a8adcb..30e593163d8 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1311,6 +1311,12 @@ manuals: section: - path: /compose/ title: Overview of Docker Compose + - sectiontitle: Compose V1 + section: + - path: /compose/transition/ + title: Transition + - path: /compose/compatibility/ + title: Compatibility - path: /compose/install/ title: Install Compose - path: /compose/gettingstarted/ @@ -1335,12 +1341,6 @@ manuals: title: Sample apps with Compose - path: /compose/release-notes/ title: Release notes - - sectiontitle: Compose V1 - section: - - path: /compose/transition/ - title: Transition - - path: /compose/compatibility/ - title: Compatibility - sectiontitle: Docker Hub section: diff --git a/compose/index.md b/compose/index.md index ef088dc72b7..95de7be7ea9 100644 --- a/compose/index.md +++ b/compose/index.md @@ -10,9 +10,9 @@ redirect_from: > Important > -> The new Compose V2, which supports the `compose` command as part of the Docker CLI, is available with the Docker Desktop 4.1 release. +> The new Compose V2, which supports the `compose` command as part of the Docker CLI, is available with the Docker Desktop 4.1.0 release. > -> Compose V2 integrates compose functions into the Docker platform, continuing to support most of the previous `docker-compose` features and flags. You can test the Compose V2 by simply replacing the dash (`-`) with a space, and by running `docker compose`, instead of `docker-compose`. +> Compose V2 integrates compose functions into the Docker platform, continuing to support most of the previous `docker-compose` features and flags. You can use Compose V2 by simply replacing the dash (`-`) with a space, and by running `docker compose`, instead of `docker-compose`. > > Compose V1 will receive minimal maintenance for security issues, and will be deprecated as of December 28th, 2021. {: .important} diff --git a/compose/transition.md b/compose/transition.md index 32643a41ded..c93627bed14 100644 --- a/compose/transition.md +++ b/compose/transition.md @@ -21,4 +21,21 @@ Starting with Docker Desktop 3.4.0, you can run Compose V2 commands without modi We turn this option on automatically for Docker Desktop users, so that users can seamlessly move to Docker Compose V2 without the need to upgrade any of their scripts. If you run into any problems with Compose V2, you can easily switch back to Compose V1 by either by making changes in Docker Desktop Settings, or by running the command `docker-compose disable-v2`. Your feedback is important to us. Let us know your feedback on the new 'compose' command by creating an issue in the [Compose](https://github.com/docker/compose/issues){:target="_blank" rel="noopener" class="_"} GitHub repository. -{: .important} \ No newline at end of file +{: .important} + +## Compose V1 end of life + +### September 28th, 2021 +New features and bug fixes will only be considered in the V2 codebase (we may make some exceptions). +Users on Mac/Windows will be defaulted into Docker Compose V2, but can still opt out through the UI and the cli. + +Docker Compose V1 will only be maintained regarding security issues +V2 branch on docker/compose repo becomes the default one + +### Dec 28th, 2021: +V1 is marked as deprecated +No other impacts to users than a strong signal to users + +### March 28th, 2022: +End of security fixes +No new contribution will be accepted to the V1 branch, even for security fixes. From 7a86909a2d6070b1b6838b8421e2d36bd6d302c9 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Wed, 15 Sep 2021 08:06:25 +0200 Subject: [PATCH 6/8] remove details about legacy compose file versions Signed-off-by: Nicolas De Loof --- _data/toc.yaml | 6 +- _includes/content/compose-matrix.md | 29 -- compose/compose-file/compose-file-v2.md | 9 +- compose/compose-file/compose-file-v3.md | 8 +- compose/compose-file/compose-versioning.md | 492 +-------------------- compose/compose-file/index.md | 9 +- 6 files changed, 14 insertions(+), 539 deletions(-) delete mode 100644 _includes/content/compose-matrix.md diff --git a/_data/toc.yaml b/_data/toc.yaml index 30e593163d8..e801572848e 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1099,11 +1099,7 @@ reference: - sectiontitle: Compose file reference section: - path: /compose/compose-file/ - title: Compose Specification - - path: /compose/compose-file/compose-file-v3/ - title: Version 3 - - path: /compose/compose-file/compose-file-v2/ - title: Version 2 + title: Compose file reference - path: /compose/compose-file/compose-versioning/ title: About versions and upgrading - path: /compose/faq/ diff --git a/_includes/content/compose-matrix.md b/_includes/content/compose-matrix.md deleted file mode 100644 index 9eec23afe24..00000000000 --- a/_includes/content/compose-matrix.md +++ /dev/null @@ -1,29 +0,0 @@ -This table shows which Compose file versions support specific Docker releases. - -| **Compose file format** | **Docker Engine release** | -| ------------------- | ------------------ | -| Compose specification | 19.03.0+ | -| 3.8 | 19.03.0+ | -| 3.7 | 18.06.0+ | -| 3.6 | 18.02.0+ | -| 3.5 | 17.12.0+ | -| 3.4 | 17.09.0+ | -| 3.3 | 17.06.0+ | -| 3.2 | 17.04.0+ | -| 3.1 | 1.13.1+ | -| 3.0 | 1.13.0+ | -| 2.4 | 17.12.0+ | -| 2.3 | 17.06.0+ | -| 2.2 | 1.13.0+ | -| 2.1 | 1.12.0+ | -| 2.0 | 1.10.0+ | - -In addition to Compose file format versions shown in the table, the Compose -itself is on a release schedule, as shown in [Compose -releases](https://github.com/docker/compose/releases/), but file format versions -do not necessarily increment with each release. For example, Compose file format -3.0 was first introduced in [Compose release -1.10.0](https://github.com/docker/compose/releases/tag/1.10.0), and versioned -gradually in subsequent releases. - -The latest Compose file format is defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md){:target="_blank" rel="noopener" class="_"} and is implemented by Docker Compose **1.27.0+**. diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index 7675a3efd7b..9ec59736a6a 100644 --- a/compose/compose-file/compose-file-v2.md +++ b/compose/compose-file/compose-file-v2.md @@ -10,13 +10,8 @@ toc_min: 1 These topics describe version 2 of the Compose file format. -## Compose and Docker compatibility matrix - -There are several versions of the Compose file format – 1, 2, 2.x, and 3.x. The -table below is a quick look. For full details on what each version includes and -how to upgrade, see **[About versions and upgrading](compose-versioning.md)**. - -{% include content/compose-matrix.md %} +Compose file version 2 is obsolete, better refere to the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). See [Compose file versions and upgrading](compose-versioning.md) +{: .important} ## Service configuration reference diff --git a/compose/compose-file/compose-file-v3.md b/compose/compose-file/compose-file-v3.md index 9c92c5244ac..755a827967e 100644 --- a/compose/compose-file/compose-file-v3.md +++ b/compose/compose-file/compose-file-v3.md @@ -11,13 +11,9 @@ toc_min: 1 These topics describe version 3 of the Compose file format. This is the newest version. -## Compose and Docker compatibility matrix - -There are several versions of the Compose file format – 1, 2, 2.x, and 3.x. The -table below is a quick look. For full details on what each version includes and -how to upgrade, see **[About versions and upgrading](compose-versioning.md)**. +Compose file version 2 is obsolete, better refere to the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). See [Compose file versions and upgrading](compose-versioning.md) +{: .important} -{% include content/compose-matrix.md %} ## Compose file structure and examples diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md index 60fb0d8ab33..e83586b3086 100644 --- a/compose/compose-file/compose-versioning.md +++ b/compose/compose-file/compose-versioning.md @@ -7,108 +7,28 @@ title: Compose file versions and upgrading The Compose file is a [YAML](https://yaml.org) file defining services, networks, and volumes for a Docker application. -The Compose file formats are now described in these references, specific to each version. - -| **Reference file** | **What changed in this version** | -|:------------------------------------------------------|:---------------------------------| -| [Compose Specification](index.md) (most current, and recommended) | [Versioning](compose-versioning.md#versioning) | -| [Version 3](compose-file-v3.md) | [Version 3 updates](#version-3) | -| [Version 2](compose-file-v2.md) | [Version 2 updates](#version-2) | -| Version 1 (Deprecated) | [Version 1 updates](#version-1-deprecated) | - -The topics below explain the differences among the versions, Docker Engine -compatibility, and [how to upgrade](#upgrading). - -## Compatibility matrix - -There are several versions of the Compose file format – 1, 2, 2.x, and 3.x - -{% include content/compose-matrix.md %} - -> Looking for more detail on Docker and Compose compatibility? -> -> We recommend keeping up-to-date with newer releases as much as possible. -However, if you are using an older version of Docker and want to determine which -Compose release is compatible, refer to the [Compose release -notes](https://github.com/docker/compose/releases/). Each set of release notes -gives details on which versions of Docker Engine are supported, along -with compatible Compose file format versions. (See also, the discussion in -[issue #3404](https://github.com/docker/docker.github.io/issues/3404).) +## Versioning +> Earlier releases of Docker Compose used a `version` field in the Compose file to define supported attributes. The latest and recommended version of the Compose file format is defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). This format merges the [legacy 2.x](compose-file-v2.md) and [3.x](compose-file-v3.md) file formats and is implemented by **Compose 1.27.0+** and **Compose V2**. +: .important} -For details on versions and how to upgrade, see -[Versioning](compose-versioning.md#versioning) and -[Upgrading](compose-versioning.md#upgrading). +For modern usage, you should **not** declare a `version` attribute in your Compose file. File format is +described by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). -## Versioning +## Legacy 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 1. (Obsolete) - 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](../../engine/swarm/index.md). 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://github.com/compose-spec/compose-spec/blob/master/spec.md). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**. - -> ### v2 and v3 Declaration -> -> **Note**: 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. - - -The [Compatibility Matrix](#compatibility-matrix) shows Compose file versions mapped to Docker Engine releases. - -To move your project to a later version, see the [Upgrading](#upgrading) -section. - -> **Note**: If you're using -> [multiple Compose files](../extends.md#multiple-compose-files) or -> [extending services](../extends.md#extending-services), 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 1 (Deprecated) - -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**. It will be deprecated in a -future Compose release. - -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](../networking.md) 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: - - "5000:5000" - volumes: - - .:/code - links: - - redis - redis: - image: redis ### Version 2 @@ -128,148 +48,6 @@ 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](../networking.md). -> **Note** -> -> 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: "{{ site.compose_file_v2 }}" - services: - web: - build: . - ports: - - "5000:5000" - volumes: - - .:/code - redis: - image: redis - -A more extended example, defining volumes and networks: - - version: "{{ site.compose_file_v2 }}" - services: - web: - build: . - ports: - - "5000: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: "{{ site.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 @@ -284,261 +62,7 @@ the [upgrading](#upgrading) guide for how to migrate away from these. - Added: [deploy](compose-file-v3.md#deploy) -> **Note**: 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: "3" -> ``` -> -> is equivalent to: -> -> ```yaml -> version: "3.0" -> ``` - -### 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`. ## 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: "{{ site.compose_file_v3 }}" - 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, see [Extending services](../extends.md#extending-services).) -- `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. - -### 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](../networking.md), or connect both the external container and - your service's containers to an - [external network](../networking.md#use-a-pre-existing-network). - -- `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: "{{ site.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 - -## 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. Because the -> resulting configuration is only an approximate using non-Swarm mode -> properties, it may produce unexpected results. - -## Compose file format references -- [Compose Specification](index.md) -- [Compose file version 3](compose-file-v3.md) -- [Compose file version 2](compose-file-v2.md) \ No newline at end of file +The [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md) defines all the attributes from both versions 2.x and 3.x, so basically you don't need anything changed for your Compose file to be compliant with the Specification. Just the `version` attribute will be ignored, you can remove it. diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index de284d7fd42..e6f3bb5c9ab 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -12,15 +12,8 @@ toc_min: 1 ## Reference and guidelines These topics describe the Docker Compose implementation of the Compose format. -Docker Compose **1.27.0+** implements the format defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). Previous Docker Compose versions have support for several Compose file formats – 2, 2.x, and 3.x. The Compose specification is a unified 2.x and 3.x file format, aggregating properties across these formats. +Docker Compose **1.27.0+** implements the format defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). Previous Docker Compose versions have support for several Compose file formats – 2, 2.x, and 3.x. The Compose specification is a unified 2.x and 3.x file format, aggregating properties across these formats, and use of `version` in a compose file is obsolete. -## Compose and Docker compatibility matrix - -There are several versions of the Compose file format – 2, 2.x, and 3.x. The -table below provides a snapshot of various versions. For full details on what each version includes and -how to upgrade, see **[About versions and upgrading](compose-versioning.md)**. - -{% include content/compose-matrix.md %} ## Compose documentation From 093b2d010e9be761dfd32cf0d5a6ed1e3781f019 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Wed, 15 Sep 2021 10:49:05 +0200 Subject: [PATCH 7/8] relax End of Life policy Signed-off-by: Nicolas De Loof --- compose/transition.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/compose/transition.md b/compose/transition.md index c93627bed14..d627c745fe0 100644 --- a/compose/transition.md +++ b/compose/transition.md @@ -26,16 +26,16 @@ Your feedback is important to us. Let us know your feedback on the new 'compose' ## Compose V1 end of life ### September 28th, 2021 -New features and bug fixes will only be considered in the V2 codebase (we may make some exceptions). +Compose V2 is the default development branch on GitHub. +New features and bug fixes will be considered in the V2 codebase. Legacy V1 codebase will only be considered +for security issues and critical bug fixes. Users on Mac/Windows will be defaulted into Docker Compose V2, but can still opt out through the UI and the cli. -Docker Compose V1 will only be maintained regarding security issues -V2 branch on docker/compose repo becomes the default one - -### Dec 28th, 2021: -V1 is marked as deprecated +### March 28th, 2022: +After a 6 months transition period, V1 is marked as deprecated No other impacts to users than a strong signal to users -### March 28th, 2022: +### End of Life +Actual date to be defined based on community feedback and Compose V2 adoption End of security fixes No new contribution will be accepted to the V1 branch, even for security fixes. From b3180282b144f71fcd649fe501708c7dae5beecb Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Wed, 15 Sep 2021 14:07:25 +0200 Subject: [PATCH 8/8] document installation for all users Signed-off-by: Nicolas De Loof --- compose/install.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/compose/install.md b/compose/install.md index fe76afd96d7..eeed3d16c3f 100644 --- a/compose/install.md +++ b/compose/install.md @@ -127,8 +127,8 @@ also included below. $ sudo curl -L "https://github.com/docker/compose/releases/download/{{site.compose_version}}/docker-compose-$(uname -s)-$(uname -m)" -o ~/.docker/cli-plugins/docker-compose ``` - > To install a different version of Compose, substitute `{{site.compose_version}}` - > with the version of Compose you want to use. + > This command installs Compose V2 for the active user under $HOME directory. To install for all + > users on your system, replace `~/.docker/cli-plugins` by `/usr/local/lib/docker/cli-plugins`. 2. Apply executable permissions to the binary: