mirror of https://github.com/docker/docs.git
Updating Environment variables precedence page
Updating Environment variables precedence page based on changes in the code/rule and integrating feedback from the team.
This commit is contained in:
Dockertopia
GitHub
commit
d41b72f551
|
|
@ -1,46 +1,50 @@
|
||||||
---
|
---
|
||||||
title: Environment variables precedence
|
title: Environment variables precedence
|
||||||
description: Scenario Overview illustrating how environmental variables are resolved in Compose
|
description: Scenario Overview illustrating how environment variables are resolved in Compose
|
||||||
keywords: compose, environment, env file
|
keywords: compose, environment, env file
|
||||||
---
|
---
|
||||||
|
|
||||||
## Order of precedence
|
## Order of precedence
|
||||||
1. Passed from the command-line [`docker compose run --env <KEY[=[VAL]]>`](../../engine/reference/commandline/compose_run/#options).
|
|
||||||
2. Passed from/set in `compose.yaml` service's configuration, from the [environment key](../../compose/compose-file/#environment).
|
1. Passed from the [`.env` file](../environment-variables/#the-env-file).
|
||||||
3. Passed from/set in `compose.yaml` service's configuration, from the [env_file key](../../compose/compose-file/#env_file).
|
2. Set in the Host OS environment.
|
||||||
4. Passed from/set in Container Image in the [ENV directive](../../engine/reference/builder/#env).
|
3. Passed from/set in Container Image in the [ENV directive](../../engine/reference/builder/#env).
|
||||||
|
4. Passed from/set in `compose.yaml` service's configuration, from the [env_file key](../../compose/compose-file/#env_file).
|
||||||
|
5. Passed from/set in `compose.yaml` service's configuration, from the [environment key](../../compose/compose-file/#environment).
|
||||||
|
6. Passed from the command line [`docker compose run --env <KEY[=[VAL]]>`](../../engine/reference/commandline/compose_run/#options).
|
||||||
|
|
||||||
### Precedence quick overview table
|
### Precedence quick overview table
|
||||||
The table below provides a quick overview of how interpolation works when using all environment variables on Compose, using `TAG`, an environmental variable defining the version for an image, as an example.
|
The table below provides a quick overview of how interpolation works when using environment variables on Compose.
|
||||||
|
This overview is done using `TAG`, an environment variable defining the version for an image, as an example.
|
||||||
|
|
||||||
Each row represents a scenario and each column represents a context where you can be setting or passing an environment variable.
|
Each table's:
|
||||||
|
* column - represents a context from where you can set or pass `TAG`, or environment variables in general.
|
||||||
|
* row - represents a scenario, this means a combination of contexts where `TAG` is set or passed simultaneously.
|
||||||
|
|
||||||
| # | `.env` file | `compose.yaml`:`env_file` key | `compose.yaml`:`environment` key | CMD | Image | OS | Resolved as |
|
The last column gives you the final result: how `TAG` is resolved for each scenario according with the precedence rule.
|
||||||
|:-:|:--------------------------:|:-----------------------------:|:---------------------------------:|:------------:|:-------------:|:------------:|:-----------------:|
|
|
||||||
| 1 | `TAG=1.3` | Unset | Unset | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.6` |
|
|
||||||
| 2 | `TAG=1.3` | Unset | Unset | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.3` |
|
|
||||||
| 3 | `TAG=$TAG:-1.2` | Unset | Unset | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` |
|
|
||||||
| 4 | `TAG=$TAG:-1.2` | Unset | Unset | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.6` |
|
|
||||||
| 5 | `TAG=$TAG:-1.2` | Unset | Unset | `TAG` | `TAG=1.6` | Unset | `TAG=1.6` |
|
|
||||||
| 6 | `TAG=$TAG:-1.2` | Unset | Unset | `TAG=1.5` | `TAG=1.6` | `TAG=1.4` | `TAG=1.5` |
|
|
||||||
| 7 | `TAG=$TAG:-1.2` | Unset | `TAG` | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` |
|
|
||||||
| 8 | `TAG=$TAG:-1.2` | Unset | `TAG=1.7` | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.7` |
|
|
||||||
| 9 | `TAG=$TAG:-1.2` | Unset | `TAG=1.7` | `TAG=1.5` | `TAG=1.6` | `TAG=1.4` | `TAG=1.5` |
|
|
||||||
| 10| `TAG=$TAG:-1.2` | Unset | `TAG` | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` |
|
|
||||||
| 11| `TAG=$TAG:-1.2` | Unset | `TAG` | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` |
|
|
||||||
| 12| `TAG=$TAG:-1.2` | `TAG=1.8` | Unset | **`TAG=1.5`** | `TAG=1.6` | `TAG=1.4` | `TAG=1.5` |
|
|
||||||
| 13| `TAG=$TAG:-1.2` | `TAG=1.8` | **`TAG=1.7`** | `TAG=1.5` | `TAG=1.6` | `TAG=1.4` | `TAG=1.7` |
|
|
||||||
| 14| Unset |**`TAG=1.8`** | Unset | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.8` |
|
|
||||||
| 15| Unset | Unset | `TAG=1.7` | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` |
|
|
||||||
| 16| Unset | Unset | `TAG=1.7` | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` |
|
|
||||||
|
|
||||||
Description for each column:
|
| # | `.env` file | `Host OS` environment | Image | `compose.yaml`:`env_file` key | `compose.yaml`:`environment` key | `run --env` | RESOLVED AS |
|
||||||
* `.env` file - `.env` file on the project root (or, with higher precedence, the file passed via `docker compose -–env-file <FILE>`).
|
|:--:|:-----------------:|:-----------------------:|:-----------:|:-------------------------------:|:----------------------------------:|:-------------:|:-------------:|
|
||||||
* `OS` environment - OS Environment variable
|
| 1 | `TAG=1.3` | `TAG=1.4` | - | - | - | - | - |
|
||||||
* Image - `ENV` directive in the Dockerfile
|
| 2 | `TAG=1.3` | `TAG=1.4` |**`TAG=1.5`**| - | - | - |**`TAG=1.5`** |
|
||||||
* Compose file - In `env_file` key from the service section in the `compose.yaml`.
|
| 3 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | - |**`$TAG`** |**`TAG=1.4`** |
|
||||||
* Compose file - In `environment` key from the service section in the `compose.yaml`.
|
| 4 |**`TAG=1.3`** | - | `TAG=1.5` |**`$TAG`** | - | - |**`TAG=1.3`** |
|
||||||
* Command line - Environmental variable passed via `docker compose run -e <KEY[=[VAL]]>`.
|
| 5 |**`TAG=1.3`** | - | `TAG=1.5` | - | - |**`$TAG`** |**`TAG=1.3`** |
|
||||||
* Resolved as - This column expresses the result available in the container.
|
| 6 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | - |**`TAG=1.8`** |**`TAG=1.8`** |
|
||||||
|
| 7 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`$TAG`** | - |**`TAG=1.4`** |
|
||||||
|
| 8 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | `TAG=1.7` |**`$TAG`** |**`TAG=1.4`** |
|
||||||
|
| 9 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | `TAG=1.7` |**`TAG=1.8`** |**`TAG=1.8`** |
|
||||||
|
| 10 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`$TAG`** | - |**`TAG=1.4`** |
|
||||||
|
| 11 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | - |**`TAG=1.8`** |**`TAG=1.8`** |
|
||||||
|
| 12 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | `TAG=1.7` |**`TAG=1.8`** |**`TAG=1.8`** |
|
||||||
|
| 13 | - | `TAG=1.4` | `TAG=1.5` |**`TAG=1.6`** | - | - |**`TAG=1.6`** |
|
||||||
|
| 14 | - | `TAG=1.4` | `TAG=1.5` | - |**`TAG=1.7`** | - |**`TAG=1.7`** |
|
||||||
|
|
||||||
**Note that the "`OS`" has precedence over "`.env` file" column for variable resolution in the other columns.**
|
Table column's description:
|
||||||
|
* `.env` file - the `.env` file on the project root.
|
||||||
|
* `Host OS` environment - the environment where the Docker Engine is running.
|
||||||
|
* Image - `ENV` directive in the Dockerfile for the image.
|
||||||
|
* `compose.yaml`:`env_file` key - In `env_file` key from the service section in the `compose.yaml` file.
|
||||||
|
* `compose.yaml`:`environment` key - In `environment` key from the service section in the `compose.yaml` file.
|
||||||
|
* `run --env` - environment variable set via the command line: `docker compose run -e <KEY[=[VAL]]>`.
|
||||||
|
* RESOLVED AS - This column expresses the result available in the container. So this column expresses the value of `TAG`, our example in this table, after Compose applies the precedence rule.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue