mirror of https://github.com/docker/docs.git
Update compose env to comply with styleguide
This commit is contained in:
Joao Fernandes
Joao Fernandes
parent
5c8b79ba61
commit
d670e54ac3
|
|
@ -1,124 +1,181 @@
|
||||||
---
|
---
|
||||||
description: How to set, use and manage environment variables in Compose
|
|
||||||
keywords: fig, composition, compose, docker, orchestration, environment, variables, env file
|
|
||||||
title: Environment variables in Compose
|
title: Environment variables in Compose
|
||||||
|
description: How to set, use and manage environment variables in Compose
|
||||||
|
keywords: compose, orchestration, environment, env file
|
||||||
---
|
---
|
||||||
|
|
||||||
There are multiple parts of Compose that deal with environment variables in one sense or another. This page should help you find the information you need.
|
There are multiple parts of Compose that deal with environment variables in one
|
||||||
|
sense or another. This page should help you find the information you need.
|
||||||
|
|
||||||
|
|
||||||
## Substituting environment variables in Compose files
|
## Substitute environment variables in Compose files
|
||||||
|
|
||||||
It's possible to use environment variables in your shell to populate values inside a Compose file:
|
It's possible to use environment variables in your shell to populate values
|
||||||
|
inside a Compose file:
|
||||||
|
|
||||||
web:
|
```yaml
|
||||||
image: "webapp:${TAG}"
|
web:
|
||||||
|
image: "webapp:${TAG}"
|
||||||
|
```
|
||||||
|
|
||||||
For more information, see the [Variable substitution](compose-file.md#variable-substitution) section in the Compose file reference.
|
For more information, see the
|
||||||
|
[Variable substitution](compose-file.md#variable-substitution) section in the
|
||||||
|
Compose file reference.
|
||||||
|
|
||||||
|
|
||||||
## Setting environment variables in containers
|
## Set environment variables in containers
|
||||||
|
|
||||||
You can set environment variables in a service's containers with the ['environment' key](compose-file.md#environment), just like with `docker run -e VARIABLE=VALUE ...`:
|
You can set environment variables in a service's containers with the
|
||||||
|
['environment' key](compose-file.md#environment), just like with
|
||||||
|
`docker run -e VARIABLE=VALUE ...`:
|
||||||
|
|
||||||
web:
|
```yaml
|
||||||
environment:
|
web:
|
||||||
- DEBUG=1
|
environment:
|
||||||
|
- DEBUG=1
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pass environment variables to containers
|
||||||
|
|
||||||
## Passing environment variables through to containers
|
You can pass environment variables from your shell straight through to a
|
||||||
|
service's containers with the ['environment' key](compose-file.md#environment)
|
||||||
|
by not giving them a value, just like with `docker run -e VARIABLE ...`:
|
||||||
|
|
||||||
You can pass environment variables from your shell straight through to a service's containers with the ['environment' key](compose-file.md#environment) by not giving them a value, just like with `docker run -e VARIABLE ...`:
|
```yaml
|
||||||
|
web:
|
||||||
web:
|
environment:
|
||||||
environment:
|
- DEBUG
|
||||||
- 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.
|
|
||||||
|
|
||||||
|
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” configuration option
|
## The “env_file” configuration option
|
||||||
|
|
||||||
You can pass multiple environment variables from an external file through to a service's containers with the ['env_file' option](compose-file.md#envfile), just like with `docker run --env-file=FILE ...`:
|
You can pass multiple environment variables from an external file through to
|
||||||
|
a service's containers with the ['env_file' option](compose-file.md#envfile),
|
||||||
|
just like with `docker run --env-file=FILE ...`:
|
||||||
|
|
||||||
web:
|
```yaml
|
||||||
env_file:
|
web:
|
||||||
- web-variables.env
|
env_file:
|
||||||
|
- web-variables.env
|
||||||
|
```
|
||||||
|
|
||||||
|
## Set environment variables with 'docker-compose run'
|
||||||
|
|
||||||
## Setting environment variables with 'docker-compose run'
|
Just like with `docker run -e`, you can set environment variables on a one-off
|
||||||
|
container with `docker-compose run -e`:
|
||||||
|
|
||||||
Just like with `docker run -e`, you can set environment variables on a one-off container with `docker-compose run -e`:
|
```bash
|
||||||
|
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 through from the shell by not giving it a value:
|
||||||
|
|
||||||
docker-compose run -e DEBUG web python console.py
|
```bash
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
## The “.env” 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`:
|
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`:
|
||||||
|
|
||||||
$ cat .env
|
```bash
|
||||||
TAG=v1.5
|
$ cat .env
|
||||||
|
TAG=v1.5
|
||||||
|
|
||||||
$ cat docker-compose.yml
|
$ cat docker-compose.yml
|
||||||
version: '3'
|
version: '3'
|
||||||
services:
|
services:
|
||||||
web:
|
web:
|
||||||
image: "webapp:${TAG}"
|
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:
|
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:
|
||||||
|
|
||||||
$ docker-compose config
|
```bash
|
||||||
version: '3'
|
$ docker-compose config
|
||||||
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:
|
version: '3'
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
image: 'webapp:v1.5'
|
||||||
|
```
|
||||||
|
|
||||||
$ export TAG=v2.0
|
Values in the shell take precedence over those specified in the `.env` file.
|
||||||
$ docker-compose config
|
If you set `TAG` to a different value in your shell, the substitution in `image`
|
||||||
version: '3'
|
uses that instead:
|
||||||
services:
|
|
||||||
web:
|
|
||||||
image: 'webapp:v2.0'
|
|
||||||
|
|
||||||
When values are provided both with a shell `environment` variable and with an `env_file` configuration file, values of environment variables is taken **from environment key first and then from environment file, then from a `Dockerfile` `ENV`–entry**:
|
```bash
|
||||||
|
$ export TAG=v2.0
|
||||||
|
$ docker-compose config
|
||||||
|
|
||||||
$ cat ./Docker/api/api.env
|
version: '3'
|
||||||
NODE_ENV=test
|
services:
|
||||||
|
web:
|
||||||
|
image: 'webapp:v2.0'
|
||||||
|
```
|
||||||
|
|
||||||
$ cat docker-compose.yml
|
When values are provided both with a shell `environment` variable and with an
|
||||||
version: '3'
|
`env_file` configuration file, values of environment variables is taken
|
||||||
services:
|
from environment key first and then from environment file, then from a
|
||||||
api:
|
`Dockerfile` `ENV`–entry:
|
||||||
image: 'node:6-alpine'
|
|
||||||
env_file:
|
|
||||||
- ./Docker/api/api.env
|
|
||||||
environment:
|
|
||||||
- NODE_ENV=production
|
|
||||||
|
|
||||||
You can test this with a command like the following command that starts a _NodeJS_ container in the CLI:
|
```bash
|
||||||
|
$ cat ./Docker/api/api.env
|
||||||
|
NODE_ENV=test
|
||||||
|
|
||||||
$ docker-compose exec api node
|
$ cat docker-compose.yml
|
||||||
> process.env.NODE_ENV
|
version: '3'
|
||||||
'production'
|
services:
|
||||||
|
api:
|
||||||
|
image: 'node:6-alpine'
|
||||||
|
env_file:
|
||||||
|
- ./Docker/api/api.env
|
||||||
|
environment:
|
||||||
|
- NODE_ENV=production
|
||||||
|
```
|
||||||
|
|
||||||
Having any `ARG` or `ENV` setting in a `Dockerfile` evaluates only if there is _no_ Docker _Compose_ entry for `environment` or `env_file`.
|
You can test this with a command like the following command that starts a
|
||||||
|
_NodeJS_ container in the CLI:
|
||||||
|
|
||||||
_Spcecifics for NodeJS containers:_ If you have a `package.json` entry for `script:start` like `NODE_ENV=test node server.js`, then this overrules _any_ setting in your `docker-compose.yml` file.
|
```bash
|
||||||
|
$ docker-compose exec api node
|
||||||
|
|
||||||
## Configuring Compose using environment variables
|
> process.env.NODE_ENV
|
||||||
|
'production'
|
||||||
|
```
|
||||||
|
|
||||||
Several environment variables are available for you to configure the Docker Compose command-line behaviour. They begin with `COMPOSE_` or `DOCKER_`, and are documented in [CLI Environment Variables](reference/envvars.md).
|
Having any `ARG` or `ENV` setting in a `Dockerfile` evaluates only if there is
|
||||||
|
no Docker Compose entry for `environment` or `env_file`.
|
||||||
|
|
||||||
|
> Spcecifics for NodeJS containers
|
||||||
|
>
|
||||||
|
> If you have a `package.json` entry for `script:start` like
|
||||||
|
> `NODE_ENV=test node server.js`, then this overrules any setting in your
|
||||||
|
> `docker-compose.yml` file.
|
||||||
|
|
||||||
|
## Configure Compose using environment variables
|
||||||
|
|
||||||
|
Several environment variables are available for you to configure the Docker
|
||||||
|
Compose command-line behavior. They begin with `COMPOSE_` or `DOCKER_`, and are
|
||||||
|
documented in [CLI Environment Variables](reference/envvars.md).
|
||||||
|
|
||||||
## Environment variables created by links
|
## Environment variables created by links
|
||||||
|
|
||||||
When using the ['links' option](compose-file.md#links) in a [v1 Compose file](compose-file.md#version-1), environment variables are created for each link. They are documented in
|
When using the ['links' option](compose-file.md#links) in a
|
||||||
the [Link environment variables reference](link-env-deprecated.md). However, these variables are deprecated. Use the link alias as a hostname instead.
|
[v1 Compose file](compose-file.md#version-1), environment variables are created
|
||||||
|
for each link. They are documented in
|
||||||
|
the [Link environment variables reference](link-env-deprecated.md).
|
||||||
|
|
||||||
|
However, these variables are deprecated. Use the link alias as a hostname instead.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue