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
named `.env` placed in the project directory. The project directory is specified by order of precedence:
- `--project-dir` flag
named `.env` placed in the project directory. Docker Compose versions earlier than `1.28`,
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
- Current directory
## 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.
* Lines beginning with `#` are processed as comments and ignored.
* Blank lines are ignored.
* There is no special handling of quotation marks. This means that
- Compose expects each line in an `env` file to be in `VAR=VAL` format.
- Lines beginning with `#` are processed as comments and ignored.
- Blank lines are ignored.
- There is no special handling of quotation marks. This means that
**they are part of the VAL**.
## Compose file and CLI variables

166
compose/environment-variables.md
View File

@ -21,10 +21,67 @@ web:
image: "webapp:${TAG}"
```
If you have multiple environment variables, you can substitute them by providing
a path to your environment variables file. By default, the `docker-compose`
command will look for a file named `.env` in the project directory (parent folder
of your Compose file).
If you have multiple environment variables, you can substitute them by adding
them to a default environment variable file named `.env` or by providing a
path to your environment variables file using the `--env-file` command line option.
### 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
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
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
[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'
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`:
```bash
```shell
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
```
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 “.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
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
file, and the Compose file:
```bash
```shell
$ cat ./Docker/api/api.env
NODE_ENV=test
@ -172,7 +226,7 @@ services:
When you run the container, the environment variable defined in the Compose
file takes precedence.
```bash
```shell
$ docker-compose exec api node
> 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
[`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
Compose preserves all volumes used by your services. When `docker-compose up`