Compose における環境変数

読む時間の目安: 2 分

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

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

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

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

環境変数が複数ある場合、環境変数ファイルへのパスを指定して利用することができます。 docker-composeコマンドを実行すると、デフォルトでそのプロジェクトディレクトリ(Compose ファイルの親ディレクトリ)内の.envというファイルを探します。

ファイル名を引数に与えれば、どこの何というファイルでも指定できます。 たとえば .env.ci.env.dev.env.prod などとすることができます。 ファイルパスの指定は --env-file オプションを使って行います。

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

詳しくは 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 が起動しているシェルのことです。

.envファイル

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

$ 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'

環境変数を複数のファイルなどに設定していた場合に、Compose が値を採用する優先順位は以下のとおりです。

  1. Compose ファイル
  2. シェル内の環境変数
  3. 環境ファイル
  4. Dockerfile
  5. 未定義の変数

以下の例では同一の環境変数を、環境ファイルと 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ファイル内のARGENVは、environmentenv_fileによる Docker Composeの設定がある場合は評価されません。

NodeJS コンテナーの仕様

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

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

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

Compose ファイルバージョン 1 における linksオプション を用いると、各リンクに対する環境変数が生成されます。 ただしこの変数は廃止予定となっています。 リンクはホスト名として利用するようにしてください。

compose, orchestration, environment, env file