Compose における環境変数

読む時間の目安: 3 分

Compose の複数の場面において環境変数がさまざまに用いられています。このページでは環境変数について必要となる情報を示します。

Compose ファイル内での環境変数の利用

シェル内にて環境変数を設定し、その値を Compose ファイルにおいて読み込ませることができます。

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

環境変数が複数ある場合、.envという名前のファイルに環境変数のデフォルト値を設定することができます。あるいはコマンドラインオプション--env-fileを使って環境変数ファイルへのパスを指定して利用することもできます。

`.env`ファイル

Compose ファイルが参照する環境変数、あるいは Compose の設定に用いられる環境変数のデフォルト値を設定することができます。これは.envという環境ファイルにて行います。 .envファイルのパスは以下のとおりです。

Compose バージョンv1.28以降は、.envファイルはプロジェクトのベースディレクトリに置くようになりました。
それ以前のバージョンの場合は、Docker Compose コマンドが実行されたカレントワーキングディレクトリに置きます。ただし--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'

シェル内にて設定される値は、.envファイル内のものよりも優先されます。

たとえばシェル上においてTAGを異なる値に設定していたら、それを使って変数置換されたimageが用いられることになります。

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

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 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引数として指定された場合、Compopse は以下のようなエラーを返します。

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

詳しくは Compose ファイルリファレンスの変数の置換の項を参照してください。

コンテナー内での環境変数の設定

サービスコンテナーにおいて、たとえばdocker run -e VARIABLE=VALUE ...のように environmentキーを使って、環境変数を設定することができます。

web:
  environment:
    - DEBUG=1

コンテナーへの環境変数の受け渡し

シェル内の環境変数を environmentキーを使って、直接サービスコンテナーに受け渡すことができます。この場合には値を渡すのではなくdocker run -e 変数名 ...のようにできます。

web:
  environment:
    - DEBUG

コンテナー内の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変数は、シェル内の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は、environmentやenv_fileによる Docker Composeの設定がある場合は評価されません。

NodeJS コンテナーの仕様

script:startに対してpackage.jsonのエントリーを含む場合、たとえばNODE_ENV=test node server.jsのような場合には、docker-compose.ymlファイルでの設定よりもこちらの設定が優先されます。

環境変数を用いた Compose の設定

Docker Compose のコマンドラインからの処理設定を行うことができる環境変数がいくつかあります。そういった変数は先頭がCOMPOSE_やDOCKER_で始まります。詳しくは CLI 環境変数を参照してください。

compose, orchestration, environment, env file

Compose における環境変数

Compose ファイル内での環境変数の利用

.envファイル

--env-fileオプションの利用