docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ENGDOCS-216 (#20222) 

* ENGDOCS-216

* ENGDOCS-216
This commit is contained in:
Allie Sadler 2024-06-13 08:15:18 +01:00 committed by GitHub
parent f95da63054
commit baf4aafab0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 47 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
content/compose/compose-file/12-interpolation.md
View File

@ -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:

73
content/compose/environment-variables/variable-interpolation.md
View File

@ -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 <project directory> `.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_ <project directory> `.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`.