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

ENGDOCS-2003b (#20188) 

* ENGDOCS-2003b

* redirect

* lint fix

* lint fix
This commit is contained in:
Allie Sadler 2024-06-10 14:19:05 +01:00 committed by GitHub
parent 544db60301
commit 042d84f6de
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 339 additions and 321 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
content/compose/environment-variables/_index.md
View File

@ -5,9 +5,7 @@ description: Explainer on the ways to set, use and manage environment variables
keywords: compose, orchestration, environment, env file
---
Use environment variables to pass configuration information to containers at runtime.
Environment variables are key-value pairs that contain data that can be used by processes running inside a Docker container. They are often used to configure application settings and other parameters that may vary between different environments, such as development, testing, and production.
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.
> **Tip**
>
@ -15,10 +13,11 @@ Environment variables are key-value pairs that contain data that can be used by
{ .tip }
This section covers:
- The various ways you can [set environment variables with Compose](set-environment-variables.md).
- [How environment variable precedence works](envvars-precedence.md).
- The correct syntax for an [environment file](env-file.md).
- Changing pre-defined [environment variables](envvars.md).
- [How to set environment variables within your container's environment](set-environment-variables.md).
- [How environment variable precedence works within your container's environment](envvars-precedence.md).
- [Pre-defined environment variables](envvars.md).
It also covers:
- How [interpolation](variable-interpolation.md) can be used to set variables within your Compose file and how it relates to a container's environment.
- Some [best practices](best-practices.md).

2
content/compose/environment-variables/best-practices.md
View File

@ -20,7 +20,7 @@ Consider how your application adapts to different environments. For example deve
#### Know interpolation
Understand how [interpolation](env-file.md#interpolation) works within compose files for dynamic configurations.
Understand how [interpolation](variable-interpolation.md) works within compose files for dynamic configurations.
#### Command line overrides

64
content/compose/environment-variables/env-file.md
View File

@ -1,64 +0,0 @@
---
description: Understand the accepted syntax for declaring environment variables with an environment file
keywords: fig, composition, compose, docker, orchestration, environment, env file
title: Syntax for environment files in Docker Compose
aliases:
- /compose/env-file/
---
This page provides information on the syntax rules and guidelines when using an `.env` file. It defines the rules for commenting, and explains how values are processed. Additionally, it introduces the concept of interpolation, which allows the use of variables within environment files.
> **Important**
>
> Environment variables from an environment file have lower precedence than those from any other [method](set-environment-variables.md).
For more information, see [Environment variables precedence](envvars-precedence.md).
{ .important }
## Syntax
The following syntax rules apply to environment files:
- Lines beginning with `#` are processed as comments and ignored.
- Blank lines are ignored.
- Unquoted and double-quoted (`"`) values have [interpolation](#interpolation) applied.
- Each line represents a key-value pair. Values can optionally be quoted.
- `VAR=VAL` -> `VAL`
- `VAR="VAL"` -> `VAL`
- `VAR='VAL'` -> `VAL`
- Inline comments for unquoted values must be preceded with a space.
- `VAR=VAL # comment` -> `VAL`
- `VAR=VAL# not a comment` -> `VAL# not a comment`
- Inline comments for quoted values must follow the closing quote.
- `VAR="VAL # not a comment"` -> `VAL # not a comment`
- `VAR="VAL" # comment` -> `VAL`
- Single-quoted (`'`) values are used literally.
- `VAR='$OTHER'` -> `$OTHER`
- `VAR='${OTHER}'` -> `${OTHER}`
- Quotes can be escaped with `\`.
- `VAR='Let\'s go!'` -> `Let's go!`
- `VAR="{\"hello\": \"json\"}"` -> `{"hello": "json"}`
- Common shell escape sequences including `\n`, `\r`, `\t`, and `\\` are supported in double-quoted values.
- `VAR="some\tvalue"` -> `some value`
- `VAR='some\tvalue'` -> `some\tvalue`
- `VAR=some\tvalue` -> `some\tvalue`
### Interpolation
Compose supports interpolation in environment files.
Interpolation is applied for unquoted and double-quoted values.
Both braced (`${VAR}`) and unbraced (`$VAR`) expressions are supported.
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
For more information, see [Interpolation](../compose-file/12-interpolation.md) in the Compose Specification.

104
content/compose/environment-variables/envvars-precedence.md
View File

@ -7,34 +7,32 @@ aliases:
- /compose/envvars-precedence/
---
When the same environment variable is set in multiple sources, Docker Compose follows a precedence rule to determine the value for that variable.
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.
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)
2. Substituted from your [shell](set-environment-variables.md#substitute-from-the-shell)
3. Set using just the [`environment` attribute in the Compose file](set-environment-variables.md#use-the-environment-attribute)
4. Use of the [`--env-file` argument](set-environment-variables.md#substitute-with---env-file) in the CLI
5. Use of the [`env_file` attribute](set-environment-variables.md#use-the-env_file-attribute) in the Compose file
6. Set using an [`.env` file](set-environment-variables.md#substitute-with-an-env-file) placed at base of your project directory
7. Set in a container image in the [ENV directive](../../reference/dockerfile.md#env).
1. Set using [`docker compose run -e` in the CLI](set-environment-variables.md#set-environment-variables-with-docker-compose-run---env).
2. Set with either the `environment` or `env_file` attribute but with the value interpolated from your [shell](variable-interpolation.md#substitute-from-the-shell) or an environment file. (either your default [`.env` file](variable-interpolation.md#env-file), or with the [`--env-file` argument](variable-interpolation.md#substitute-with---env-file) in the CLI).
3. Set using just the [`environment` attribute](set-environment-variables.md#use-the-environment-attribute) in the Compose file.
4. Use of the [`env_file` attribute](set-environment-variables.md#use-the-env_file-attribute) in the Compose file.
5. Set in a container image in the [ENV directive](../../reference/dockerfile.md#env).
Having any `ARG` or `ENV` setting in a `Dockerfile` evaluates only if there is no Docker Compose entry for `environment`, `env_file` or `run --env`.
## Simple example
In the example below, we set a different value for the same environment variable in an `.env` file and with the `environment` attribute in the Compose file:
In the following example, a different value for the same environment variable in an `.env` file and with the `environment` attribute in the Compose file:
```console
$ cat ./Docker/api/api.env
$ cat ./webapp.env
NODE_ENV=test
$ cat compose.yml
services:
api:
image: 'node:6-alpine'
webapp:
image: 'webapp'
env_file:
- ./Docker/api/api.env
- ./webapp.env
environment:
- NODE_ENV=production
```
@ -42,44 +40,64 @@ services:
The environment variable defined with the `environment` attribute takes precedence.
```console
$ docker compose exec api node
> process.env.NODE_ENV
'production'
$ docker compose run webapp env | grep NODE_ENV
NODE_ENV=production
```
> Hard coding variables in container scripts
>
> Executing a command within the container that unconditionally sets a variable value overrules any setting in your `compose.yml` file.
>
> For example, in a NodeJS project, if you have a `package.json` entry for `scripts.start`, such as `NODE_ENV=test` `node server.js`, any value set for `NODE_ENV` in your Compose file, is ignored when running `npm run start` within the container.
{ .important }
## Advanced example
The following table uses `TAG`, an environment variable defining the version for an image, as an example.
The following table uses `VALUE`, an environment variable defining the version for an image, as an example.
### How the table works
Each column represents a context from where you can set a value, or substitute in a value for `TAG`.
Each column represents a context from where you can set a value, or substitute in a value for `VALUE`.
The columns `Host OS environment` and `.env file` is listed only as an illustration lookup. In reality, they don't result in a variable in the container by itself.
The columns `Host OS environment` and `.env` file is listed only for illustration purposes. In reality, they don't result in a variable in the container by itself, but in conjunction with either the `environment` or `env_file` attribute.
Each row represents a combination of contexts where `TAG` is set, substituted, or both. The **Result** column indicates the final value for `TAG` in each scenario.
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`** |
| # | `docker compose run --env` | `environment` attribute | `env_file` attribute | Image `ENV` | `Host OS` environment | `.env` file | | Result |
|:--:|:-------------:|:----------------------------------:|:-------------------------------:|:------------:|:-----------------------:|:-----------------:|:---:|:-------------:|
| 1 | - | - | - | - | `TAG=1.4` | `TAG=1.3` || - |
| 2 | - | - | - |`TAG=1.5` | `TAG=1.4` | `TAG=1.3` ||**`TAG=1.5`** |
| 3 |`TAG` | - | - | `TAG=1.5` |`TAG=1.4` | `TAG=1.3` ||**`TAG=1.4`** |
| 4 | - | - |`TAG` | `TAG=1.5` | - |`TAG=1.3` ||**`TAG=1.3`** |
| 5 |`TAG` | - | - | `TAG=1.5` | - |`TAG=1.3` ||**`TAG=1.3`** |
| 6 |`TAG=1.8` | - | - | `TAG=1.5` | `TAG=1.4` | `TAG=1.3` ||**`TAG=1.8`** |
| 7 | - |`TAG` | - | `TAG=1.5` |`TAG=1.4` | `TAG=1.3` ||**`TAG=1.4`** |
| 8 |`TAG` | `TAG=1.7` | - | `TAG=1.5` |`TAG=1.4` | `TAG=1.3` ||**`TAG=1.4`** |
| 9 |`TAG=1.8` | `TAG=1.7` | - | `TAG=1.5` | `TAG=1.4` | `TAG=1.3` ||**`TAG=1.8`** |
| 10 |`TAG=1.8` | - | `TAG=1.6` | `TAG=1.5` | `TAG=1.4` | `TAG=1.3` ||**`TAG=1.8`** |
| 11 |`TAG=1.8` | `TAG=1.7` | `TAG=1.6` | `TAG=1.5` | `TAG=1.4` | `TAG=1.3` ||**`TAG=1.8`** |
| 12 | - | - |`TAG=1.6` | `TAG=1.5` | `TAG=1.4` | - ||**`TAG=1.6`** |
| 13 | - |`TAG=1.7` | - | `TAG=1.5` | `TAG=1.4` | - ||**`TAG=1.7`** |
### Result explanation
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.
Result 2: The `env_file` attribute in the Compose file defines an explicit value for `VALUE` so the container environment is set accordingly.
Result 3: The `environment` attribute in the Compose file defines an explicit value for `VALUE`, so the container environment is set accordingly/
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 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.
Result 7: The `docker compose run` command has the `--env` flag set to replicate the value from the environment. Value from `.env` file is the selected to define the container's environment.
Result 8: The `env_file` attribute in the Compose file is set to replicate `VALUE` from the local environment. Host OS value takes precedence and is replicated into the container's environment.
Result 9: The `env_file` attribute in the Compose file is set to replicate `VALUE` from the local environment. Value from `.env` file is the selected to define the container's environment.
Result 10: The `environment` attribute in the Compose file is set to replicate `VALUE` from the local environment. Host OS value takes precedence and is replicated into the container's environment.
Result 11: The `environment` attribute in the Compose file is set to replicate `VALUE` from the local environment. Value from `.env` file is the selected to define the container's environment.
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.

6
content/compose/environment-variables/envvars.md
View File

@ -29,9 +29,9 @@ This page contains information on how you can set or change the following pre-de
You can set or change the pre-defined environment variables:
- Within your Compose file using the [`environment` attribute](set-environment-variables.md#use-the-environment-attribute)
- With an [environment file](env-file.md)
- With the `env-file` attribute and an [environment file](set-environment-variables.md#use-the-env_file-attribute)
- From the command line
- From your [shell](set-environment-variables.md#substitute-from-the-shell)
- From your [shell](variable-interpolation.md#substitute-from-the-shell)
When changing or setting any environment variables, be aware of [Environment variable precedence](envvars-precedence.md).
@ -182,7 +182,7 @@ This is an opt-out variable. When turned off it deactivates the experimental fea
## Unsupported in Compose V2
The environment variables listed below have no effect in Compose V2.
The following environment variables have no effect in Compose V2.
For more information, see [Migrate to Compose V2](../migrate.md).
- `COMPOSE_API_VERSION`

248
content/compose/environment-variables/set-environment-variables.md
View File

@ -1,109 +1,44 @@
---
title: Ways to set environment variables with Compose
title: Set environment variables within your container's environment
description: How to set, use, and manage environment variables with Compose
keywords: compose, orchestration, environment, env file
keywords: compose, orchestration, environment, environment variables, container environment variables
aliases:
- /compose/env/
- /compose/link-env-deprecated/
---
With Compose, there are multiple ways you can set environment variables in your containers. You can use either your Compose file, or the CLI.
Be aware that each method is subject to [environment variable precedence](envvars-precedence.md).
A container's environment is not set until there's an explicit entry in the service configuration to make this happen. With Compose, there are two ways you can set environment variables in your containers with your Compose file.
>**Tip**
>
> Don't use environment variables to pass sensitive information, such as passwords, in to your containers. Use [secrets](../use-secrets.md) instead.
{ .tip }
## Compose file
### Substitute with an `.env` file
## Use the `environment` attribute
An `.env` file in Docker Compose is a text file used to define environment variables that should be made available to Docker containers when running `docker compose up`. This file typically contains key-value pairs of environment variables, and it allows you to centralize and manage configuration in one place. The `.env` file is useful if you have multiple environment variables you need to store.
You can set environment variables directly in your container's environment with the
[`environment` attribute](../compose-file/05-services.md#environment) in your `compose.yml`.
The `.env` file is the default method for setting environment variables in your containers. 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.md).
Below is a simple example:
```console
$ cat .env
TAG=v1.5
$ cat compose.yml
services:
web:
image: "webapp:${TAG}"
```
When you run `docker compose up`, the `web` service defined in the Compose file [interpolates](env-file.md#interpolation) in the
image `webapp:v1.5` which was set in the `.env` file. You can verify this with the
[config command](../../reference/cli/docker/compose/config.md), which prints your resolved application config to the terminal:
```console
$ docker compose config
services:
web:
image: 'webapp:v1.5'
```
#### Additional information
- As of Docker Compose version 2.24.0, you can set your `.env` file to be optional by using the `env_file` attribute. When `required` is set to `false` and the `.env` file is missing, Compose silently ignores the entry.
```yaml
env_file:
- path: ./default.env
required: true # default
- path: ./override.env
required: false
```
- 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:
```yaml
services:
webapp:
image: my-webapp-image
environment:
- DEBUG=${DEBUG}
```
Docker Compose replaces `${DEBUG}` with the value from the `.env` file
- You can use multiple `.env` files in your `compose.yml` with the [`env_file` attribute](../compose-file/05-services.md#env_file), and Docker Compose reads them in the order specified. If the same variable is defined in multiple files, the last definition takes precedence:
```yaml
services:
webapp:
image: my-webapp-image
env_file:
- .env
- .env.override
```
- You can place your `.env` file in a location other than the root of your project's directory, and then use one of the following methods so Compose can navigate to it:
- The [`--env-file` option in the CLI](#substitute-with---env-file)
- Using the [`env_file` attribute in the Compose file](../compose-file/05-services.md#env_file)
- Values in your `.env` file can be overridden from the command line by using [`docker compose run -e`](#set-environment-variables-with-docker-compose-run---env).
- Your `.env` file can be overridden by another `.env` if it is [substituted with `--env-file`](#substitute-with---env-file).
> **Important**
>
> Substitution from `.env` files is a Docker Compose CLI feature.
>
> It is not supported by Swarm when running `docker stack deploy`.
{ .important }
### Use the `environment` attribute
You can set environment variables directly in your Compose file without using an `.env` file, with the
[`environment` attribute](../compose-file/05-services.md#environment) in your `compose.yml`. It works in the same way as `docker run -e VARIABLE=VALUE ...`
It supports both list and mapping syntax:
```yaml
web:
environment:
- DEBUG=1
services:
webapp:
environment:
DEBUG: "true"
```
is equivalent to
```yaml
services:
webapp:
environment:
- DEBUG=true
```
See [`environment` attribute](../compose-file/05-services.md#environment) for more examples on how to use it.
#### Additional information
### Additional information
- You can choose not to set a value and pass the environment variables from your shell straight through to your containers. It works in the same way as `docker run -e VARIABLE ...`:
```yaml
@ -111,39 +46,46 @@ See [`environment` attribute](../compose-file/05-services.md#environment) for mo
environment:
- DEBUG
```
The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run.
Note that in this case no warning is issued if the `DEBUG` variable in the shell environment is not set.
The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run. Note that in this case no warning is issued if the `DEBUG` variable in the shell environment is not set.
- You can also take advantage of [interpolation](variable-interpolation.md#interpolation-syntax). In the following example, the result is similar to the one above but Compose gives you a warning if the `DEBUG` variable is not set in the shell environment or in an `.env` file in the project directory.
- You can also take advantage of [interpolation](env-file.md#interpolation).
```yaml
web:
environment:
- DEBUG=${DEBUG}
```
The result is similar to the one above but Compose gives you a warning if the `DEBUG` variable is not set in the shell environment.
### Use the `env_file` attribute
## Use the `env_file` attribute
The [`env_file` attribute](../compose-file/05-services.md#env_file) lets you use multiple `.env` files in your Compose application. It also helps you keep your environment variables separate from your main configuration file, providing a more organized and secure way to manage sensitive information, as you do not need to place your `.env` file in the root of your project's directory.
It works in the same way as `docker run --env-file=FILE ...`.
A container's environment can also be set using [`.env` files](variable-interpolation.md#env-file) along with the [`env_file` attribute](../compose-file/05-services.md#env_file).
```yaml
web:
env_file:
- web-variables.env
services:
webapp:
env_file: "webapp.env"
```
#### Additional information
Using an `.env` file lets you to use the same file for use by a plain `docker run --env-file ...` command, or to share the same `.env` file within multiple services without the need to duplicate a long `environment` YAML block.
It can also help you keep your environment variables separate from your main configuration file, providing a more organized and secure way to manage sensitive information, as you do not need to place your `.env` file in the root of your project's directory.
The [`env_file` attribute](../compose-file/05-services.md#env_file) also lets you use multiple `.env` files in your Compose application.
The paths to your `.env` file, specified in the `env_file` attribute, are relative to the location of your `compose.yml` file.
> **Important**
>
> Interpolation in `.env` files is a Docker Compose CLI feature.
>
> It is not supported when running `docker run --env-file ...`.
{ .important }
### Additional information
- If multiple files are specified, they are evaluated in order and can override values set in previous files.
- Environment variables declared in the `.env` file cannot then be referenced again separately in the Compose file.
- If you use both the `env_file` and `environment` attribute, environment variables set by `environment` take precedence.
- The paths to your `.env` file, specified in the `env_file` attribute, are relative to the location of your `compose.yml` file.
- Values in your `.env` files can be overridden from the command line by using [`docker compose run -e`](#set-environment-variables-with-docker-compose-run---env).
- Your `.env` files can be overriden by another `.env` if it is [substituted with `--env-file`](#substitute-with---env-file).
- As of Docker Compose version 2.24.0, you can set your `.env` file to be optional by using the `required` field. When `required` is set to `false` and the `.env` file is missing,
Compose silently ignores the entry.
- In addition, as the `.env` file supports [interpolation](variable-interpolation.md), it is possible to combine those with values set by `environment`.
- As of Docker Compose version 2.24.0, you can set your `.env` file, defined by the `env_file` attribute, to be optional by using the `required` field. When `required` is set to `false` and the `.env` file is missing, Compose silently ignores the entry.
```yaml
env_file:
- path: ./default.env
@ -151,99 +93,9 @@ Compose silently ignores the entry.
- path: ./override.env
required: false
```
- Values in your `.env` file can be overridden from the command line by using [`docker compose run -e`](#set-environment-variables-with-docker-compose-run---env).
### 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 allows you to 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 example above, 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`.
> **Important**
>
> Values set in the shell environment override those set in the `.env` file, the `environment` attribute, and the `env_file` attribute. For more information, see [Environment variable precedence](envvars-precedence.md).
{ .important }
## CLI
### Substitute with `--env-file`
You can set default values for multiple environment variables, in an [environment file](env-file.md) and then pass the file as an argument in the CLI.
The advantage of this method is that you can store the file anywhere and name it appropriately, for example,
This file path is relative to the current working directory where the Docker Compose command is executed. Passing the file path is done using the `--env-file` option:
```console
$ docker compose --env-file ./config/.env.dev up
```
#### Additional information
- This method is useful if you want to temporarily override an `.env` file that is already referenced in your `compose.yml` file. For example you may have different `.env` files for production ( `.env.prod`) and testing (`.env.test`).
In the following example, there are two environment files, `.env` and `.env.dev`. Both have different values set for `TAG`.
```console
$ cat .env
TAG=v1.5
$ cat ./config/.env.dev
TAG=v1.6
$ cat compose.yml
services:
web:
image: "webapp:${TAG}"
```
If the `--env-file` is not used in the command line, the `.env` file is loaded by default:
```console
$ docker compose config
services:
web:
image: 'webapp:v1.5'
```
Passing the `--env-file` argument overrides the default file path:
```console
$ docker compose --env-file ./config/.env.dev config
services:
web:
image: 'webapp:v1.6'
```
When an invalid file path is being passed as an `--env-file` argument, Compose returns an error:
```console
$ docker compose --env-file ./doesnotexist/.env.dev config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
```
- You can use multiple `--env-file` options to specify multiple environment files, and Docker Compose reads them in order. Later files can override variables from earlier files.
```console
$ docker compose --env-file .env --env-file .env.override up
```
- You can override specific environment variables from the command line when starting containers.
```console
$ docker compose --env-file .env.dev up -e DATABASE_URL=mysql://new_user:new_password@new_db:3306/new_database
```
### Set environment variables with `docker compose run --env`
## Set environment variables with `docker compose run --env`
Similar to `docker run --env`, you can set environment variables temporarily with `docker compose run --env` or its short form `docker compose run -e`:
@ -251,7 +103,7 @@ Similar to `docker run --env`, you can set environment variables temporarily wit
$ docker compose run -e DEBUG=1 web python console.py
```
#### Additional information
### Additional information
- You can also pass a variable from the shell by not giving it a value:
@ -259,11 +111,11 @@ $ docker compose run -e DEBUG=1 web python console.py
$ docker compose run -e DEBUG web python console.py
```
The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run.
The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run.
## Further resources
- [Understand environment variable precedence](envvars-precedence.md).
- [Set or change predefined environment variables](envvars.md)
- [Explore best practices](best-practices.md)
- [Understand the syntax and formatting guidelines for environment files](env-file.md)
- [Understand interpolation](variable-interpolation.md)

213
content/compose/environment-variables/variable-interpolation.md Normal file
View File

@ -0,0 +1,213 @@
---
title: Set, use, and manage variables in a Compose file with interpolation
description: How to set, use, and manage variables in your Compose file with interpolation
keywords: compose, orchestration, environment, variables, interpolation
aliases:
- /compose/env-file/
- /compose/environment-variables/env-file/
---
A Compose file can use variables to offer more flexibility. If you want to quickly switch
between image tags to test multiple versions, or want to adjust a volume source to your local
environment, you don't need to edit the Compose file each time, you can just set variables that insert values into your Compose file at run time.
Interpolation can also be used to insert values into your Compose file at run time, which is then used to pass variables into your container's environment
Below is a simple example:
```console
$ cat .env
TAG=v1.5
$ cat compose.yml
services:
web:
image: "webapp:${TAG}"
```
When you run `docker compose up`, the `web` service defined in the Compose file [interpolates](variable-interpolation.md) in the image `webapp:v1.5` which was set in the `.env` file. You can verify this with the
[config command](../../reference/cli/docker/compose/config.md), which prints your resolved application config to the terminal:
```console
$ docker compose config
services:
web:
image: 'webapp:v1.5'
```
## Interpolation syntax
Interpolation is applied for unquoted and double-quoted values.
Both braced (`${VAR}`) and unbraced (`$VAR`) expressions are supported.
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
For more information, see [Interpolation](../compose-file/12-interpolation.md) in the Compose Specification.
## 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.
### `.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.
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).
Basic example:
```console
$ cat .env
## define COMPOSE_DEBUG based on DEV_MODE, defaults to false
COMPOSE_DEBUG=${DEV_MODE:-false}
$ cat compose.yaml
services:
webapp:
image: my-webapp-image
environment:
- DEBUG=${COMPOSE_DEBUG}
$ DEV_MODE=true docker compose config
services:
webapp:
environment:
DEBUG: "true"
```
#### 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:
```yaml
services:
webapp:
image: my-webapp-image
environment:
- DEBUG=${DEBUG}
```
Docker Compose replaces `${DEBUG}` with the value from the `.env` file
> **Important**
>
> Be aware of [Environment variables precedence](envvars-precedence.md) when using variables in an `.env` file that as environment variables in your container's environment.
{ .important }
- You can place your `.env` file in a location other than the root of your project's directory, and then use the [`--env-file` option in the CLI](#substitute-with---env-file) so Compose can navigate to it.
- Your `.env` file can be overridden by another `.env` if it is [substituted with `--env-file`](#substitute-with---env-file).
> **Important**
>
> Substitution from `.env` files is a Docker Compose CLI feature.
>
> It is not supported by Swarm when running `docker stack deploy`.
{ .important }
#### `.env` file syntax
The following syntax rules apply to environment files:
- Lines beginning with `#` are processed as comments and ignored.
- Blank lines are ignored.
- Unquoted and double-quoted (`"`) values have interpolation applied.
- Each line represents a key-value pair. Values can optionally be quoted.
- `VAR=VAL` -> `VAL`
- `VAR="VAL"` -> `VAL`
- `VAR='VAL'` -> `VAL`
- Inline comments for unquoted values must be preceded with a space.
- `VAR=VAL # comment` -> `VAL`
- `VAR=VAL# not a comment` -> `VAL# not a comment`
- Inline comments for quoted values must follow the closing quote.
- `VAR="VAL # not a comment"` -> `VAL # not a comment`
- `VAR="VAL" # comment` -> `VAL`
- Single-quoted (`'`) values are used literally.
- `VAR='$OTHER'` -> `$OTHER`
- `VAR='${OTHER}'` -> `${OTHER}`
- Quotes can be escaped with `\`.
- `VAR='Let\'s go!'` -> `Let's go!`
- `VAR="{\"hello\": \"json\"}"` -> `{"hello": "json"}`
- Common shell escape sequences including `\n`, `\r`, `\t`, and `\\` are supported in double-quoted values.
- `VAR="some\tvalue"` -> `some value`
- `VAR='some\tvalue'` -> `some\tvalue`
- `VAR=some\tvalue` -> `some\tvalue`
### Substitute with `--env-file`
You can set default values for multiple environment variables, in an `.env` file and then pass the file as an argument in the CLI.
The advantage of this method is that you can store the file anywhere and name it appropriately, for example,
This file path is relative to the current working directory where the Docker Compose command is executed. Passing the file path is done using the `--env-file` option:
```console
$ docker compose --env-file ./config/.env.dev up
```
#### Additional information
- This method is useful if you want to temporarily override an `.env` file that is already referenced in your `compose.yml` file. For example you may have different `.env` files for production ( `.env.prod`) and testing (`.env.test`).
In the following example, there are two environment files, `.env` and `.env.dev`. Both have different values set for `TAG`.
```console
$ cat .env
TAG=v1.5
$ cat ./config/.env.dev
TAG=v1.6
$ cat compose.yml
services:
web:
image: "webapp:${TAG}"
```
If the `--env-file` is not used in the command line, the `.env` file is loaded by default:
```console
$ docker compose config
services:
web:
image: 'webapp:v1.5'
```
Passing the `--env-file` argument overrides the default file path:
```console
$ docker compose --env-file ./config/.env.dev config
services:
web:
image: 'webapp:v1.6'
```
When an invalid file path is being passed as an `--env-file` argument, Compose returns an error:
```console
$ docker compose --env-file ./doesnotexist/.env.dev config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
```
- You can use multiple `--env-file` options to specify multiple environment files, and Docker Compose reads them in order. Later files can override variables from earlier files.
```console
$ docker compose --env-file .env --env-file .env.override up
```
- You can override specific environment variables from the command line when starting containers.
```console
$ docker compose --env-file .env.dev up -e DATABASE_URL=mysql://new_user:new_password@new_db:3306/new_database
```
### 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`.

2
content/compose/migrate.md
View File

@ -79,7 +79,7 @@ The following behave differently between Compose V1 and V2:
Environment variable behavior in Compose V1 wasn't formally documented and behaved inconsistently in some edge cases.
For Compose V2, the [Environment variables](/compose/environment-variables/) section covers both [precedence](/compose/environment-variables/envvars-precedence) as well as [`.env` file interpolation](/compose/environment-variables/env-file) and includes many examples covering tricky situations such as escaping nested quotes.
For Compose V2, the [Environment variables](/compose/environment-variables/) section covers both [precedence](/compose/environment-variables/envvars-precedence) as well as [`.env` file interpolation](environment-variables/variable-interpolation.md) and includes many examples covering tricky situations such as escaping nested quotes.
Check if:
- Your project uses multiple levels of environment variable overrides, for example `.env` file and `--env` CLI flags.

4
data/toc.yaml
View File

@ -2015,10 +2015,10 @@ Manuals:
title: Explore ways to set environment variables
- path: /compose/environment-variables/envvars-precedence/
title: Understand environment variables precedence
- path: /compose/environment-variables/env-file/
title: Syntax for environment files
- path: /compose/environment-variables/envvars/
title: Set or change pre-defined environment variables
- path: /compose/environment-variables/variable-interpolation/
title: Interpolation
- path: /compose/environment-variables/best-practices/
title: Best practices
- sectiontitle: Use...