From cc6762ecd3a3e193cf6d042380d98a0925c598d4 Mon Sep 17 00:00:00 2001 From: Anca Iordache Date: Tue, 23 Mar 2021 22:42:08 +0100 Subject: [PATCH] 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 * Minor style edits * Minor style edits Co-authored-by: Usha Mandya <47779042+usha-mandya@users.noreply.github.com> --- compose/env-file.md | 22 ++-- compose/environment-variables.md | 166 ++++++++++++++++++++----------- compose/index.md | 4 + 3 files changed, 129 insertions(+), 63 deletions(-) diff --git a/compose/env-file.md b/compose/env-file.md index 2cf75c4c09..2e44989926 100644 --- a/compose/env-file.md +++ b/compose/env-file.md @@ -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 diff --git a/compose/environment-variables.md b/compose/environment-variables.md index 0a392d9f2f..fd0b240e5e 100644 --- a/compose/environment-variables.md +++ b/compose/environment-variables.md @@ -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 diff --git a/compose/index.md b/compose/index.md index 988ca0becf..9ebd9f9794 100644 --- a/compose/index.md +++ b/compose/index.md @@ -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`