From a70e6ab243f32c1cb4de25e713d805b9918a19a8 Mon Sep 17 00:00:00 2001 From: Guillaume Lours Date: Thu, 14 Apr 2022 15:49:20 +0200 Subject: [PATCH] Update Compose installation for the V2 GA announcement Signed-off-by: Guillaume Lours --- _config.yml | 4 +- compose/install.md | 215 ++++++++++++++++----------------------------- 2 files changed, 76 insertions(+), 143 deletions(-) diff --git a/_config.yml b/_config.yml index 507918769c..5ecc307f57 100644 --- a/_config.yml +++ b/_config.yml @@ -22,8 +22,8 @@ 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_v2_version: "2.2.3" +compose_v1_version: "1.29.2" +compose_version: "v2.4.1" compose_file_v3: "3.9" compose_file_v2: "2.4" machine_version: "0.16.0" diff --git a/compose/install.md b/compose/install.md index 264c6ef507..35973554ea 100644 --- a/compose/install.md +++ b/compose/install.md @@ -20,9 +20,10 @@ have Docker Engine installed either locally or remote, depending on your setup. - On desktop systems like Docker Desktop for Mac and Windows, Docker Compose is included as part of those desktop installs. -- On Linux systems, first install the -[Docker Engine](../engine/install/index.md#server){: target="_blank" rel="noopener" class="_"} -for your OS as described on the Get Docker page, then come back here for +- On Linux systems, you can install Docker Compose with the Docker Engine using the +[convenience script](../engine/install/index.md#server){: target="_blank" rel="noopener" class="_"}. Select the install Docker Engine page for your distribution and then look for instructions on installing using the convenience script. +Otherwise, you should first install the [Docker Engine](../engine/install/index.md#server){: target="_blank" rel="noopener" class="_"} +for your OS and then refer to this page for instructions on installing Compose on Linux systems. @@ -31,27 +32,23 @@ 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 > > The instructions below outline installation of the current stable release -> (**v{{site.compose_version}}**) of Compose. To install a different version of -> Compose, replace the given release number with the one that you want. For instructions to install Compose 2.0.0 on Linux, see [Install Compose 2.0.0 on Linux](cli-command.md#install-on-linux). +> (**{{site.compose_version}}**) of Compose. To install a different version of +> Compose, replace the given release number with the one that you want. > > Compose releases are also listed and available for direct download on the > [Compose repository release page on GitHub](https://github.com/docker/compose/releases){:target="_blank" rel="noopener" class="_"}. -> To install a **pre-release** of Compose, refer to the [install pre-release builds](#install-pre-release-builds) -> section.
@@ -95,185 +92,121 @@ on Microsoft Windows Server and want to install Docker Compose. ``` Then run the following command to download the current stable release of - Compose (v{{site.compose_version}}): + Compose ({{site.compose_version}}): ```powershell 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}}` + > To install a different version of Compose, substitute `{{site.compose_version}}` > with the version of Compose you want to use. 3. Test the installation. ```powershell - docker-compose --version - - docker-compose version {{site.compose_version}}, build 01110ad01 + $ docker compose version + Docker Compose version {{site.compose_version}} ``` -
### Install Compose on Linux systems On Linux, 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="_"}. +[Compose repository release page on GitHub](https://github.com/docker/compose/releases){:target="_blank" rel="noopener" class="_"} and copying it into `$HOME/.docker/cli-plugins` as `docker-compose`. 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 + $ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} + $ mkdir -p $DOCKER_CONFIG/cli-plugins + $ curl -SL https://github.com/docker/compose/releases/download/{{site.compose_version}}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose ``` + This command installs Compose for the active user under `$HOME` directory. To install Docker Compose for all users on your system, replace `~/.docker/cli-plugins` with `/usr/local/lib/docker/cli-plugins`. + + > To install a different version of Compose, substitute `{{site.compose_version}}` - > with the version of Compose you want to use. For instructions on how to - > install Compose `{{site.compose_v2_version}}` on Linux, see [Install - > Compose 2.0.0 on Linux](../cli-command#install-on-linux) + > 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: +2. Apply executable permissions to the binary: + ```console + $ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose + ``` + or if you choose to install Compose for all users ```console - $ sudo chmod +x /usr/local/bin/docker-compose + $ sudo chmod +x /usr/local/lib/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. Test the installation. -3. Optionally, install [command completion](completion.md) for the - `bash` and `zsh` shell. + ```console + $ docker compose version + Docker Compose version {{site.compose_version}} + ``` +
+
-4. Test the installation. +### Install Compose as standalone binary on Linux systems + +You can use Compose as a standalone binary without installing the Docker CLI. + +1. Run this command to download the current stable release of Docker Compose: + + ```console + $ curl -SL https://github.com/docker/compose/releases/download/{{site.compose_version}}/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose + ``` + + > To install a different version of Compose, substitute `{{site.compose_version}}` + > with the version of Compose you want to use. + +2. Apply executable permissions to the binary: + + ```console + $ sudo chmod +x /usr/local/bin/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. Test the installation. ```console $ docker-compose --version - docker-compose version {{site.compose_version}}, build 1110ad01 + 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 -$ pip3 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 - -Compose can also be run inside a container, from a small bash script wrapper. To -install compose as a container run this command: - -```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 -``` - -
- -
- -### Install pre-release builds - -If you're interested in trying out a pre-release build, you can download release -candidates 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 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} -
---- -## 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 -``` + ```console + $ rm $DOCKER_CONFIG/cli-plugins/docker-compose + ``` + + or if you choose to install Compose for all users -To uninstall Docker Compose if you installed using `pip`: - -```console -$ pip uninstall docker-compose -``` + ```console + $ sudo rm /usr/local/lib/docker/cli-plugins/docker-compose + ``` > Got a "Permission denied" error? >