From 013f5331ca536c072659e2d6ff2810410962f94c Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Thu, 10 Aug 2023 08:45:02 +0100 Subject: [PATCH] compose freshness (#17889) Co-authored-by: aevesdocker --- compose/environment-variables/env-file.md | 4 +-- .../envvars-precedence.md | 7 ++-- compose/environment-variables/envvars.md | 4 +-- .../set-environment-variables.md | 11 +++--- compose/features-uses.md | 22 +++++------- compose/file-watch.md | 21 +++++------ compose/gettingstarted.md | 12 +++---- compose/gpu-support.md | 19 +++++----- compose/history.md | 14 ++++---- compose/index.md | 8 ++--- compose/install/index.md | 12 +++---- compose/install/linux.md | 2 +- compose/install/standalone.md | 19 +++++----- compose/install/uninstall.md | 35 ++++++++++--------- compose/networking.md | 13 ++++--- compose/production.md | 14 +++----- compose/profiles.md | 27 +++++++------- compose/samples-for-compose.md | 10 +++--- compose/use-secrets.md | 2 +- 19 files changed, 125 insertions(+), 131 deletions(-) diff --git a/compose/environment-variables/env-file.md b/compose/environment-variables/env-file.md index 6e3c40d52b..0ed5a6f5f0 100644 --- a/compose/environment-variables/env-file.md +++ b/compose/environment-variables/env-file.md @@ -1,7 +1,7 @@ --- description: Understand the accepted syntax for declaring environment variables. keywords: fig, composition, compose, docker, orchestration, environment, env file -title: Use an environment file +title: Use an environment file in Docker Compose redirect_from: - /compose/env-file/ --- @@ -53,5 +53,5 @@ For braced expressions, the following formats are supported: ## Precedence -Environment variables from an environment file have lower precedence than those passed via the command-line or via the `environment` attribute in the `docker-compose.yml` file. +Environment variables from an environment file have lower precedence than those passed via the command-line or via the `environment` attribute in the `compose.yml` file. For more information, see [Environment variables precedence](envvars-precedence.md). diff --git a/compose/environment-variables/envvars-precedence.md b/compose/environment-variables/envvars-precedence.md index e547bf6e09..a10f684800 100644 --- a/compose/environment-variables/envvars-precedence.md +++ b/compose/environment-variables/envvars-precedence.md @@ -1,5 +1,5 @@ --- -title: Environment variables precedence +title: Environment variables precedence in Docker Compose description: Scenario overview illustrating how environment variables are resolved in Compose keywords: compose, environment, env file redirect_from: @@ -28,7 +28,7 @@ In the example below, we set a different value for the same environment variable $ cat ./Docker/api/api.env NODE_ENV=test -$ cat docker-compose.yml +$ cat compose.yml services: api: image: 'node:6-alpine' @@ -49,9 +49,10 @@ $ docker compose exec api node > Hard coding variables in container scripts > -> Executing a command within the container that unconditionally sets a variable value overrules any setting in your `docker-compose.yml` file. +> Executing a command within the container that unconditionally sets a variable value overrules any setting in your `compose.yml` file. > > For example, in a NodeJS project, if you have a `package.json` entry for `scripts.start`, such as `NODE_ENV=test` `node server.js`, any value set for `NODE_ENV` in your Compose file, is ignored when running `npm run start` within the container. +{: .important} ## Advanced example diff --git a/compose/environment-variables/envvars.md b/compose/environment-variables/envvars.md index c5d2bbb371..e36401da3d 100644 --- a/compose/environment-variables/envvars.md +++ b/compose/environment-variables/envvars.md @@ -1,7 +1,7 @@ --- description: Compose pre-defined environment variables keywords: fig, composition, compose, docker, orchestration, cli, reference -title: Change pre-defined environment variables +title: Change pre-defined environment variables in Docker Compose redirect_from: - /compose/reference/envvars/ --- @@ -105,7 +105,7 @@ When enabled, Compose performs path conversion from Windows-style to Unix-style Specifies a different path separator for items listed in `COMPOSE_FILE`. * Defaults to: - * On MacOS and Linux to `:`, + * On macOS and Linux to `:`, * On Windows to`;`. ### COMPOSE\_IGNORE\_ORPHANS diff --git a/compose/environment-variables/set-environment-variables.md b/compose/environment-variables/set-environment-variables.md index 49ac2c6217..f29e578c8b 100644 --- a/compose/environment-variables/set-environment-variables.md +++ b/compose/environment-variables/set-environment-variables.md @@ -26,7 +26,7 @@ Below is a simple example: $ cat .env TAG=v1.5 -$ cat docker-compose.yml +$ cat compose.yml services: web: image: "webapp:${TAG}" @@ -44,7 +44,7 @@ services: image: 'webapp:v1.5' ``` -The `.env` file should be placed at the root of the project directory next to your `docker-compose.yml` file. You can use an alternative path with one of the following methods: +The `.env` file should be placed at the root of the project directory next to your `compose.yaml` file. You can use an alternative path with one of the following methods: - The [`--file` option in the CLI](../reference/index.md#use--f-to-specify-name-and-path-of-one-or-more-compose-files) - The [`--env-file` option in the CLI](#substitute-with---env-file) - Using the [`env_file` attribute in the Compose file](../compose-file/05-services.md#env_file) @@ -56,6 +56,7 @@ For more information on formatting an environment file, see [Use an environment > Substitution from `.env` files is a Docker Compose CLI feature. > > It is not supported by Swarm when running `docker stack deploy`. +{: .important} ### Use the `environment` attribute @@ -122,6 +123,7 @@ If an environment variable is not set, Compose substitutes with an empty string. > **Important** > > Values set in the shell environment override those set in the `.env` file, the `environment` attribute, and the `env_file` attribute. For more information, see [Environment variable precedence](envvars-precedence.md). +{: .important} ## CLI @@ -135,7 +137,7 @@ The advantage of this method is that you can store the file anywhere and name it $ docker compose --env-file ./config/.env.dev up ``` -In the example below, there are two environment files, `.env` and `.env.dev`. Both have different values set for `TAG`. +In the following example, there are two environment files, `.env` and `.env.dev`. Both have different values set for `TAG`. ```console $ cat .env @@ -145,7 +147,7 @@ $ cat ./config/.env.dev TAG=v1.6 -$ cat docker-compose.yml +$ cat compose.yml services: web: image: "webapp:${TAG}" @@ -179,6 +181,7 @@ ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev > **Important** > > Values set in the shell environment override those set when using the `--env-file` argument in the CLI. For more information, see [Environment variable precedence](envvars-precedence.md) +{: .important} ### Set environment variables with `docker compose run --env` diff --git a/compose/features-uses.md b/compose/features-uses.md index d76b0110ee..ecd1877a1f 100644 --- a/compose/features-uses.md +++ b/compose/features-uses.md @@ -1,7 +1,7 @@ --- description: Key features and use cases of Docker Compose keywords: documentation, docs, docker, compose, orchestration, containers, uses, features -title: Key features and use cases +title: Key features and use cases of Docker Compose --- Using Compose is essentially a three-step process: @@ -9,12 +9,12 @@ Using Compose is essentially a three-step process: 1. Define your app's environment with a `Dockerfile` so it can be reproduced anywhere. -2. Define the services that make up your app in `docker-compose.yml` +2. Define the services that make up your app in a `compose.yaml` file so they can be run together in an isolated environment. -3. Run `docker compose up` and the Docker compose command starts and runs your entire app. You can alternatively run `docker-compose up` using Compose standalone(`docker-compose` binary). +3. Run `docker compose up` and the Docker compose command starts and runs your entire app. -A `docker-compose.yml` looks like this: +A `compose.yaml` looks like this: ```yaml services: @@ -42,13 +42,13 @@ For more information about the Compose file, see the Compose uses a project name to isolate environments from each other. You can make use of this project name in several different contexts: -* on a dev host, to create multiple copies of a single environment, such as when you want to run a stable copy for each feature branch of a project -* on a CI server, to keep builds from interfering with each other, you can set +* On a dev host, to create multiple copies of a single environment, such as when you want to run a stable copy for each feature branch of a project +* On a CI server, to keep builds from interfering with each other, you can set the project name to a unique build number -* on a shared host or dev host, to prevent different projects, which may use the +* On a shared host or dev host, to prevent different projects, which may use the same service names, from interfering with each other -The default project name is the basename of the project directory. You can set +The default project name is the base name of the project directory. You can set a custom project name by using the [`-p` command line option](reference/index.md) or the [`COMPOSE_PROJECT_NAME` environment variable](environment-variables/envvars.md#compose_project_name). @@ -56,7 +56,6 @@ a custom project name by using the The default project directory is the base directory of the Compose file. A custom value for it can be defined with the `--project-directory` command line option. - ### Preserves volume data when containers are created Compose preserves all volumes used by your services. When `docker compose up` @@ -68,7 +67,6 @@ If you use `docker compose` on a Windows machine, see [Environment variables](environment-variables/envvars.md) and adjust the necessary environment variables for your specific needs. - ### Only recreate containers that have changed Compose caches the configuration used to create a container. When you @@ -81,8 +79,6 @@ environment very quickly. Compose supports variables in the Compose file. You can use these variables to customize your composition for different environments, or different users. -See [Variable substitution](compose-file/compose-file-v3.md#variable-substitution) for more -details. You can extend a Compose file using the `extends` field or by creating multiple Compose files. For more details, see [Working with multiple Compose files](multiple-compose-files/index.md). @@ -127,4 +123,4 @@ Compose has traditionally been focused on development and testing workflows, but with each release we're making progress on more production-oriented features. For details on using production-oriented features, see -[compose in production](production.md) in this documentation. +[Compose in production](production.md). diff --git a/compose/file-watch.md b/compose/file-watch.md index 6f529abc3c..ca74011d84 100644 --- a/compose/file-watch.md +++ b/compose/file-watch.md @@ -1,18 +1,18 @@ --- description: Use File watch to automatically update running services as you work keywords: compose, file watch, experimental -title: Automatically update services with file watch +title: Automatically update services with file watch in Docker Compose --- -> **Note** +> **Experimental** > > The Compose file watch feature is currently [Experimental](../release-lifecycle.md). Use `watch` to automatically update your running Compose services as you edit and save your code. -For many projects, this enables a hands-off development workflow once Compose is running: services automatically update themselves as you save your work. +For many projects, this allows for a hands-off development workflow once Compose is running, as services automatically update themselves when you save your work. -You do not need to enable `watch` for all services in a Compose project. In some instances, only part of the project (e.g. Javascript frontend) might be suitable for automatic updates. +You don't need to switch on `watch` for all services in a Compose project. In some instances, only part of the project, for example the Javascript frontend, might be suitable for automatic updates. `watch` adheres to the following file path rules: * All paths are relative to the build context @@ -36,20 +36,21 @@ the `action`, additional fields might be accepted or required. If `action` is set to `sync`, Compose makes sure any changes made to files on your host automatically match with the corresponding files within the service container. -Sync is ideal for frameworks that support "Hot Reload" or equivalent functionality. +`sync` is ideal for frameworks that support "Hot Reload" or equivalent functionality. -More generally, sync rules can be used in place of bind mounts for many development use cases. +More generally, `sync` rules can be used in place of bind mounts for many development use cases. ##### Comparison to bind mounts + Compose also supports sharing a host directory inside service containers. Watch mode does not replace this functionality but exists as a companion specifically suited to developing in containers. Most importantly, watch mode allows for greater granularity than is practical with a bind mount. Watch rules allow ignoring specific files or entire directories within the watched tree. -For example, in a JavaScript project, ignoring the `node_modules/` directory has a couple benefits: -* Performance: file trees with many small files can cause high I/O load in some configurations -* Multi-platform: compiled artifacts cannot be shared if the host OS (e.g. Windows, macOS) or architecture (e.g. arm64) is different than the container +For example, in a JavaScript project, ignoring the `node_modules/` directory has two benefits: +* Performance. File trees with many small files can cause high I/O load in some configurations +* Multi-platform. Compiled artifacts cannot be shared if the host OS (e.g. Windows, macOS) or architecture (e.g. arm64) is different than the container -For example, in a Node.js project, it's not recommended to sync the `node_modules/` directory. Even though JavaScript is interpreted, npm packages can contain native code that is not portable across platforms. +For example, in a Node.js project, it's not recommended to sync the `node_modules/` directory. Even though JavaScript is interpreted, `npm` packages can contain native code that is not portable across platforms. #### Rebuild diff --git a/compose/gettingstarted.md b/compose/gettingstarted.md index b2d5edb3c6..c5e9778eb3 100644 --- a/compose/gettingstarted.md +++ b/compose/gettingstarted.md @@ -120,7 +120,7 @@ and the [Dockerfile reference](/engine/reference/builder/). ## Step 3: Define services in a Compose file -Create a file called `docker-compose.yml` in your project directory and paste +Create a file called `compose.yaml` in your project directory and paste the following: ```yaml @@ -214,7 +214,7 @@ image pulled from the Docker Hub registry. ## Step 5: Edit the Compose file to add a bind mount -Edit `docker-compose.yml` in your project directory to add a +Edit the `compose.yaml` file in your project directory to add a [bind mount](../storage/bind-mounts.md) for the `web` service: ```yaml @@ -269,7 +269,7 @@ Docker Desktop for Mac and Docker Desktop for Windows that uses [Linux containers](../desktop/faqs/windowsfaqs.md#how-do-i-switch-between-windows-and-linux-containers). For more information, see [File sharing on Docker for Mac](../desktop/settings/mac.md#file-sharing), -[File sharing on Docker for Windows](../desktop/settings/windows.md#file-sharing), +[File sharing on Docker for Windows](../desktop/settings/windows.md#file-sharing), [File sharing on Docker for Linux](../desktop/settings/linux.md#file-sharing). and the general examples on how to > [Manage data in containers](../storage/volumes.md). > @@ -281,7 +281,7 @@ need VirtualBox. ## Step 7: Update the application -Because the application code is now mounted into the container using a volume, +As the application code is now mounted into the container using a volume, you can make changes to its code and see the changes instantly, without having to rebuild the image. @@ -344,7 +344,7 @@ $ docker compose down --volumes ## Where to go next -- Next, try the [Sample apps with Compose](https://github.com/docker/awesome-compose) +- Try the [Sample apps with Compose](https://github.com/docker/awesome-compose) - [Explore the full list of Compose commands](reference/index.md) -- [Explore the Compose configuration file reference](compose-file/index.md) +- [Explore the Compose file reference](compose-file/index.md) - To learn more about volumes and bind mounts, see [Manage data in Docker](../storage/index.md) diff --git a/compose/gpu-support.md b/compose/gpu-support.md index e837a242bc..0d1b04cbd2 100644 --- a/compose/gpu-support.md +++ b/compose/gpu-support.md @@ -1,17 +1,17 @@ --- description: Understand GPU support in Docker Compose keywords: documentation, docs, docker, compose, GPU access, NVIDIA, samples -title: Enabling GPU access with Compose +title: Turn on GPU access with Docker 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 you install the [prerequisites](../config/containers/resource_constraints.md#gpu){: target="_blank" rel="noopener" class="_" } if you have not already done so. +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 you install the [prerequisites](../config/containers/resource_constraints.md#gpu){: target="_blank" rel="noopener" class="_" } if you haven't 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. For more information, see [Migrate to Compose V2](migrate.md){: target="_blank" rel="noopener" class="_" }. -### Enabling GPU access to service containers +## Enabling GPU access to service containers -GPUs are referenced in a `docker-compose.yml` file using the [device](compose-file/deploy.md#devices){:target="_blank" rel="noopener" class="_"} structure, within your services that need them. +GPUs are referenced in a `compose.yml` file using the [device](compose-file/deploy.md#devices){:target="_blank" rel="noopener" class="_"} attribute from the Compose Deploy specification, within your services that need them. This provides more granular control over a GPU reservation as custom values can be set for the following device properties: @@ -29,10 +29,9 @@ This provides more granular control over a GPU reservation as custom values can > `count` and `device_ids` are mutually exclusive. You must only define one field at a time. {: .important} -For more information on these properties, see the `deploy` section in the [Compose Specification](compose-file/deploy.md#devices){:target="_blank" rel="noopener" class="_"}. +For more information on these properties, see the `deploy` section in the [Compose Specification](compose-file/deploy.md#devices). - -#### Example of a Compose file for running a service with access to 1 GPU device: +### Example of a Compose file for running a service with access to 1 GPU device: ```yaml services: @@ -78,7 +77,7 @@ gpu_test_1 exited with code 0 ``` -On machines hosting multiple GPUs, `device_ids` field can be set to target specific GPU devices and `count` can be used to limit the number of GPU devices assigned to a service container. +On machines hosting multiple GPUs, the `device_ids` field can be set to target specific GPU devices and `count` can be used to limit the number of GPU devices assigned to a service container. You can use `count` or `device_ids` in each of your service definitions. An error is returned if you try to combine both, specify an invalid device ID, or use a value of count that’s higher than the number of GPUs in your system. @@ -109,9 +108,9 @@ $ nvidia-smi +-------------------------------+----------------------+----------------------+ ``` -### Access specific devices +## Access specific devices -To enable access only to GPU-0 and GPU-3 devices: +To allow access only to GPU-0 and GPU-3 devices: ```yaml services: diff --git a/compose/history.md b/compose/history.md index d3f07cfb15..dde79b3bf9 100644 --- a/compose/history.md +++ b/compose/history.md @@ -1,5 +1,5 @@ --- -title: History of Compose +title: History of Docker Compose description: History of Compose V1 and Compose YAML schema versioning keywords: compose, compose yaml, swarm, migration, compatibility --- @@ -13,9 +13,9 @@ target="_blank" rel="noopener" class="_"}. For users supporting projects originally targeting older versions of Compose, this can serve as a guide to understanding compatibility and the evolution of changes. ## Docker Compose CLI versioning -There are two major versions of Docker Compose, i.e. the command-line binary. +There are two major versions of Docker Compose, otherwise known as the command-line binary. -Compose V1 was first released in 2014, is written in Python, and is invoked as `docker-compose`. +Compose V1 was first released in 2014. It was written in Python, and is invoked as `docker-compose`. Typically, Compose V1 projects include a `version` field in YAML with values ranging from `2.0` to `3.8`. Compose V2 was announced in 2020, is written in Go, and is invoked as `docker compose`. @@ -34,12 +34,12 @@ Its usage is historical and files written in this format don't run with Compose Compose file format 2.x and 3.x were very similar to each other, but the latter introduced many new options targeted at Swarm deployments. -To address confusion around Compose CLI versioning, Compose file format versioning, and feature parity depending on whether Swarm mode was in use, file format 2.x and 3.x were merged into the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"}. -Unlike the prior file formats, the Compose specification is rolling and eliminates the `version` field in YAML. +To address confusion around Compose CLI versioning, Compose file format versioning, and feature parity depending on whether Swarm mode was in use, file format 2.x and 3.x were merged into the [Compose Specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"}. +Unlike the prior file formats, the Compose Specification is rolling and eliminates the `version` field in YAML. -Compose V2 uses the Compose specification for project definition. +Compose V2 uses the Compose Specification for project definition. The `version` field should be omitted and is ignored if present. -To make migration easier, Compose V2 has backwards compatibility for certain elements that have been deprecated or changed between Compose file format 2.x/3.x and the Compose specification. +To make migration easier, Compose V2 has backwards compatibility for certain elements that have been deprecated or changed between Compose file format 2.x/3.x and the Compose Specification. In these cases, a warning is logged when running Compose V2 commands, and you should update your YAML accordingly. Future versions of Compose may return an error in these cases. diff --git a/compose/index.md b/compose/index.md index bbc00880e2..017b0982af 100644 --- a/compose/index.md +++ b/compose/index.md @@ -1,7 +1,7 @@ --- description: Learn how to use Docker Compose to define and run multi-container applications with this detailed introduction to the tool. keywords: docker compose, docker-compose, docker compose command, docker compose files, docker compose documentation, using docker compose, compose container, docker compose service -title: Docker Compose overview +title: Overview of Docker Compose redirect_from: - /compose/cli-command/ - /compose/networking/swarm/ @@ -16,7 +16,7 @@ With Compose, you use a YAML file to configure your application's services. Then, with a single command, you create and start all the services from your configuration. -Compose works in all environments: production, staging, development, testing, as +Compose works in all environments; production, staging, development, testing, as well as CI workflows. It also has commands for managing the whole lifecycle of your application: * Start, stop, and rebuild services @@ -27,9 +27,9 @@ well as CI workflows. It also has commands for managing the whole lifecycle of y The key features of Compose that make it effective are: * [Have multiple isolated environments on a single host](features-uses.md#have-multiple-isolated-environments-on-a-single-host) -* [Preserves volume data when containers are created](features-uses.md#preserves-volume-data-when-containers-are-created) +* [Preserve volume data when containers are created](features-uses.md#preserves-volume-data-when-containers-are-created) * [Only recreate containers that have changed](features-uses.md#only-recreate-containers-that-have-changed) -* [Supports variables and moving a composition between environments](features-uses.md#supports-variables-and-moving-a-composition-between-environments) +* [Support variables and moving a composition between environments](features-uses.md#supports-variables-and-moving-a-composition-between-environments)
diff --git a/compose/install/index.md b/compose/install/index.md index 1d058b4fc2..0301e85b5b 100644 --- a/compose/install/index.md +++ b/compose/install/index.md @@ -1,7 +1,7 @@ --- description: Learn how to install Docker Compose. Compose is available natively on Docker Desktop, as a Docker Engine plugin, and as a standalone tool. keywords: install docker compose, docker compose install, install docker compose ubuntu, installing docker compose, docker compose download, docker compose not found, docker compose windows, how to install docker compose -title: Overview +title: Overview of installing Docker Compose toc_max: 3 redirect_from: - /compose/compose-desktop/ @@ -10,7 +10,7 @@ redirect_from: --- {% include compose-eol.md %} -This page contains summary information about the available options for getting Docker Compose. +This page contains summary information about the available options for installing Docker Compose. ## Installation scenarios @@ -24,7 +24,7 @@ Docker Desktop is available on: - [Mac](../../desktop/install/mac-install.md) - [Windows](../../desktop/install/windows-install.md) -If you have already installed Docker Desktop, you can check which version of Compose you have by selecting **About Docker Desktop** from the Docker menu ![whale menu](../../desktop/images/whale-x.svg){: .inline} +If you have already installed Docker Desktop, you can check which version of Compose you have by selecting **About Docker Desktop** from the Docker menu ![whale menu](../../desktop/images/whale-x.svg){: .inline}. ### Scenario two: Install the Compose plugin @@ -32,7 +32,7 @@ If you already have Docker Engine and Docker CLI installed, you can install the - [Using Docker's repository](linux.md#install-using-the-repository) - [Downloading and installing manually](linux.md#install-the-plugin-manually) ->Note +> **Important** > >This is only available on Linux {: .important} @@ -41,7 +41,7 @@ If you already have Docker Engine and Docker CLI installed, you can install the You can [install the Compose standalone](standalone.md) on Linux or on Windows Server. ->Note +> **Warning** > >This install scenario is not recommended and is only supported for backward compatibility purposes. -{: .important} +{: .warning} diff --git a/compose/install/linux.md b/compose/install/linux.md index cce7e91dd6..7f1f7e8039 100644 --- a/compose/install/linux.md +++ b/compose/install/linux.md @@ -53,7 +53,7 @@ For Compose standalone, see [Install Compose Standalone](standalone.md). Docker Compose version vN.N.N ``` -Where `vN.N.N` is placeholder text standing in for the latest version. + Where `vN.N.N` is placeholder text standing in for the latest version. ### Update Compose diff --git a/compose/install/standalone.md b/compose/install/standalone.md index 72cf60c973..cc056f3169 100644 --- a/compose/install/standalone.md +++ b/compose/install/standalone.md @@ -23,14 +23,15 @@ On this page you can find instructions on how to install Compose standalone on L 2. Apply executable permissions to the standalone binary in the target path for the installation. 3. Test and execute compose commands using `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 -> ``` + > **Tip** + > + > 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 + > ``` + {: .tip} ### On Windows Server @@ -38,7 +39,7 @@ Follow these instructions if you are running the Docker daemon and client direct on Microsoft Windows Server and want to install Docker Compose. 1. Run PowerShell as an administrator. - When asked if you want to allow this app to make changes to your device, click **Yes** in order to proceed with the installation. + When asked if you want to allow this app to make changes to your device, select **Yes** in order to proceed with the installation. 2. GitHub now requires TLS1.2. In PowerShell, run the following: diff --git a/compose/install/uninstall.md b/compose/install/uninstall.md index b4c55c1efb..684273d7ad 100644 --- a/compose/install/uninstall.md +++ b/compose/install/uninstall.md @@ -7,7 +7,7 @@ title: Uninstall Docker Compose Uninstalling Docker Compose depends on the method you have used to install Docker Compose. On this page you can find specific instructions to uninstall Docker Compose. -### Uninstalling Docker Desktop +## Uninstalling Docker Desktop If you want to uninstall Compose and you have installed Docker Desktop, see [Uninstall Docker Desktop](../../desktop/uninstall.md). @@ -15,44 +15,45 @@ If you want to uninstall Compose and you have installed Docker Desktop, see [Uni > > Unless you have other Docker instances installed on that specific environment, you would be removing Docker altogether by uninstalling the Desktop. -### Uninstalling the Docker Compose CLI plugin +## Uninstalling the Docker Compose CLI plugin To remove the Compose CLI plugin, run: Ubuntu, Debian: -```console -$ sudo apt-get remove docker-compose-plugin -``` + ```console + $ sudo apt-get remove docker-compose-plugin + ``` RPM-based distros: -```console -$ sudo yum remove docker-compose-plugin -``` + ```console + $ sudo yum remove docker-compose-plugin + ``` -#### Manually installed +### Manually installed If you used `curl` to install Compose CLI plugin, to uninstall it, run: -```console -$ rm $DOCKER_CONFIG/cli-plugins/docker-compose -``` + ```console + $ rm $DOCKER_CONFIG/cli-plugins/docker-compose + ``` -#### Remove for all users +### Remove for all users Or, if you have installed Compose for all users, run: -```console -$ rm /usr/local/lib/docker/cli-plugins/docker-compose -``` + ```console + $ rm /usr/local/lib/docker/cli-plugins/docker-compose + ``` > Got a **Permission denied** error? > > If you get a **Permission denied** error using either of the above > methods, you do not have the permissions allowing you to remove > `docker-compose`. To force the removal, prepend `sudo` to either of the above instructions and run it again. +{: .tip} -#### Inspect the location of the Compose CLI plugin +### Inspect the location of the Compose CLI plugin To check where Compose is installed, use: diff --git a/compose/networking.md b/compose/networking.md index 758c559436..4711f0ce24 100644 --- a/compose/networking.md +++ b/compose/networking.md @@ -6,7 +6,7 @@ title: Networking in Compose {% include compose-eol.md %} By default Compose sets up a single -[network](../engine/reference/commandline/network_create.md){: target="_blank" rel="noopener" class="_" } for your app. Each +[network](../engine/reference/commandline/network_create.md) for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by them at a hostname identical to the container name. @@ -15,10 +15,10 @@ identical to the container name. > > Your app's network is given a name based on the "project name", > which is based on the name of the directory it lives in. You can override the -> project name with either the [`--project-name` flag](reference/index.md){: target="_blank" rel="noopener" class="_" } -> or the [`COMPOSE_PROJECT_NAME` environment variable](environment-variables/envvars.md#compose_project_name){: target="_blank" rel="noopener" class="_" }. +> project name with either the [`--project-name` flag](reference/index.md){ +> or the [`COMPOSE_PROJECT_NAME` environment variable](environment-variables/envvars.md#compose_project_name). -For example, suppose your app is in a directory called `myapp`, and your `docker-compose.yml` looks like this: +For example, suppose your app is in a directory called `myapp`, and your `compose.yml` looks like this: ```yaml services: @@ -40,7 +40,6 @@ When you run `docker compose up`, the following happens: 3. A container is created using `db`'s configuration. It joins the network `myapp_default` under the name `db`. - Each container can now look up the hostname `web` or `db` and get back the appropriate container's IP address. For example, `web`'s application code could connect to the URL `postgres://db:5432` and start @@ -181,5 +180,5 @@ Instead of attempting to create a network called `[projectname]_default`, Compos For full details of the network configuration options available, see the following references: -- [Top-level `networks` key](compose-file/06-networks.md) -- [Service-level `networks` key](compose-file/05-services.md#networks) +- [Top-level `networks` element](compose-file/06-networks.md) +- [Service-level `networks` attribute](compose-file/05-services.md#networks) diff --git a/compose/production.md b/compose/production.md index 2ac739f988..51879e360e 100644 --- a/compose/production.md +++ b/compose/production.md @@ -23,19 +23,19 @@ production. These changes might include: - Binding to different ports on the host - Setting environment variables differently, such as reducing the verbosity of logging, or to specify settings for external services such as an email server -- Specifying a restart policy like [`restart: always`](compose-file/05-services.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime +- Specifying a restart policy like [`restart: always`](compose-file/05-services.md#restart)to avoid downtime - Adding extra services such as a log aggregator -For this reason, consider defining an additional Compose file, say +For this reason, consider defining an additional Compose file, for example `production.yml`, which specifies production-appropriate configuration. This configuration file only needs to include the changes you want to make from the original Compose file. The additional Compose file -is then applied over the original `docker-compose.yml` to create a new configuration. +is then applied over the original `compose.yml` to create a new configuration. Once you have a second configuration file, you can use it with the `-f` option: ```console -$ docker compose -f docker-compose.yml -f production.yml up -d +$ docker compose -f compose.yml -f production.yml up -d ``` See [Using multiple compose files](multiple-compose-files/index.md) for a more complete example, and other options. @@ -63,9 +63,3 @@ appropriately. See also [Compose CLI environment variables](environment-variable Once you've set up your environment variables, all the normal `docker compose` commands work with no further configuration. - -## What's new? - -- [Command line reference](reference/index.md) -- [Compose file reference](compose-file/index.md) -- [Sample apps with Compose](samples-for-compose.md) diff --git a/compose/profiles.md b/compose/profiles.md index 339140256b..14a64ebd3f 100644 --- a/compose/profiles.md +++ b/compose/profiles.md @@ -6,12 +6,12 @@ keywords: cli, compose, profile, profiles reference {% include compose-eol.md %} Profiles help you adjust the Compose application model for various uses and -environments by selectively enabling services. +environments by selectively starting services. This is achieved by assigning each service to zero or more profiles. If unassigned, the service is always started but if assigned, it is only started if the profile is activated. -This allows you to define additional services in a single `docker-compose.yml` file +This allows you to define additional services in a single `compose.yml` file that should only be started in specific scenarios, for example for debugging or development tasks. @@ -56,9 +56,9 @@ Valid profiles names follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`. > they are always enabled and automatically started. {: .tip} -## Enable profiles +## Start specific profiles -To enable profiles supply the `--profile` [command-line option](reference/index.md) or +To start a specific profile supply the `--profile` [command-line option](reference/index.md) or use the [`COMPOSE_PROFILES` environment variable](environment-variables/envvars.md#compose_profiles): ```console @@ -69,10 +69,10 @@ $ COMPOSE_PROFILES=debug docker compose up ``` The above commands would both start your application with the `debug` profile enabled. -In the example, `docker-compose.yml` file above, this starts the services `backend`, +In the example, `compose.yml` file above, this starts the services `backend`, `db` and `phpmyadmin`. -### Enable multiple profiles +### Start multiple profiles Multiple profiles can be specified by passing multiple `--profile` flags or a comma-separated list for the `COMPOSE_PROFILES` environment variable: @@ -85,10 +85,10 @@ $ docker compose --profile frontend --profile debug up $ COMPOSE_PROFILES=frontend,debug docker compose up ``` -## Auto-enabling profiles and dependency resolution +## Auto-starting profiles and dependency resolution When a service with assigned `profiles` is explicitly targeted on the command -line its profiles are enabled automatically so you don't need to enable them +line its profiles are started automatically so you don't need to start them manually. This can be used for one-off services and debugging tools. As an example consider the following configuration: @@ -118,12 +118,12 @@ $ docker compose up -d $ docker compose run db-migrations ``` -But keep in mind that `docker compose` only automatically enables the +But keep in mind that `docker compose` only automatically starts the profiles of the services on the command line and not of any dependencies. This means that any other services the targeted service `depends_on` should either: - Share a common profile -- Always be enabled, by omitting `profiles` or having a matching profile enabled explicitly +- Always be started, by omitting `profiles` or having a matching profile started explicitly ```yaml services: @@ -159,7 +159,7 @@ $ docker compose up -d mock-backend $ docker compose up phpmyadmin ``` -Although targeting `phpmyadmin` automatically enables the profiles `debug`, it doesn't automatically enable the profiles required by `db` which is `dev`. +Although targeting `phpmyadmin` automatically starts the profiles `debug`, it doesn't automatically start the profiles required by `db` which is `dev`. To fix this you either have to add the `debug` profile to the `db` service: @@ -169,15 +169,14 @@ db: profiles: ["debug", "dev"] ``` -or enable a profile of `db` explicitly: +or start a profile of `db` explicitly: ```console -# Profiles "debug" is enabled automatically by targeting phpmyadmin +# Profiles "debug" is started automatically by targeting phpmyadmin $ docker compose --profile dev up phpmyadmin $ COMPOSE_PROFILES=dev docker compose up phpmyadmin ``` - ## Reference information [`profiles`](compose-file/05-services.md#profiles) diff --git a/compose/samples-for-compose.md b/compose/samples-for-compose.md index 72a99bbe6d..3aba2be936 100644 --- a/compose/samples-for-compose.md +++ b/compose/samples-for-compose.md @@ -12,13 +12,13 @@ if you have not already done so. The samples should help you to: -- define services based on Docker images using - [Compose files](compose-file/index.md): `docker-compose.yml` and +- Define services based on Docker images using + [Compose files](compose-file/index.md): `compose.yml` and `docker-stack.yml` -- understand the relationship between `docker-compose.yml` and +- Understand the relationship between `compose.yml` and [Dockerfiles](/engine/reference/builder/) -- learn how to make calls to your application services from Compose files -- learn how to deploy applications and services to a [swarm](../engine/swarm/index.md) +- Learn how to make calls to your application services from Compose files +- Learn how to deploy applications and services to a [swarm](../engine/swarm/index.md) ## Samples tailored to demo Compose diff --git a/compose/use-secrets.md b/compose/use-secrets.md index 86225ca423..553db8bb8c 100644 --- a/compose/use-secrets.md +++ b/compose/use-secrets.md @@ -10,7 +10,7 @@ Docker Compose provides a way for you to use secrets without having to use envir ## Use secrets -Getting a secret into a container is a two-step process. First, define the secret using the [top-level secrets attribute in your Compose file](compose-file/09-secrets.md). Next, update your service definitions to reference the secrets they require with the [secrets attribute](compose-file/05-services.md#secrets). Compose grants access to secrets on a per-service basis. +Getting a secret into a container is a two-step process. First, define the secret using the [top-level secrets element in your Compose file](compose-file/09-secrets.md). Next, update your service definitions to reference the secrets they require with the [secrets attribute](compose-file/05-services.md#secrets). Compose grants access to secrets on a per-service basis. Unlike the other methods, this permits granular access control within a service container via standard filesystem permissions.