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

Engdocs 1814 (#18670) 

* ENGDOCS-1814

* ENGDOCS-1814

* tidy up

* style guide edits

* review comments
This commit is contained in:
Allie Sadler 2023-12-06 14:19:51 +00:00 committed by GitHub
parent 4f2a5312e6
commit ce8823deae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 188 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -7,10 +7,20 @@ keywords: compose, orchestration, environment, env file
{{< include "compose-eol.md" >}}
Environment variables can help you define various configuration values. They also keep your app flexible and organized.
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.
> **Tip**
>
> Before using environment variables, read through all of the information first to get a full picture of environment variables in Docker Compose.
{ .tip }
This section covers:
- The various ways you can [set environment variables in Compose](set-environment-variables.md).
- 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).
- Changing pre-defined [environment variables](envvars.md).
- Some [best practices](best-practices.md).

27
content/compose/environment-variables/best-practices.md Normal file
View File

@ -0,0 +1,27 @@
---
title: Best practices for working with environment variables in Docker Compose
description: Explainer on the best ways to set, use, and manage environment variables in
Compose
keywords: compose, orchestration, environment, env file, environment variables
---
#### Handle sensitive information securely
Be cautious about including sensitive data in environment variables. Consider using [Secrets](../use-secrets.md) for managing sensitive information.
#### Understand environment variable precedence
Be aware of how Docker Compose handles the [precedence of environment variables](envvars-precedence.md) from different sources (`.env` files, shell variables, Dockerfiles).
#### Use specific environment files
Consider how your application adapts to different environments. For example development, testing, production, and use different `.env` files as needed.
#### Know interpolation
Understand how [interpolation](env-file.md#interpolation) works within compose files for dynamic configurations.
#### Command line overrides
Be aware that you can [override environment variables](set-environment-variables.md#cli) from the command line when starting containers. This is useful for testing or when you have temporary changes.

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

@ -1,17 +1,25 @@
---
description: Understand the accepted syntax for declaring environment variables.
description: Understand the accepted syntax for declaring environment variables with an environment file
keywords: fig, composition, compose, docker, orchestration, environment, env file
title: Use an environment file in Docker Compose
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 [parameter expansion](#parameter-expansion) applied.
- 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`
@ -33,9 +41,9 @@ The following syntax rules apply to environment files:
- `VAR='some\tvalue'` -> `some\tvalue`
- `VAR=some\tvalue` -> `some\tvalue`
### Parameter expansion
Compose supports parameter expansion in environment files.
Parameter expansion is applied for unquoted and double-quoted values.
### 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:
@ -51,7 +59,5 @@ For braced expressions, the following formats are supported:
- `${VAR:+replacement}` -> `replacement` if `VAR` is set and non-empty, otherwise empty
- `${VAR+replacement}` -> `replacement` if `VAR` is set, otherwise empty
## Precedence
Environment variables from an environment file have lower precedence than those passed via the command-line or via the `environment` attribute in the `compose.yml` file.
For more information, see [Environment variables precedence](envvars-precedence.md).

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

@ -7,14 +7,14 @@ aliases:
- /compose/envvars-precedence/
---
When you set the same environment variable in multiple sources, there’s a precedence rule used by Compose. It aims to resolve the value for the variable in question.
When the same environment variable is set in multiple sources, Docker Compose follows a precedence rule to determine the value for that variable.
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 the [`environment` attribute in the Compose file](set-environment-variables.md#use-the-environment-attribute)
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
@ -65,7 +65,7 @@ Each column represents a context from where you can set a value, or substitute i
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.
Each row represents a combination of contexts where `TAG` is set, substituted, or both.
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.
| # | `docker compose run --env` | `environment` attribute | `env_file` attribute | Image `ENV` | `Host OS` environment | `.env` file | | Result |

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

@ -6,7 +6,7 @@ aliases:
- /compose/reference/envvars/
---
Compose already comes with pre-defined environment variables.
Compose already comes with pre-defined environment variables. It also inherits common Docker CLI environment variables, such as `DOCKER_HOST` and `DOCKER_CONTEXT`. See [Docker CLI environment variable reference](/engine/reference/commandline/cli/#environment-variables) for details.
This page contains information on how you can set or change the following pre-defined environment variables if you need to:
@ -23,8 +23,6 @@ This page contains information on how you can set or change the following pre-de
- `COMPOSE_STATUS_STDOUT`
- `COMPOSE_ENV_FILES`
Compose also inherits common Docker CLI environment variables, such as `DOCKER_HOST` and `DOCKER_CONTEXT`. See [Docker CLI environment variable reference](/engine/reference/commandline/cli/#environment-variables) for details.
## Methods to override
You can set or change the pre-defined environment variables:
@ -146,7 +144,13 @@ The default value is false to clearly separate the output streams between Compos
Lets you specify which environment files Compose should use if `--env-file` isn't used.
When using multiple environment files, use a comma as a separator.
When using multiple environment files, use a comma as a separator. For example,
```console
COMPOSE_ENV_FILES=.env.envfile1, .env.envfile2
```
If `COMPOSE_ENV_FILES` is not set, and you don't provide `--env-file` in the CLI, Docker Compose uses the default behavior, which is to look for an `.env` file in the project directory.
## Unsupported in Compose V2

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

@ -1,13 +1,15 @@
---
title: Ways to set environment variables in Compose
description: How to set, use and manage environment variables in Compose
title: Ways to set environment variables with Compose
description: How to set, use, and manage environment variables with Compose
keywords: compose, orchestration, environment, env file
aliases:
- /compose/env/
- /compose/link-env-deprecated/
---
Environment variables are dealt with by either the Compose file or the CLI. Both have multiple ways you can substitute in or set your environment variables. This is outlined below.
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).
>**Tip**
>
@ -18,7 +20,9 @@ Environment variables are dealt with by either the Compose file or the CLI. Both
### Substitute with an `.env` file
The `.env` file is useful if you have multiple environment variables you need to store.
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.
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:
@ -32,7 +36,7 @@ services:
image: "webapp:${TAG}"
```
When you run `docker compose up`, the `web` service defined in the Compose file substitutes in the
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](../../engine/reference/commandline/compose_config.md), which prints your resolved application config to the terminal:
@ -44,12 +48,31 @@ services:
image: 'webapp:v1.5'
```
The `.env` file should be placed at the root of the project directory next to your `compose.yaml` file. You can use an alternative path with one of the following methods:
- The [`--file` option in the CLI](../reference/index.md#use--f-to-specify-name-and-path-of-one-or-more-compose-files)
- 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)
#### Additional information
For more information on formatting an environment file, see [Use an environment file](env-file.md).
- 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 up -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**
>
@ -60,8 +83,8 @@ For more information on formatting an environment file, see [Use an environment
### Use the `environment` attribute
You can set environment variables in a service's containers with the
[`environment` attribute](../compose-file/05-services.md#environment) in your Compose file. It works in the same way as `docker run -e VARIABLE=VALUE ...`
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 ...`
```yaml
web:
@ -69,52 +92,48 @@ web:
- DEBUG=1
```
You can choose not to set a value and pass the environment variables from your shell straight through to a
service's containers. It works in the same way as `docker run -e VARIABLE ...`:
See [`environment` attribute](../compose-file/05-services.md#environment) for more examples on how to use it.
```yaml
web:
environment:
- DEBUG
```
#### 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
web:
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 will be issued if the `DEBUG` variable in the shell environment is not set.
You can also explicitly assign a variable using a Bash-like syntax `${DEBUG}`:
```yaml
web:
environment:
- DEBUG=${DEBUG}
```
The result is similar to the one above but Compose will give you a warning if the `DEBUG` variable is not set in the shell environment.
See [`environment` attribute](../compose-file/05-services.md#environment) and [variable interpolation](../compose-file/12-interpolation.md) for more information.
- 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
You can pass multiple environment variables from an external file through to
a service's containers with the [`env_file` option](../compose-file/05-services.md#env_file). This works in the same way as `docker run --env-file=FILE ...`:
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 ...`.
```yaml
web:
env_file:
- web-variables.env
```
If multiple files are specified, they are evaluated in order and can override values set in previous files.
> **Note**
>
>With this option, environment variables declared in the file cannot then be referenced again separately in the Compose file or used to configure Compose.
See [`env_file` attribute](../compose-file/05-services.md#env_file) for more information.
#### 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 up -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).
### Substitute from the shell
It's possible to use environment variables in your shell to populate values inside a Compose file. Compose uses the variable values from the shell environment in which `docker compose` is run.
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:
@ -142,72 +161,85 @@ If an environment variable is not set, Compose substitutes with an empty string.
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, `.env.ci`, `.env.dev`, `.env.prod`. 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:
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
```
In the following example, there are two environment files, `.env` and `.env.dev`. Both have different values set for `TAG`.
#### 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
```console
$ cat .env
TAG=v1.5
$ cat ./config/.env.dev
TAG=v1.6
$ cat ./config/.env.dev
TAG=v1.6
$ cat compose.yml
services:
web:
image: "webapp:${TAG}"
```
$ 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:
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'
```
```console
$ docker compose config
services:
web:
image: 'webapp:v1.5'
```
Passing the `--env-file` argument overrides the default file path:
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'
```
```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:
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
```
```console
$ docker compose --env-file ./doesnotexist/.env.dev config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
```
> **Important**
>
> Values set in the shell environment override those set when using the `--env-file` argument in the CLI. For more information, see [Environment variable precedence](envvars-precedence.md)
{ .important }
- 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`
Similar to `docker run --env`, you can set environment variables in a one-off
container with `docker compose run --env` or its short form `docker compose run -e`:
Similar to `docker run --env`, you can set environment variables temporarily with `docker compose run --env` or its short form `docker compose run -e`:
```console
$ docker compose run -e DEBUG=1 web python console.py
```
#### Additional information
You can also pass a variable from the shell by not giving it a value:
- You can also pass a variable from the shell by not giving it a value:
```console
$ docker compose run -e DEBUG web python console.py
```
```console
$ 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)

4
data/toc.yaml
View File

@ -1944,9 +1944,11 @@ Manuals:
- path: /compose/environment-variables/envvars-precedence/
title: Understand environment variables precedence
- path: /compose/environment-variables/env-file/
title: Use an environment file
title: Syntax for environment files
- path: /compose/environment-variables/envvars/
title: Set or change pre-defined environment variables
- path: /compose/environment-variables/best-practices/
title: Best practices
- path: /compose/profiles/
title: Using service profiles
- sectiontitle: Working with multiple Compose files