From 7a5e17648c2c7e8d55b64c55a0de1c0be997542e Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 2 Jul 2025 11:28:16 +0100 Subject: [PATCH 1/3] compose freshness --- .../how-tos/environment-variables/_index.md | 5 +- .../envvars-precedence.md | 47 ++++---- .../how-tos/environment-variables/envvars.md | 100 ++++++++++-------- .../variable-interpolation.md | 15 +++ 4 files changed, 98 insertions(+), 69 deletions(-) diff --git a/content/manuals/compose/how-tos/environment-variables/_index.md b/content/manuals/compose/how-tos/environment-variables/_index.md index a2ddb86929a7..0775edc2665d 100644 --- a/content/manuals/compose/how-tos/environment-variables/_index.md +++ b/content/manuals/compose/how-tos/environment-variables/_index.md @@ -2,14 +2,13 @@ title: Environment variables in Compose linkTitle: Use environment variables weight: 40 -description: Explainer on the ways to set, use and manage environment variables in - Compose +description: Explains how to set, use, and manage environment variables in Docker Compose. keywords: compose, orchestration, environment, env file aliases: - /compose/environment-variables/ --- -By leveraging environment variables and interpolation in Docker Compose, you can create versatile and reusable configurations, making your Dockerized applications easier to manage and deploy across different environments. +Environment variables and interpolation in Docker Compose help you create reusable, flexible configurations. This makes Dockerized applications easier to manage and deploy across environments. > [!TIP] > diff --git a/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md b/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md index f5e14549472d..8197d8f18f7a 100644 --- a/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md +++ b/content/manuals/compose/how-tos/environment-variables/envvars-precedence.md @@ -12,7 +12,7 @@ aliases: When the same environment variable is set in multiple sources, Docker Compose follows a precedence rule to determine the value for that variable in your container's environment. -This page contains information on the level of precedence each method of setting environmental variables takes. +This page explains how Docker Compose determines the final value of an environment variable when it's defined in multiple locations. The order of precedence (highest to lowest) is as follows: 1. Set using [`docker compose run -e` in the CLI](set-environment-variables.md#set-environment-variables-with-docker-compose-run---env). @@ -59,25 +59,25 @@ The columns `Host OS environment` and `.env` file is listed only for illustratio Each row represents a combination of contexts where `VALUE` is set, substituted, or both. The **Result** column indicates the final value for `VALUE` in each scenario. -| # | `docker compose run` | `environment` attribute | `env_file` attribute | Image `ENV` | `Host OS` environment | `.env` file | | Result | -|:--:|:----------------:|:-------------------------------:|:----------------------:|:------------:|:-----------------------:|:-----------------:|:---:|:----------:| -| 1 | - | - | - | - | `VALUE=1.4` | `VALUE=1.3` || - | -| 2 | - | - | `VALUE=1.6` | `VALUE=1.5` | `VALUE=1.4` | - ||**`VALUE=1.6`** | -| 3 | - | `VALUE=1.7` | - | `VALUE=1.5` | `VALUE=1.4` | - ||**`VALUE=1.7`** | -| 4 | - | - | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.5`** | -| 5 |`--env VALUE=1.8` | - | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.8`** | -| 6 |`--env VALUE` | - | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.4`** | -| 7 |`--env VALUE` | - | - | `VALUE=1.5` | - | `VALUE=1.3` ||**`VALUE=1.3`** | -| 8 | - | - | `VALUE` | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.4`** | -| 9 | - | - | `VALUE` | `VALUE=1.5` | - | `VALUE=1.3` ||**`VALUE=1.3`** | -| 10 | - | `VALUE` | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.4`** | -| 11 | - | `VALUE` | - | `VALUE=1.5` | - | `VALUE=1.3` ||**`VALUE=1.3`** | -| 12 |`--env VALUE` | `VALUE=1.7` | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.4`** | -| 13 |`--env VALUE=1.8` | `VALUE=1.7` | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.8`** | -| 14 |`--env VALUE=1.8` | - | `VALUE=1.6` | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.8`** | -| 15 |`--env VALUE=1.8` | `VALUE=1.7` | `VALUE=1.6` | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` ||**`VALUE=1.8`** | - -### Result explanation +| # | `docker compose run` | `environment` attribute | `env_file` attribute | Image `ENV` | `Host OS` environment | `.env` file | Result | +|:--:|:----------------:|:-------------------------------:|:----------------------:|:------------:|:-----------------------:|:-----------------:|:----------:| +| 1 | - | - | - | - | `VALUE=1.4` | `VALUE=1.3` | - | +| 2 | - | - | `VALUE=1.6` | `VALUE=1.5` | `VALUE=1.4` | - |**`VALUE=1.6`** | +| 3 | - | `VALUE=1.7` | - | `VALUE=1.5` | `VALUE=1.4` | - |**`VALUE=1.7`** | +| 4 | - | - | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.5`** | +| 5 |`--env VALUE=1.8` | - | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.8`** | +| 6 |`--env VALUE` | - | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.4`** | +| 7 |`--env VALUE` | - | - | `VALUE=1.5` | - | `VALUE=1.3` |**`VALUE=1.3`** | +| 8 | - | - | `VALUE` | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.4`** | +| 9 | - | - | `VALUE` | `VALUE=1.5` | - | `VALUE=1.3` |**`VALUE=1.3`** | +| 10 | - | `VALUE` | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.4`** | +| 11 | - | `VALUE` | - | `VALUE=1.5` | - | `VALUE=1.3` |**`VALUE=1.3`** | +| 12 |`--env VALUE` | `VALUE=1.7` | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.4`** | +| 13 |`--env VALUE=1.8` | `VALUE=1.7` | - | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.8`** | +| 14 |`--env VALUE=1.8` | - | `VALUE=1.6` | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.8`** | +| 15 |`--env VALUE=1.8` | `VALUE=1.7` | `VALUE=1.6` | `VALUE=1.5` | `VALUE=1.4` | `VALUE=1.3` |**`VALUE=1.8`** | + +### Understanding precedence results Result 1: The local environment takes precedence, but the Compose file is not set to replicate this inside the container, so no such variable is set. @@ -87,7 +87,7 @@ Result 3: The `environment` attribute in the Compose file defines an explicit va Result 4: The image's `ENV` directive declares the variable `VALUE`, and since the Compose file is not set to override this value, this variable is defined by image -Result 5: The `docker compose run` command has the `--env` flag set which an explicit value, and overrides the value set by the image. +Result 5: The `docker compose run` command has the `--env` flag set with an explicit value, and overrides the value set by the image. Result 6: The `docker compose run` command has the `--env` flag set to replicate the value from the environment. Host OS value takes precedence and is replicated into the container's environment. @@ -104,3 +104,8 @@ Result 11: The `environment` attribute in the Compose file is set to replicate ` Result 12: The `--env` flag has higher precedence than the `environment` and `env_file` attributes and is to set to replicate `VALUE` from the local environment. Host OS value takes precedence and is replicated into the container's environment. Results 13 to 15: The `--env` flag has higher precedence than the `environment` and `env_file` attributes and so sets the value. + +## Next steps + +- [Set environment variables in Compose](set-environment-variables.md) +- [Use variable interpolation in Compose files](variable-interpolation.md) diff --git a/content/manuals/compose/how-tos/environment-variables/envvars.md b/content/manuals/compose/how-tos/environment-variables/envvars.md index 430a719f509d..f17aa2b9f2cb 100644 --- a/content/manuals/compose/how-tos/environment-variables/envvars.md +++ b/content/manuals/compose/how-tos/environment-variables/envvars.md @@ -1,7 +1,7 @@ --- description: Compose pre-defined environment variables -keywords: fig, composition, compose, docker, orchestration, cli, reference -title: Set or change pre-defined environment variables in Docker Compose +keywords: fig, composition, compose, docker, orchestration, cli, reference, compose environment configuration, docker env variables +title: Configure pre-defined environment variables in Docker Compose linkTitle: Pre-defined environment variables weight: 30 aliases: @@ -9,9 +9,9 @@ aliases: - /compose/environment-variables/envvars/ --- -Compose already comes with pre-defined environment variables. It also inherits common Docker CLI environment variables, such as `DOCKER_HOST` and `DOCKER_CONTEXT`. See [Docker CLI environment variable reference](/reference/cli/docker/#environment-variables) for details. +Docker Compose includes several pre-defined environment variables. It also inherits common Docker CLI environment variables, such as `DOCKER_HOST` and `DOCKER_CONTEXT`. See [Docker CLI environment variable reference](/reference/cli/docker/#environment-variables) for details. -This page contains information on how you can set or change the following pre-defined environment variables if you need to: +This page explains how to set or change the following pre-defined environment variables: - `COMPOSE_PROJECT_NAME` - `COMPOSE_FILE` @@ -30,16 +30,19 @@ This page contains information on how you can set or change the following pre-de ## Methods to override -You can set or change the pre-defined environment variables: -- With an [`.env` file located in your working directory](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) -- From the command line -- From your [shell](variable-interpolation.md#substitute-from-the-shell) +| Method | Description | +| ----------- | -------------------------------------------- | +| [`.env` file](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) | Located in the working directory. | +| [Shell](variable-interpolation.md#substitute-from-the-shell) | Defined in the host operating system shell. | +| CLI | Passed with `--env` or `-e` flag at runtime. | When changing or setting any environment variables, be aware of [Environment variable precedence](envvars-precedence.md). -## Configure +## Configuration details -### COMPOSE\_PROJECT\_NAME +### Project and file configuration + +#### COMPOSE\_PROJECT\_NAME Sets the project name. This value is prepended along with the service name to the container's name on startup. @@ -64,7 +67,7 @@ constraint, you must use one of the other mechanisms. See also the [command-line options overview](/reference/cli/docker/compose/_index.md#command-options-overview-and-help) and [using `-p` to specify a project name](/reference/cli/docker/compose/_index.md#use--p-to-specify-a-project-name). -### COMPOSE\_FILE +#### COMPOSE\_FILE Specifies the path to a Compose file. Specifying multiple Compose files is supported. @@ -81,7 +84,7 @@ Specifies the path to a Compose file. Specifying multiple Compose files is suppo See also the [command-line options overview](/reference/cli/docker/compose/_index.md#command-options-overview-and-help) and [using `-f` to specify name and path of one or more Compose files](/reference/cli/docker/compose/_index.md#use--f-to-specify-the-name-and-path-of-one-or-more-compose-files). -### COMPOSE\_PROFILES +#### COMPOSE\_PROFILES Specifies one or more profiles to be enabled when `docker compose up` is run. @@ -100,7 +103,29 @@ COMPOSE_PROFILES=frontend,debug See also [Using profiles with Compose](../profiles.md) and the [`--profile` command-line option](/reference/cli/docker/compose/_index.md#use-profiles-to-enable-optional-services). -### COMPOSE\_CONVERT\_WINDOWS\_PATHS +#### COMPOSE\_PATH\_SEPARATOR + +Specifies a different path separator for items listed in `COMPOSE_FILE`. + +- Defaults to: + - On macOS and Linux to `:` + - On Windows to`;` + +#### COMPOSE\_ENV\_FILES + +Specifies which environment files Compose should use if `--env-file` isn't used. + +When using multiple environment files, use a comma as a separator. For example: + +```console +COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2 +``` + +If `COMPOSE_ENV_FILES` is not set, and you don't provide `--env-file` in the CLI, Docker Compose uses the default behavior, which is to look for an `.env` file in the project directory. + +### Environment handling and container lifecycle + +#### COMPOSE\_CONVERT\_WINDOWS\_PATHS When enabled, Compose performs path conversion from Windows-style to Unix-style in volume definitions. @@ -109,15 +134,7 @@ When enabled, Compose performs path conversion from Windows-style to Unix-style - `false` or `0`, to disable - Defaults to: `0` -### COMPOSE\_PATH\_SEPARATOR - -Specifies a different path separator for items listed in `COMPOSE_FILE`. - -- Defaults to: - - On macOS and Linux to `:` - - On Windows to`;` - -### COMPOSE\_IGNORE\_ORPHANS +#### COMPOSE\_IGNORE\_ORPHANS When enabled, Compose doesn't try to detect orphaned containers for the project. @@ -126,7 +143,7 @@ When enabled, Compose doesn't try to detect orphaned containers for the project. - `false` or `0`, to disable - Defaults to: `0` -### COMPOSE\_REMOVE\_ORPHANS +#### COMPOSE\_REMOVE\_ORPHANS When enabled, Compose automatically removes orphaned containers when updating a service or stack. Orphaned containers are those that were created by a previous configuration but are no longer defined in the current `compose.yaml` file. @@ -135,11 +152,13 @@ When enabled, Compose automatically removes orphaned containers when updating a - `false` or `0`, to disable automatic removal. Compose displays a warning about orphaned containers instead. - Defaults to: `0` -### COMPOSE\_PARALLEL\_LIMIT +#### COMPOSE\_PARALLEL\_LIMIT Specifies the maximum level of parallelism for concurrent engine calls. -### COMPOSE\_ANSI +### Output + +#### COMPOSE\_ANSI Specifies when to print ANSI control characters. @@ -149,7 +168,7 @@ Specifies when to print ANSI control characters. - `always` or `0`, use TTY mode - Defaults to: `auto` -### COMPOSE\_STATUS\_STDOUT +#### COMPOSE\_STATUS\_STDOUT When enabled, Compose writes its internal status and progress messages to `stdout` instead of `stderr`. The default value is false to clearly separate the output streams between Compose messages and your container's logs. @@ -159,19 +178,18 @@ The default value is false to clearly separate the output streams between Compos - `false` or `0`, to disable - Defaults to: `0` -### COMPOSE\_ENV\_FILES +#### COMPOSE\_PROGRESS -Lets you specify which environment files Compose should use if `--env-file` isn't used. +{{< summary-bar feature_name="Compose progress" >}} -When using multiple environment files, use a comma as a separator. For example: +Defines the type of progress output, if `--progress` isn't used. -```console -COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2 -``` +Supported values are `auto`, `tty`, `plain`, `json`, and `quiet`. +Default is `auto`. -If `COMPOSE_ENV_FILES` is not set, and you don't provide `--env-file` in the CLI, Docker Compose uses the default behavior, which is to look for an `.env` file in the project directory. +### User experience -### COMPOSE\_MENU +#### COMPOSE\_MENU {{< summary-bar feature_name="Compose menu" >}} @@ -182,26 +200,17 @@ When enabled, Compose displays a navigation menu where you can choose to open th - `false` or `0`, to disable - Defaults to: `1` if you obtained Docker Compose through Docker Desktop, otherwise the default is `0` -### COMPOSE\_EXPERIMENTAL +#### COMPOSE\_EXPERIMENTAL {{< summary-bar feature_name="Compose experimental" >}} -This is an opt-out variable. When turned off it deactivates the experimental features such as the navigation menu or [Synchronized file shares](/manuals/desktop/features/synchronized-file-sharing.md). +This is an opt-out variable. When turned off it deactivates the experimental features. - Supported values: - `true` or `1`, to enable - `false` or `0`, to disable - Defaults to: `1` -### COMPOSE\_PROGRESS - -{{< summary-bar feature_name="Compose progress" >}} - -Defines the type of progress output, if `--progress` isn't used. - -Supported values are `auto`, `tty`, `plain`, `json`, and `quiet`. -Default is `auto`. - ## Unsupported in Compose V2 The following environment variables have no effect in Compose V2. @@ -216,3 +225,4 @@ For more information, see [Migrate to Compose V2](/manuals/compose/releases/migr - `COMPOSE_INTERACTIVE_NO_CLI` - `COMPOSE_DOCKER_CLI_BUILD` Use `DOCKER_BUILDKIT` to select between BuildKit and the classic builder. If `DOCKER_BUILDKIT=0` then `docker compose build` uses the classic builder to build images. + diff --git a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md index bc2461c78ed5..04b185534697 100644 --- a/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md +++ b/content/manuals/compose/how-tos/environment-variables/variable-interpolation.md @@ -149,6 +149,21 @@ The following syntax rules apply to environment files: - `VAR="some\tvalue"` -> `some value` - `VAR='some\tvalue'` -> `some\tvalue` - `VAR=some\tvalue` -> `some\tvalue` +- Single-quoted values can span multiple lines. Example: + + ```yaml + KEY='SOME + VALUE' + ``` + + If you then run `docker compose config`, you'll see: + + ```yaml + environment: + KEY: |- + SOME + VALUE + ``` ### Substitute with `--env-file` From 68e67f13a3f2815477b161fb89bb917a4af34204 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 2 Jul 2025 11:47:10 +0100 Subject: [PATCH 2/3] build images --- content/manuals/compose/how-tos/dependent-images.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/manuals/compose/how-tos/dependent-images.md b/content/manuals/compose/how-tos/dependent-images.md index d62668548acf..ba9e44ff31e2 100644 --- a/content/manuals/compose/how-tos/dependent-images.md +++ b/content/manuals/compose/how-tos/dependent-images.md @@ -8,7 +8,7 @@ weight: 50 {{< summary-bar feature_name="Compose dependent images" >}} To reduce push/pull time and image weight, a common practice for Compose applications is to have services -share base layers as much as possible. You will typically select the same operating system base image for +share base layers as much as possible. You typically select the same operating system base image for all services. But you can also get one step further by sharing image layers when your images share the same system packages. The challenge to address is then to avoid repeating the exact same Dockerfile instruction in all services. @@ -162,3 +162,8 @@ Bake can also be selected as the default builder by editing your `$HOME/.docker/ ... } ``` + +## Additional resources + +- [Docker Compose build reference](/reference/cli/docker/compose/build.md) +- [Learn about multi-stage Dockerfiles](/manuals/build/building/multi-stage.md) From d4735eba057c485b9d27579b8f44e8605e73d6ba Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 2 Jul 2025 11:55:38 +0100 Subject: [PATCH 3/3] secrets --- content/manuals/compose/how-tos/file-watch.md | 4 ---- content/manuals/compose/how-tos/use-secrets.md | 10 +++++----- 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/content/manuals/compose/how-tos/file-watch.md b/content/manuals/compose/how-tos/file-watch.md index e59386d267eb..a9463df9683a 100644 --- a/content/manuals/compose/how-tos/file-watch.md +++ b/content/manuals/compose/how-tos/file-watch.md @@ -207,10 +207,6 @@ This setup demonstrates how to use the `sync+restart` action in Docker Compose t > or [local setup for Docker docs](https://github.com/docker/docs/blob/main/CONTRIBUTING.md) > for a demonstration of Compose `watch`. -## Feedback - -We are actively looking for feedback on this feature. Give feedback or report any bugs you may find in the [Compose Specification repository](https://github.com/compose-spec/compose-spec/pull/253). - ## Reference - [Compose Develop Specification](/reference/compose-file/develop.md) diff --git a/content/manuals/compose/how-tos/use-secrets.md b/content/manuals/compose/how-tos/use-secrets.md index 63680e6ac352..d2c6352c3be5 100644 --- a/content/manuals/compose/how-tos/use-secrets.md +++ b/content/manuals/compose/how-tos/use-secrets.md @@ -1,9 +1,9 @@ --- -title: How to use secrets in Docker Compose +title: Manage secrets securely in Docker Compose linkTitle: Secrets in Compose weight: 60 -description: How to use secrets in Compose and their benefits -keywords: secrets, compose, security, environment variables +description: Learn how to securely manage runtime and build-time secrets in Docker Compose. +keywords: secrets, compose, security, environment variables, docker secrets, secure Docker builds, sensitive data in containers tags: [Secrets] aliases: - /compose/use-secrets/ @@ -25,7 +25,7 @@ Unlike the other methods, this permits granular access control within a service ## Examples -### Simple +### Single-service secret injection In the following example, the frontend service is given access to the `my_secret` secret. In the container, `/run/secrets/my_secret` is set to the contents of the file `./my_secret.txt`. @@ -40,7 +40,7 @@ secrets: file: ./my_secret.txt ``` -### Advanced +### Multi-service secret sharing and password management ```yaml services: