Compose 設定をファイルとプロジェクト間で共有¶

共通する設定を共有するため、 Compose は２つの方法をサポートしています。

複数の Compose ファイルを使い、Compose ファイル全体を拡張
「extends」フィールドで個々のサービスを拡張（Compose ファイルバージョン 2.1 以上）

複数の Compose ファイル ¶

複数の Compose ファイルを使えば、異なる環境や異なるワークフローごとに、 Compose アプリケーションをカスタマイズできます。

デフォルトでは、 Compose は２つのファイルを読み込みます。１つは docker-compose.yml で、もう１つはオプションで docker-compose.override.yml ファイルです。習慣として、 docker-compose.yml に基本となる設定を入れます。上書き(override) ファイルは、その名前が意味する通り、既存のサービスや新しいサービス全体の設定を上書きする設定を含められます。

両方のファイルでサービスが定義されると、 Compose は設定の追加と上書きに記述してある規則を使い、設定を統合します。

複数の上書きファイルを使う場合や、異なる名前の上書きファイルを使う場合は、 -f オプションを使ってリストやファイルを指定できます。コマンドライン上で指定した順番で、Compose はそれらのファイルを統合します。 -f を使う詳しい情報は docker-compose コマンドリファレンスをご覧ください。

複数の設定ファイルを使う場合、全ファイルのパスが基本となる Compose ファイル（ -f で１番目に指定した Comopse ファイル）からの相対パスになるので、注意が必要です。注意が要るのは、上書きするファイルは正しい Comopse ファイルである必要がないためです。サービスの一部を追跡するにあたり、相対パスは複雑で混乱するため、パスを分かりやすくするためには、全てのパスを基本ファイルからの相対パスとして指定すべきです。

使用例 ¶

このセクションには、複数の Compose ファイルを使う一般的な使用例が２つあります。異なる環境で Compose アプリを変えるものと、Compose アプリに対して管理用タスクを実行するものです。

異なる環境 ¶

複数のファイルを使う一般的な利用例は、開発用 Compose アプリを本番のような環境用（本番や、ステージングや、CI など）に変える場合です。環境の違いに対応するには、 Comopse 設定を複数の異なるファイルに分割できます。

各サービスに対する標準的な設定を定義するベースファイル(base file) から始めましょう。

docker-compose.yml

web:
  image: example/my_web_app:latest
  depends_on:
    - db
    - cache

db:
  image: postgres:latest

cache:
  image: redis:latest

この例にある開発用の設定では、ホスト上のいくつかのポートを公開し、ボリュームとしてコードをマウントし、web イメージを構築します。

docker-compose.override.yml

web:
  build: .
  volumes:
    - '.:/code'
  ports:
    - 8883:80
  environment:
    DEBUG: 'true'

db:
  command: '-d'
  ports:
    - 5432:5432

cache:
  ports:
    - 6379:6379

docker-compose up を実行すると、上書きファイルを自動的に読み込みます。

これで、この Compose アプリを本番環境でも使えるようになりました。あとは、他の上書きファイル（異なる git リポジトリに保管されるかもしれませんし、他のチームによって管理されるかもしれません）を作成します。

docker-compose.prod.yml

web:
  ports:
    - 80:80
  environment:
    PRODUCTION: 'true'

cache:
  environment:
    TTL: '500'

この本番用 Compose ファイルでデプロイするには、次のように実行します。

$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

これは docker-compose.yml と docker-compose.prod.yml （開発用の設定 docker-compose.override.yml ではありません）の設定を使い、設定された３つのサービスすべてをデプロイします。

Compose を本番環境で使うための情報は本番環境をご覧ください。

管理用タスク ¶

他の一般的な利用例は、 Compose アプリ内のサービスに対して、一時的または管理的なタスクを１つまたは複数実行する場合です。

docker-compose.yml から始めます。

web:
  image: example/my_web_app:latest
  depends_on:
    - db

db:
  image: postgres:latest

docker-compose.admin.yml には、データベースの出力(export) やバックアップを実行する新しいサービスを追加します。

dbadmin:
  build: database_admin/
  depends_on:
    - db

docker-compose up -d を実行して、通常の環境を起動します。データベースのバックアップを実行するには、 docker-compose.admin.yaml も同様に含めます。

$ docker-compose -f docker-compose.yml -f docker-compose.admin.yml \
  run dbadmin db-backup

サービスの拡張(extends)¶

注釈

extends （拡張）キーワードは、初期の Compose ファイル形式から Compose ファイルバージョン 2.1 （ v2 の extends を参照）までサポートされていましたが、Compose バージョン 3.x ではサポートされていません。バージョン 3 概要でのキー追加と削除に加え、アップグレードの仕方をご覧ください。将来の形式で同じように extends をサポートする可能性についての議論は、 moby/moby#31101 をご覧ください。 extends キーワードは、 docker-compose バージョン 1.27 以上から含まれるようになりました。

Docker Compose の extends キーワードは、共通の設定を異なるファイル間で共有できます。また、全く異なるプロジェクトでさえも共有できます。サービスの拡張(extends) は、共通する設定オプション群を持つ、複数のサービスがある場合に役立ちます。 extends を使えば、１箇所で共通するサービスのオプション群を設定できますし、どこからでも参照できます。

注意点として、 volumes_from と depends_on は、 extends を使うサービス間で決して共有されません。これは潜在的な依存関係を防ぐために、例外終了します。つまり、 volumes_from は常にローカルで定義しなくてはいけません。これにより、現在のファイルを読み込む時に、サービスの依存関係が明確に表示されます。また、これら（ボリューム）をローカルで定義するため、参照しているファイルを変更したとても、一切影響がありません。

extends 設定の理解 ¶

docker-compose.yml であらゆるサービスを定義する時に、次のように、他のサービスを拡張するよう宣言できます。

services:
  web:
    extends:
      file: common-services.yml
      service: webapp

これは Compose に対し、 common-services.yml ファイル内で定義された webapp サービスの設定を再利用するように命令します。 common-services.yml は、このような内容を想定しています。

services:
  webapp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - "/data"

このようにすると、 docker-compose.yml 内の web 以下で、同じ build 、 ports 、 volumes 設定を定義した場合と結果が完全に同じになります。

docker-compose.yml 内では、さらに続けてローカルの設定を定義（あるいは再定義）できます。

services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5

  important_web:
    extends: web
    cpu_shares: 10

また、他のサービスを記述し、 web サービスに対してサービスをリンクできます。

services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5
    depends_on:
      - db
  db:
    image: postgres

利用例 ¶

複数のサービスが共通の設定を持つ場合、個々のサービスを拡張するのが便利です。以下の例にある Compose アプリは、ウェブ(web) アプリケーションとキューワーカ(queue worker) という、２つのサービスがあります。どちらのサービスも、同じコードベースを使い、多くの設定オプションを共有します。

common.yml 内には、共通する設定を定義します。

services:
  app:
    build: .
    environment:
      CONFIG_FILE_PATH: /code/config
      API_KEY: xxxyyy
    cpu_shares: 5

docker-compose.yml 内には、共通する設定を使う具体的なサービスを定義します。

services:
  webapp:
    extends:
      file: common.yml
      service: app
    command: /code/run_web_app
    ports:
      - 8080:8080
    depends_on:
      - queue
      - db

  queue_worker:
    extends:
      file: common.yml
      service: app
    command: /code/run_worker
    depends_on:
      - queue

設定情報の追加と上書き ¶

Compose はオリジナルのサービスにある設定情報を、ローカルの設定情報へとコピーします。設定情報のオプションがオリジナルサービスとローカルサービスの両方で定義されている場合、ローカルの値は「置き換え(replaces) 」られるか、オリジナルの値が「拡張(extends) 」されます。

image 、 command 、 mem_limit のようにオプションが単一の値を持つ場合、古い値を新しい値で置き換えます。

オリジナルサービス：

services:
  myservice:
    # ...
    command: python app.py

ローカルサービス：

services:
  myservice:
    # ...
    command: python otherapp.py

結果：

services:
  myservice:
    # ...
    command: python otherapp.py

ports 、 expose 、 external_links 、 dns 、 dns_search 、 tmpfs のような 複数の値を持つオプション では、Compose は両方の値を連結します。

services:
  myservice:
    # ...
    expose:
      - "3000"

ローカルサービス：

services:
  myservice:
    # ...
    expose:
      - "4000"
      - "5000"

結果：

services:
  myservice:
    # ...
    expose:
      - "3000"
      - "4000"
      - "5000"

environment 、 labels 、 volumes 、 devices では、 Compose はローカルで定義した値を優先しながら、全体を「統合(merge) 」します。 environment と labels では、環境変数の値やラベル名で明示された値が使われます。

オリジナルサービス：

services:
  myservice:
    # ...
    environment:
      - FOO=original
      - BAR=original

ローカルサービス：

services:
  myservice:
    # ...
    environment:
      - BAR=local
      - BAZ=local

結果：

services:
  myservice:
    # ...
    environment:
      - FOO=original
      - BAR=local
      - BAZ=local

voluems と devices のエントリは、コンテナ内にマウントするパスを使う場合に統合(merge) されます。

オリジナルサービス：

services:
  myservice:
    # ...
    volumes:
      - ./original:/foo
      - ./original:/bar

ローカルサービス：

services:
  myservice:
    # ...
    volumes:
      - ./local:/bar
      - ./local:/baz

結果：

services:
  myservice:
    # ...
    volumes:
      - ./original:/foo
      - ./local:/bar
      - ./local:/baz

Compose ドキュメント ¶

参考

Share Compose configurations between files and projects: https://docs.docker.com/compose/extends/