Environment variables in Compose

预计阅读时间:8分钟

Compose 有多个部分在某种意义上处理环境变量. 此页面应该可以帮助您找到所需的信息.

Substitute environment variables in Compose files

可以在 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 会在 shell 中查找POSTGRES_VERSION环境变量并将其值代入.对于此示例,Compose 在运行配置之前将image解析为postgres:9.3 .

如果未设置环境变量,Compose 将替换为空字符串. 在上面的示例中,如果未设置POSTGRES_VERSION ,则image选项的值为postgres: .

您可以使用.env文件为环境变量设置默认值,Compose 会自动在项目目录(Compose 文件的父文件夹)中查找该文件. 在 shell 环境中设置的值会覆盖在.env文件中设置的值.

使用 docker stack deploy 时的注意事项

.env file功能仅在您使用 docker docker-compose up命令时有效,不适用于docker stack deploy .

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

  • 如果VARIABLE在环境中未设置或为空,则${VARIABLE:-default}评估为default .
  • 只有在环境中未设置VARIABLE${VARIABLE-default}才会评估为default .

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

  • 如果VARIABLE在环境中未设置或为空,则${VARIABLE:?err}退出并显示包含err的错误消息.
  • 如果在环境中未设置VARIABLE ,则${VARIABLE?err}退出并显示包含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环境文件中为 Compose 文件中引用或用于配置 Compose 的任何环境变量设置默认值. .env文件路径如下:

  • Starting with +v1.28, .env file is placed at the base of the project directory
  • 可以使用--file选项或COMPOSE_FILE环境变量显式定义项目目录. 否则,它是执行 docker docker compose命令的当前工作目录( +1.28 ).
  • 对于以前的版本,它可能无法使用--fileCOMPOSE_FILE解析.env文件. 要解决此问题,建议使用--project-directory ,它会覆盖.env文件的路径. +v1.28通过将文件路径限制为项目目录来解决此不一致问题.
$ cat .env
TAG=v1.5

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

当您运行docker-compose up ,上面定义的web服务使用图像webapp:v1.5 . 您可以使用config 命令验证这一点,该命令会将您解析的应用程序配置打印到终端:

$ docker-compose config

version: '3'
services:
  web:
    image: 'webapp:v1.5'

shell 中的值优先于.env文件中指定的值.

如果您在 shell 中将TAG设置为不同的值,则image中的替换将使用该值:

$ export TAG=v2.0
$ docker-compose config

version: '3'
services:
  web:
    image: 'webapp:v2.0'

您可以使用命令行参数--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 命令的当前工作目录.

$ cat .env
TAG=v1.5

$ cat ./config/.env.dev
TAG=v1.6


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

.env文件默认加载:

$ docker-compose config 
version: '3'
services:
  web:
    image: 'webapp:v1.5'

传递--env-file参数会覆盖默认文件路径:

$ docker-compose --env-file ./config/.env.dev config 
version: '3'
services:
  web:
    image: 'webapp:v1.6'

当一个无效的文件路径作为--env-file参数传递时,Compose 会返回一个错误:

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

有关详细信息,请参阅撰写文件参考中的变量替换部分.

Set environment variables in containers

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

web:
  environment:
    - DEBUG=1

Pass environment variables to containers

您可以使用'environment' 键将环境变量从 shell 直接传递到服务的容器,方法是不给它们一个值,就像使用docker run -e VARIABLE ...一样:

web:
  environment:
    - DEBUG

容器中DEBUG变量的值取自运行 Compose 的 shell 中相同变量的值.

The “env_file” configuration option

您可以使用'env_file' 选项将多个环境变量从外部文件传递到服务的容器,就像使用docker run --env-file=FILE ...一样:

web:
  env_file:
    - web-variables.env

Set environment variables with ‘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. 编写文件
  2. 外壳环境变量
  3. 环境文件
  4. Dockerfile
  5. 变量未定义

在下面的示例中,我们在 Environment 文件和 Compose 文件上设置了相同的环境变量:

$ 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

运行容器时,Compose 文件中定义的环境变量优先.

$ docker-compose exec api node

> process.env.NODE_ENV
'production'

仅当environmentenv_file没有 Docker Compose 条目时,在Dockerfile中有任何ARGENV设置才会评估.

NodeJS 容器的细节

如果你有一个script:startpackage.json条目,比如NODE_ENV=test node server.js ,那么这docker-compose.yml文件中的任何设置.

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 环境变量.

compose, orchestration, environment, 环境文件

by  icopy.site