diff --git a/content/compose/compose-file/12-interpolation.md b/content/compose/compose-file/12-interpolation.md index 1e22254699..e511ee3da4 100644 --- a/content/compose/compose-file/12-interpolation.md +++ b/content/compose/compose-file/12-interpolation.md @@ -6,19 +6,18 @@ keywords: compose, compose specification, interpolation, compose file reference {{< include "compose/interpolation.md" >}} -Default values can be defined inline using typical shell syntax: - -- `${VARIABLE:-default}` evaluates to `default` if `VARIABLE` is unset or - empty in the environment. -- `${VARIABLE-default}` evaluates to `default` only if `VARIABLE` is unset - in the environment. - -Similarly, the following syntax allows you to specify mandatory variables: - -- `${VARIABLE:?err}` exits with an error message containing `err` if - `VARIABLE` is unset or empty in the environment. -- `${VARIABLE?err}` exits with an error message containing `err` only if - `VARIABLE` is unset in the environment. +For braced expressions, the following formats are supported: +- Direct substitution + - `${VAR}` -> value of `VAR` +- Default value + - `${VAR:-default}` -> value of `VAR` if set and non-empty, otherwise `default` + - `${VAR-default}` -> value of `VAR` if set, otherwise `default` +- Required value + - `${VAR:?error}` -> value of `VAR` if set and non-empty, otherwise exit with error + - `${VAR?error}` -> value of `VAR` if set, otherwise exit with error +- Alternative value + - `${VAR:+replacement}` -> `replacement` if `VAR` is set and non-empty, otherwise empty + - `${VAR+replacement}` -> `replacement` if `VAR` is set, otherwise empty Interpolation can also be nested: diff --git a/content/compose/environment-variables/variable-interpolation.md b/content/compose/environment-variables/variable-interpolation.md index d81116f33c..519b1dfec3 100644 --- a/content/compose/environment-variables/variable-interpolation.md +++ b/content/compose/environment-variables/variable-interpolation.md @@ -56,13 +56,21 @@ For more information, see [Interpolation](../compose-file/12-interpolation.md) i ## Ways to set variables with interpolation -Docker Compose can interpolate variables into your Compose file from multiple sources; an `.env` file, variables in your environment either set globally or explicitly by the command line. +Docker Compose can interpolate variables into your Compose file from multiple sources. + +Note that when the same variable is declared by multiple sources, precedence applies: + +1. Variables from your shell environment +2. If `--env-file` is not set, variables set by an `.env` file in local working directory (`PWD`) +3. Variables from a 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`. ### `.env` file 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). +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-syntax). Basic example: @@ -85,16 +93,6 @@ 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 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: @@ -123,7 +121,6 @@ You can check variables and values used by Compose to interpolate the compose mo > It is not supported by Swarm when running `docker stack deploy`. { .important } - #### `.env` file syntax The following syntax rules apply to environment files: @@ -205,34 +202,15 @@ $ docker compose --env-file ./config/.env.dev up $ docker compose --env-file .env.dev up -e DATABASE_URL=mysql://new_user:new_password@new_db:3306/new_database ``` -### Substitute from the shell +### local `.env` file versus `.env` file -You can use existing environment variables from your host machine or from the shell environment where you execute `docker compose` commands. This lets you dynamically inject values into your Docker Compose configuration at runtime. -For example, suppose the shell contains `POSTGRES_VERSION=9.3` and you supply the following configuration: +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. -```yaml -db: - image: "postgres:${POSTGRES_VERSION}" -``` +When executed without an explicit `--env-file` flag, Compose searches for an `.env` file in your working directory ([PWD](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-PWD)) and loads values +both for self-configuration and interpolation. If the values in this file define the `COMPOSE_FILE` pre-defined variable, which results in a project directory being set to another folder, +Compose will load a second `.env` file, if present. This second `.env` file has a lower precedence. -When you run `docker compose up` with this configuration, Compose looks for the `POSTGRES_VERSION` environment variable in the shell and substitutes its value in. For this example, Compose resolves the image to `postgres:9.3` before running the configuration. - -If an environment variable is not set, Compose substitutes with an empty string. In the previous example, if `POSTGRES_VERSION` is not set, the value for the image option is `postgres:`. - -> **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. +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 @@ -252,3 +230,22 @@ services: image: "postgres:9.3" ``` +### Substitute from the shell + +You can use existing environment variables from your host machine or from the shell environment where you execute `docker compose` commands. This lets you dynamically inject values into your Docker Compose configuration at runtime. +For example, suppose the shell contains `POSTGRES_VERSION=9.3` and you supply the following configuration: + +```yaml +db: + image: "postgres:${POSTGRES_VERSION}" +``` + +When you run `docker compose up` with this configuration, Compose looks for the `POSTGRES_VERSION` environment variable in the shell and substitutes its value in. For this example, Compose resolves the image to `postgres:9.3` before running the configuration. + +If an environment variable is not set, Compose substitutes with an empty string. In the previous example, if `POSTGRES_VERSION` is not set, the value for the image option is `postgres:`. + +> **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`. + +