diff --git a/content/compose/environment-variables/variable-interpolation.md b/content/compose/environment-variables/variable-interpolation.md index 7df33c22b0..d81116f33c 100644 --- a/content/compose/environment-variables/variable-interpolation.md +++ b/content/compose/environment-variables/variable-interpolation.md @@ -60,7 +60,7 @@ Docker Compose can interpolate variables into your Compose file from multiple so ### `.env` file -An `.env` file in Docker Compose is a text file used to define variables that should be made available to Docker containers when running `docker compose up`. This file typically contains key-value pairs of variables, and it lets you centralize and manage configuration in one place. The `.env` file is useful if you have multiple variables you need to store. +An `.env` file in Docker Compose is a text file used to define variables that should be made available for interpolation when running `docker compose up`. This file typically contains key-value pairs of variables, and it lets you centralize and manage configuration in one place. The `.env` file is useful if you have multiple variables you need to store. The `.env` file is the default method for setting variables. The `.env` file should be placed at the root of the project directory next to your `compose.yaml` file. For more information on formatting an environment file, see [Syntax for environment files](#env-file). @@ -85,9 +85,19 @@ services: DEBUG: "true" ``` +When same variable is declare by multiple sources, precedence applies as: + +1. Variables from shell environment +2. If `--env-file` is not set, variables set by an `.env` file in local working directory (`PWD`) +3. Variables from file set by `--env-file` or an `.env` file in project directory + +You can check variables and values used by Compose to interpolate the compose model by running `docker compose config --environment`. + + + #### Additional information -- If you define an environment variable in your `.env` file, you can reference it directly in your `compose.yml` with the [`environment` attribute](../compose-file/05-services.md#environment). For example, if your `.env` file contains the environment variable `DEBUG=1` and your `compose.yml` file looks like this: +- If you define a variable in your `.env` file, you can reference it directly in your `compose.yml` with the [`environment` attribute](../compose-file/05-services.md#environment). For example, if your `.env` file contains the environment variable `DEBUG=1` and your `compose.yml` file looks like this: ```yaml services: webapp: @@ -113,6 +123,7 @@ services: > It is not supported by Swarm when running `docker stack deploy`. { .important } + #### `.env` file syntax The following syntax rules apply to environment files: @@ -211,3 +222,33 @@ If an environment variable is not set, Compose substitutes with an empty string. > **Note** > > `postgres:` is not a valid image reference. Docker expects either a reference without a tag, like `postgres` which defaults to the latest image, or with a tag such as `postgres:15`. + + +### local `.env` file _vs_ `.env` file + +An `.env` file can also be used to declare [pre-defined environment variables](envvars.md) used to control Compose behavior and files to be loaded. When executed without an +explicit `--env-file` flag, Compose will search for a `.env` file in working directory ([PWD](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-PWD)) and load values +both for self-configuration and interpolation. If those values define `COMPOSE_FILE` variable which results into project directory being set to another folder, +then the latter is also used to load a second `.env` file, which will have lower precedence. + +This mechanism makes it possible to invoke an existing Compose project with a custom set of variables as overrides, without the need to pass environment +variables by the command line. + +```console +$ cat .env +COMPOSE_FILE=../compose.yaml +POSTGRES_VERSION=9.3 + +$ cat ../compose.yaml +services: + db: + image: "postgres:${POSTGRES_VERSION}" +$ cat ../.env +POSTGRES_VERSION=9.2 + +$ docker compose config +services: + db: + image: "postgres:9.3" +``` +