Environment variables in Compose

本节代码参见compose-test

1. Substitute environment variables in Compose files

It’s possible to use environment varibles in your shell to populate values inside a Compose file:

web: 
  image: "webapp:${TAG}"

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 enviroment variables file using the --env-file command line option

If an environment variable is not set, Compose substitutues with an empty string. In the example above, if TAG is not set, the value for the image option is webapp:

You can set default values for environment variables using a .env file, which Compose automatically looks for in project directory (parent folder of your Compose file). Values set in the shell enviroment override those set in the .env file

Note when using docker stack deploy

The .env file feature only works when you use the docker-compose up command and does not work with docker stack deploy.

Both $VARIABLE and ${VARIABLE} syntax are supported. Additionally when using the 2.1 file format, it is possible to provide inline default values using typical shell syntax:

• ${VARIBALE:-default}: evaluates to default if VARIABLE is uset or empty in the environment
• ${VARIABLE-default}: evaluates to default only if VARIABLE is unset in the environment

Other extended shell-syntax features, such as ${VARIABLE/foo/bar}, are not supported

You can use a $$ (double-dollar sign) when your configuration needs a literal dollar sign. This also prevents Compose from interpolating a value, so a $$ allows you to refer to enviroment variables that you don’t want processed by Compose

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

If you foget and use a single dollar sign, Compose interprets the value as an environment variable and warns you:

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.

2. .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 named .env. The path is as follows:

• Starting with +v1.28, .env file is placed at the base of the project directory
• Project directory can be explicitly defined with the --file option or COMPOSE_FILE environment variable. Otherwise, it is the current working directory where the docker compose command is executed (+1.28).
• For previous versions, it might have trouble resolving .env file with --file or COMPOSE_FILE. To work around it, it is recommended to use --project-directory, which overrides the path for the .env file. This inconsistency is addressed in +v1.28 by limiting the filepath to the project directory

You can verify this with the config command, which prints your resolved application config to the terminal

$ 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 uses that instead

2.1 Using the --env-file option

You can override the environment file path using a command line argument --env-file

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 done using the --env-file option:

$ docker compose --env-file ./.env.prod config

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

3. Set environment variables in containers

You can set environment variables in a service’s containers with the environment key

web:
  environment:
    - DEBUG=1

3.1 Pass environment variables to containers

ou can pass environment variables from your shell straight through to a service’s containers with the 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.

// TODO: complete it later ,2021-12-18