Compose 内の環境変数¶

様々な用途のために、Compose の複数の場面で環境変数を扱います。このページは必要な情報を探すのに役立つでしょう。

Compose ファイルで環境変数を展開 ¶

環境変数を使えば、Compose ファイル内にシェル上の環境変数を投入（変数展開）できます。

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

複数の環境変数がある場合、デフォルトでは .env というファイル名で展開したい変数を記述できます。あるいは、 --env-file コマンドラインのオプションを使って、環境変数ファイルのパスを指定できます。

設定のオプションに、環境変数の値を含められます。Compose は実行時、 docker compose を実行するシェルの環境変数にある値を使います。たとえば、シェル（の環境変数）に POSTGRES_VERSION=9.3 を含んでいるとすると、これを設定に対応させられます。

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

この設定を docker compose up で使うと、 Compose はシェル内の POSTGRES_VERSION 環境変数の値を探し、その値を展開します。この例では、 Compose は設定を使って実行する前に、 image を postgres:9.3 と解釈します。

環境変数の値が無い場合は、 Compose は空の文字列を投入します。先の例では、 POSTGRES_VERSION の値が設定されていなければ、 image オプションの値は postgres: となります。

.env ファイルファイルを使えば、環境変数のデフォルト値を設定できます。この .env ファイルは、 Compose がプロジェクトのディレクトリ内（Compose ファイルがある親ディレクトリ）を自動的に探します。シェル環境変数の値は、 .env ファイルで設定された値よりも優先されます。

警告

docker stack deploy 時の注意

.env ファイル機能が動作するのは docker compose up コマンドを使った時のみであり、 docker stack deploy では機能しません。

$変数 と ${変数} 構文をサポートしています。加えて、 2.1 ファイル形式を使う場合は、典型的なシェル構文を使い、デフォルト値を変数内に展開できます。

${変数:-default} は、 変数 が設定されていないか、環境変数の値が空の場合、 default の値とする
${変数-default} は、環境変数内で 変数 が設定されていない場合のみ、 default の値とする

同様に、以下の構文を使えば、特定の値を必須に(mandatory) できます。

${変数:?err} は、 変数 が設定されていないか、環境変数の値が空の場合、 err を含むエラーメッセージと共に終了する
${変数?err} は、環境変数内で 変数 が設定されていない場合に、 err を含むエラーメッセージと共に終了する

ただし、${変数/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.

`.env` ファイル ¶

あらゆる環境変数から参照できるデフォルト値を設定できます。そのためには、 Compose ファイル内で、または、 .env という名前の環境設定ファイル内の設定を使います。 .env ファイルのパスは、以下のように扱います。

v1.28 以上は、 .env ファイルはプロジェクトがあるディレクトリのベースにあります。
プロジェクトディレクトリは、 --file オプションや COMPOSE_FILE 環境変数の値で明示できます。明示されなければ、 docker compose コマンドを実行する現在の作業ディレクトリとみなします（ v1.28 以上）。
以前のバージョンでは、 .env ファイルと --file や COMPOSE_FILE を使うと問題が起こる可能性があります。正しく動かすためには、 --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 になります。これを確認するには convert コマンドが利用でき、アプリケーションが解釈した設定をターミナル上に表示します。

$ docker compose convert

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

それぞれの .env ファイル内で指定された値よりも、シェル上の値が優先されます。

TAG に対してシェル上で異なる値を指定すると、 image は代わりにこちらを展開します。

$ export TAG=v2.0
$ docker compose convert

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

コマンドラインで引数 --env-file を使い、環境変数ファイルのパスを上書きできます。

`--env-file` オプションを使う ¶

引数としてファイルのパスを指定できるため、環境変数のファイルをどこにでも置けますし、適切な名前を付けられます。たとえば、 .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 convert
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

詳しい情報は、 Compose ファイルリファレンス内の変数の置き換えをご覧ください。

コンテナ内での環境変数を指定 ¶

サービス用のコンテナ内での環境変数は 'environment' キーで設定できます。これは docker run -e VARIABLE=VALUE ... のようなものです。

web:
  environment:
    - DEBUG=1

環境変数をコンテナ内に通す ¶

シェル上の環境変数をサービス用のコンテナに対して直接通すには、 'environment' キーで値を指定せずに使います。これは ``docker run -e VARIABLE ... `` のようなものです。

web:
  environment:
    - DEBUG

コンテナ内での DEBUG 変数の値は、Compose を実行したシェル上における、同じ環境変数の値をとります。

`env_file` 設定オプション ¶

サービス用のコンテナに対して 'env_file' オプションを使えば、外部ファイルを通して複数の環境変数を渡せます。これは、 ``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

また、シェルの環境変数は値を指定しなければ、（コンテナの中に環境変数）渡せます。

$ docker compose run -e DEBUG web python console.py

コンテナ内での DEBUG 変数の値は、 Compose を実行したシェル上での、同じ変数の値になります。

複数のファイルで同じ環境変数がある場合、Compose は使用する値を選ぶため、以下の優先度で使います。

Compose ファイル
シェル環境変数
環境変数ファイル
Dockerfile
変数が定義されていない

以下の例では、環境設定ファイル上と 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'

Dockerfile での ARG と ENV が処理されるのは、 Docker Compose の environement や env_file での指定が無い場合のみです。

注釈

NodeJS コンテナに対する指定

package.json で、 NODE_ENV=test node server.js のような script:start エントリがある場合、 docker-compose.yml ファイルでのあらゆる設定が無効になります。

Compose が使う環境変数の設定 ¶

Docker Compose のコマンドラインでの挙動を設定するため、いくつかの環境変数があります。それらは COMPOSE_ や DOCKER_ で始まるもので、 CLI 環境変数で文書化しています。

参考

Environment variables in Compose: https://docs.docker.com/compose/environment-variables/