Environment variables in Compose

Docker Compose CLI环境变量主要用来配置Docker Compose命令行的行为。以DOCKER_开头的变量与用于配置Docker命令行客户端的那些变量效果相同。注意也可以使用环境文件来提供其中的一些变量 。

在 Compose 文件中替换环境变量

可以在 shell 中使用环境变量来填充 Compose 文件中的值:

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

如果有多个环境变量，可以通过将它们添加到名为.env的默认环境变量文件中来替换它们。或者使用--env-file命令行选项提供环境变量文件的路径来替换它们
您的配置选项可以包含环境变量。Compose使用运行docker-compose的shell环境中的变量值。例如假设 shell 包含POSTGRES_VERSION=9.3并且您提供以下配置:

db:
  image: "postgres:${POSTGRES_VERSION}"

当您docker-compose up使用此配置运行时，Compose POSTGRES_VERSION会在 shell 中查找环境变量并将其值代入其中。对于此示例，Compose在运行配置之前将其解析image为postgres:9.3。
如果未设置环境变量，Compose 将替换为空字符串。在上面的示例中，如果POSTGRES_VERSION未设置，则image选项的值为postgres:。
您可以使用.env文件设置环境变量的默认值，composer自动在项目目录(Compose文件的父文件夹)中查找。在shell环境中设置的值会覆盖.env文件中设置的值。

使用 “docker stack deploy” 时的注意事项
该.env file功能仅在您使用docker-compose up命令时有效，不适用于docker stack deploy

支持$VARIABLE和${VARIABLE}语法。此外当使用2.1文件格式时，可以使用典型的shell语法提供内联默认值:

${VARIABLE:-default}  如果环境中的VARIABLE未设置或为空，则计算为default
${VARIABLE-default}   仅当VARIABLE在环境中未设置时，才计算为default

同样，以下语法允许您指定强制变量:

${VARIABLE:?err}	  如果环境中的VARIABLE未设置或为空，则退出并显示包含err的错误消息
${VARIABLE?err}		  如果VARIABLE在环境中未设置，则退出并显示包含err的错误消息

不支持其他扩展shell风格的功能，如${VARIABLE/foo/bar}
当您的配置需要真正的美元符号时，您可以使用$$(双美元符号)。这也可以防止 Compose 插入值，因此$$允许您引用不希望由Compose处理的环境变量

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

如果您忘记并使用了一个美元符号($)，Compose会将该值解释为环境变量并警告您:

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.

The .env file

您可以在名为.env的environment file中为合成文件中引用的或用于配置合成的任何环境变量设置默认值。这个.env文件路径如下:
• 从+1.28开始，.env文件位于项目目录的底部
• 可以使用 --file 选项或COMPOSE_FILE环境变量显式定义项目目录。否则它就是执行docker compose命令的当前工作目录(+1.28)
• 对于以前的版本带有 --file 或COMPOSE_FILE的env文件可能会有问题。要解决这个问题，建议使用 --project-directory ，它会重写环境文件。在+v1.28中，通过将“文件路径限制为项目目录”，解决了这种不一致性

$ cat .env
TAG=v1.5
$ cat docker-compose.yml
version: '3'
services: 
  web: 
    image: "webapp:${TAG}"

当您运行docker compose up时，上面定义的web服务使用image webapp:v1.5。您可以使用convert命令来验证这一点，该命令将您解析的应用程序配置打印到终端: [convert将合成文件转换为平台的规范格式]

docker compose convert
version: '3'
services: 
  web: 
    image: "webapp:v1.5"

shell中的值优先于.env文件中指定的值。如果您在shell中将TAG设置为不同的值，image中的替换将使用该值，您可以使用命令行参数 --env-file 覆盖环境文件路径。

Using the --env-file option

通过将文件作为参数传递，您可以将其存储在任何位置并适当地命名，例如.env.ci、.env.dev、.env.prod。传递文件路径是使用 --env-file 选项完成的:

$ docker compose --env-file ./config/.env.dev up 

该文件路径相对于Docker Compose命令执行的当前工作目录
默认情况下加载.env文件，使用 --env-file 参数会覆盖默认文件路径。当一个无效的文件路径作为 --env-file 参数传递时，Compose 会返回一个错误：

$ docker compose --env-file ./doesnotexist/.env.dev config 
ERROR: Couldn't find env file: /home/user/-/doesnotexist/.env.dev

Compose支持在名为的环境文件中声明默认环境变量.env放置在项目目录中。Docker Compose之前的版本，加载执行命令的当前工作目录中的env文件，或者使用 --project-directory 选项显式设置的项目目录中的env文件。从+1.28版开始通过将默认.env文件路径限制为项目目录来解决此不一致问题。。您可以使用 --env-file 命令行选项覆盖默认值.env并指定自定义环境文件的路径。
项目目录按优先顺序指定:
• --project-directory flag
• Folder of the first --file flag
• Current directory

语法规则

下列语法规则适用于.env文件:
• Compose要求env要放入的文件VAR=VAL格式。
• 以…开头的行#作为注释处理并被忽略。
• 空行被忽略。
• 引号没有特殊处理。这意味着它们是 VAL 的一部分

撰写文件和CLI变量

您在此处定义的环境变量用于 Compose 文件中的变量替换 ，也可用于定义以下 CLI 变量：

COMPOSE_API_VERSION
COMPOSE_CONVERT_WINDOWS_PATHS
COMPOSE_FILE
COMPOSE_HTTP_TIMEOUT
COMPOSE_PROFILES
COMPOSE_PROJECT_NAME
COMPOSE_TLS_VERSION
DOCKER_CERT_PATH
DOCKER_HOST
DOCKER_TLS_VERIFY

Note
运行时环境中存在的值总是覆盖.env文件中定义的值。同样，通过命令行参数传递的值也具有优先权
文件中定义的环境变量.env在容器内不会自动可见

在容器中设置环境变量

您可以使用’environment’key在服务的容器中设置环境变量，就像使用docker run -e VARIABLE=VALUE一样…:

web:
  environment:
    - DEBUG=1

将环境变量传递给容器
您可以使用’environment’key将环境变量从您的shell直接传递到服务的容器，不需要给它们赋值，就像docker run -e VARIABLE …:

web:
  environment:
    - DEBUG

容器中DEBUG变量的值取自运行Compose的shell中相同变量的值。
“env_file”配置选项
您可以使用’env_file’option将多个环境变量从外部文件传递到服务的容器，就像docker run --env-file=FILE一样…：

web:
  env_file:
    - web-variables.env

使用 docker compose run 设置环境变量

与docker run -e类似，您可以使用docker compose run -e在一次性容器上设置环境变量:

docker compose run -e DEBUG=1 web python console.py

您还可以通过不给变量赋值来传递shell中的变量:

docker compose run -e DEBUG web python console.py	# 容器中DEBUG变量的值取自运行Compose的shell中相同变量的值。

当您在多个文件中设置相同的环境变量时，以下是Compose用来选择使用哪个值的优先级:
1. Compose file
2. Shell environment variables
3. Environment file
4. Dockerfile
5. Variable is not defined
在下面的示例中，我们在环境文件和合成文件上设置了相同的环境变量:

$ cat ./Docker/api/api.env 
NODE ENV=test
$ cat docker-compose.yml 
version: '3'
services: 
  api: 
    image: 'node:6-alpine'
    env_file:
      - ./Docker/api/api.env 
    environment:
      - NODE_ENV=production

运行容器时，合成文件中定义的环境变量优先:

$ docker compose exec api node
>process.env.NODE_ENV
production

只有在没有environment或env_file的Docker合成条目时，Dockerfile中的任何ARG或ENV设置才会进行评估。

NodeJS容器的细节
如果script:start有一个package.json条目，比如NODE_ENV=test node server.js，那么这将覆盖docker-compose.yml文件中的任何设置。

使用环境变量配置合成

您可以使用几个环境变量来配置 DockerCompose 命令行行为。它们以COMPOSE_或DOCKER_开头，并记录在CLI 环境变量中。

在 Compose 中使用配置文件

配置文件允许通过选择性地启用服务来针对各种用途和环境调整 Compose 应用程序模型。这是通过将每个服务分配给零个或多个配置文件来实现的。如果未分配，则始终启动服务，但如果已分配，则仅在激活配置文件时才启动。
这允许人们在一个docker-compose.yml文件中定义额外的服务，这些服务应该只在特定的场景中启动，例如调试或开发任务。

将配置文件分配给服务

服务通过profiles属性与配置文件相关联，该属性采用一组配置文件名称:

# 在这里，服务frontend和phpmyadmin分别被分配给配置文件frontend和debug，因此只有在它们各自的配置文件被启用时才会启动。
version: "3.9"
services:
  frontend:
    image: frontend
    profiles: ["frontend"]
  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug
  backend:
    image: backend
  db:
    image: mysql

没有profiles属性的服务将始终被启用，即在这种情况下运行docker compose up只会启动backend和db。有效的配置文件名遵循[a-zA-Z0-9][a-zA-Z0-9_.-]+.的正则表达式格式。

Note
您的应用程序的核心服务不应该被分配profiles，因此它们将总是被启用和自动启动。

Enabling profiles

要启用配置文件，请提供 --profile 命令行选项或使用COMPOSE_PROFILES环境变量:

docker compose --profile debug up
COMPOSE_PROFILES=debug docker compose up

上面的命令会在启用debug配置文件的情况下启动应用程序。使用上面的docker-compose.yml文件，这将启动服务后端db和phpmyadmin。通过为COMPOSE_PROFILES环境变量传递多个配置文件标志或逗号分隔的列表，可以指定多个配置文件:

docker compose --profile frontend --profile debug up
COMPOSE_PROFILES=frontend,debug docker compose up

自动启用配置文件和依赖解析

当在命令行上明确指定了具有指定profiles的服务时，它的配置文件将自动启用，因此您不需要手动启用它们。这可以用于一次性服务和调试工具。作为示例考虑以下配置:

version: "3.9"
services:
  backend:
    image: backend

  db:
    image: mysql

  db-migrations:
    image: backend
    command: myapp migrate
    depends_on:
      - db
    profiles:
      - tools
# 将只启动backend和db
docker compose up -d
# 这将通过隐式启用配置文件“tools”来运行db-migration(并在必要时启动db)。
docker compose run db-migrations

但是请记住，docker compose只会在命令行上自动启用服务的配置文件，而不会启用任何依赖关系。这意味着目标服务所depends_on的所有服务都必须有一个公共配置文件，始终启用(通过省略profiles)或显式启用一个匹配的配置文件:

version: "3.9"
services:
  web:
    image: web

  mock-backend:
    image: backend
    profiles: ["dev"]
    depends_on:
      - db

  db:
    image: mysql
    profiles: ["dev"]

  phpmyadmin:
    image: phpmyadmin
    profiles: ["debug"]
    depends_on:
      - db
# 将只启动“web”
docker compose up -d
# 这将通过隐式启用配置文件'dev'启动模拟后端(如果需要db)。
docker compose up -d mock-backend
# 这将失败，因为配置文件“dev”是禁用的
docker compose up phpmyadmin

尽管定位phpmyadmin会自动启用它的概要文件即debug,但它不会自动启用db。即dev所需的配置文件。要解决这个问题，您必须将debug配置文件添加到db服务中:

db:
  image: mysql
  profiles: ["debug", "dev"]

或者显式启用db的配置文件:

## 通过针对phpmyadmin自动启用配置文件“debug”
docker compose --profile dev up phpmyadmin
COMPOSE_PROFILES=dev docker compose up phpmyadmin

Only on the top of the mountain, to see the scenery there