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

Update docs on Compose environment files (#12514) 

* Reorganize sections for variable substitution and document .env file path change for `1.28`

Signed-off-by: Anca Iordache <anca.iordache@docker.com>

* Minor style edits

* Minor style edits

Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com>
This commit is contained in:
Anca Iordache 2021-03-23 22:42:08 +01:00 committed by GitHub
parent 830a0071ad
commit cc6762ecd3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 129 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
compose/env-file.md
View File

@ -5,19 +5,27 @@ title: Declare default environment variables in file
--- ---
Compose supports declaring default environment variables in an environment file Compose supports declaring default environment variables in an environment file
named `.env` placed in the project directory. The project directory is specified by order of precedence: named `.env` placed in the project directory. Docker Compose versions earlier than `1.28`,
- `--project-dir` flag load the `.env` file from the current working directory, where the command is executed, or from the
project directory if this is explicitly set with the `--project-directory` option. This
inconsistency has been addressed starting with `+v1.28` by limiting the default `.env` file path
to the project directory. You can use the `--env-file` commandline option to override the default
`.env` and specify the path to a custom environment file.
The project directory is specified by the order of precedence:
- `--project-directory` flag
- Folder of the first `--file` flag - Folder of the first `--file` flag
- Current directory - Current directory
## Syntax rules ## Syntax rules
These syntax rules apply to the `.env` file: The following syntax rules apply to the `.env` file:
* Compose expects each line in an `env` file to be in `VAR=VAL` format. - Compose expects each line in an `env` file to be in `VAR=VAL` format.
* Lines beginning with `#` are processed as comments and ignored. - Lines beginning with `#` are processed as comments and ignored.
* Blank lines are ignored. - Blank lines are ignored.
* There is no special handling of quotation marks. This means that - There is no special handling of quotation marks. This means that
**they are part of the VAL**. **they are part of the VAL**.
## Compose file and CLI variables ## Compose file and CLI variables

166
compose/environment-variables.md
View File

@ -21,10 +21,67 @@ web:
image: "webapp:${TAG}" image: "webapp:${TAG}"
``` ```
If you have multiple environment variables, you can substitute them by providing If you have multiple environment variables, you can substitute them by adding
a path to your environment variables file. By default, the `docker-compose` them to a default environment variable file named `.env` or by providing a
command will look for a file named `.env` in the project directory (parent folder path to your environment variables file using the `--env-file` command line option.
of your Compose file).
### The “.env” file
You can set default values for any environment variables referenced in the
Compose file, or used to configure Compose, in an [environment file](env-file.md)
named `.env`. The `.env` file path is as follows:
- Starting with `+v1.28`, `.env.` file is placed at the base of the project directory
- For previous versions, it is placed in the current working directory where the
Docker Compose command is executed unless a `--project-directory` is defined which
overrides the path for the `.env` file. This inconsistency is addressed
in `+v1.28` by limiting the filepath to the project directory.
```shell
$ cat .env
TAG=v1.5
$ cat docker-compose.yml
version: '3'
services:
web:
image: "webapp:${TAG}"
```
When you run `docker-compose up`, the `web` service defined above uses the
image `webapp:v1.5`. You can verify this with the
[config command](reference/config.md), which prints your resolved application
config to the terminal:
```shell
$ docker-compose config
version: '3'
services:
web:
image: 'webapp:v1.5'
```
Values in the shell take precedence over those specified in the `.env` file.
If you set `TAG` to a different value in your shell, the substitution in `image`
uses that instead:
```shell
$ export TAG=v2.0
$ docker-compose config
version: '3'
services:
web:
image: 'webapp:v2.0'
```
You can override the environment file path using a command line argument `--env-file`.
### Using the “--env-file” option
By passing the file as an argument, you can store it anywhere and name it By passing the file as an argument, you can store it anywhere and name it
appropriately, for example, `.env.ci`, `.env.dev`, `.env.prod`. Passing the file path is appropriately, for example, `.env.ci`, `.env.dev`, `.env.prod`. Passing the file path is
@ -33,6 +90,49 @@ done using the `--env-file` option:
```shell ```shell
docker-compose --env-file ./config/.env.dev up docker-compose --env-file ./config/.env.dev up
``` ```
This file path is relative to the current working directory where the Docker Compose
command is executed.
```shell
$ cat .env
TAG=v1.5
$ cat ./config/.env.dev
TAG=v1.6
$ cat docker-compose.yml
version: '3'
services:
web:
image: "webapp:${TAG}"
```
The `.env` file is loaded by default:
```shell
$ docker-compose config
version: '3'
services:
web:
image: 'webapp:v1.5'
```
Passing the `--env-file ` argument overrides the default file path:
```shell
$ docker-compose --env-file ./config/.env.dev config
version: '3'
services:
web:
image: 'webapp:v1.6'
```
When an invalid file path is being passed as `--env-file` argument, Compose returns an error:
```
$ docker-compose --env-file ./doesnotexist/.env.dev config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
```
For more information, see the For more information, see the
[Variable substitution](compose-file/compose-file-v3.md#variable-substitution) section in the [Variable substitution](compose-file/compose-file-v3.md#variable-substitution) section in the
@ -80,68 +180,22 @@ web:
## Set environment variables with 'docker-compose run' ## Set environment variables with 'docker-compose run'
Just like with `docker run -e`, you can set environment variables on a one-off Similar to `docker run -e`, you can set environment variables on a one-off
container with `docker-compose run -e`: container with `docker-compose run -e`:
```bash ```shell
docker-compose run -e DEBUG=1 web python console.py docker-compose run -e DEBUG=1 web python console.py
``` ```
You can also pass a variable through from the shell by not giving it a value: You can also pass a variable from the shell by not giving it a value:
```bash ```shell
docker-compose run -e DEBUG 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 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 same variable in the shell in which Compose is run.
## The “.env” file
You can set default values for any environment variables referenced in the
Compose file, or used to configure Compose, in an [environment file](env-file.md)
named `.env`:
```bash
$ cat .env
TAG=v1.5
$ cat docker-compose.yml
version: '3'
services:
web:
image: "webapp:${TAG}"
```
When you run `docker-compose up`, the `web` service defined above uses the
image `webapp:v1.5`. You can verify this with the
[config command](reference/config.md), which prints your resolved application
config to the terminal:
```bash
$ docker-compose config
version: '3'
services:
web:
image: 'webapp:v1.5'
```
Values in the shell take precedence over those specified in the `.env` file.
If you set `TAG` to a different value in your shell, the substitution in `image`
uses that instead:
```bash
$ export TAG=v2.0
$ docker-compose config
version: '3'
services:
web:
image: 'webapp:v2.0'
```
When you set the same environment variable in multiple files, here's the When you set the same environment variable in multiple files, here's the
priority used by Compose to choose which value to use: priority used by Compose to choose which value to use:
@ -154,7 +208,7 @@ priority used by Compose to choose which value to use:
In the example below, we set the same environment variable on an Environment In the example below, we set the same environment variable on an Environment
file, and the Compose file: file, and the Compose file:
```bash ```shell
$ cat ./Docker/api/api.env $ cat ./Docker/api/api.env
NODE_ENV=test NODE_ENV=test
@ -172,7 +226,7 @@ services:
When you run the container, the environment variable defined in the Compose When you run the container, the environment variable defined in the Compose
file takes precedence. file takes precedence.
```bash ```shell
$ docker-compose exec api node $ docker-compose exec api node
> process.env.NODE_ENV > process.env.NODE_ENV

4
compose/index.md
View File

@ -95,6 +95,10 @@ a custom project name by using the
[`-p` command line option](reference/overview.md) or the [`-p` command line option](reference/overview.md) or the
[`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compose_project_name). [`COMPOSE_PROJECT_NAME` environment variable](reference/envvars.md#compose_project_name).
The default project directory is the base directory of the Compose file. A custom value
for it can be defined with the `--project-directory` command line option.
### Preserve volume data when containers are created ### Preserve volume data when containers are created
Compose preserves all volumes used by your services. When `docker-compose up` Compose preserves all volumes used by your services. When `docker-compose up`