diff --git a/compose/environment-variables.md b/compose/environment-variables.md index df93a9fec9..e10a0733de 100644 --- a/compose/environment-variables.md +++ b/compose/environment-variables.md @@ -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 +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: - image: "webapp:${TAG}" +```yaml +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: - environment: - - DEBUG=1 +```yaml +web: + 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 ...`: - - 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. +```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. ## 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: - env_file: - - web-variables.env +```yaml +web: + 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`: - - docker-compose run -e DEBUG=1 web python console.py +```bash +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: - 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 -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 - TAG=v1.5 +```bash +$ cat .env +TAG=v1.5 - $ cat docker-compose.yml - version: '3' - services: - web: - image: "webapp:${TAG}" +$ 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: +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 - version: '3' - services: - web: - image: 'webapp:v1.5' +```bash +$ docker-compose config -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 - $ docker-compose config - version: '3' - services: - web: - image: 'webapp:v2.0' +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: -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 - NODE_ENV=test +version: '3' +services: + web: + image: 'webapp:v2.0' +``` - $ cat docker-compose.yml - version: '3' - services: - api: - image: 'node:6-alpine' - env_file: - - ./Docker/api/api.env - environment: - - NODE_ENV=production +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: -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 - > process.env.NODE_ENV - 'production' +$ cat docker-compose.yml +version: '3' +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 -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 -the [Link environment variables reference](link-env-deprecated.md). However, these variables are deprecated. Use the link alias as a hostname instead. +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 +the [Link environment variables reference](link-env-deprecated.md). + +However, these variables are deprecated. Use the link alias as a hostname instead.