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
の値とする
同様に、以下の構文を使えば、特定の値を
${変数:?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