Compose ファイル バージョン 2 リファレンス

読む時間の目安: 30 分

リファレンスとガイドライン

ここに示す内容は Compose ファイルフォーマット、バージョン 2 です。

Compose と Docker の互換マトリックス

Compose ファイルフォーマットには 1、2、2.x、3.x という複数のバージョンがあります。 その様子は以下の一覧表に見ることができます。 各バージョンにて何が増えたのか、どのようにアップグレードしたのか、といった詳細については バージョンとアップグレードについてを参照してください。

以下の一覧表は、Compose ファイルのどのバージョンが Docker リリースをサポートしているかを示すものです。

Compose ファイルフォーマット Docker Engine リリース
Compose 仕様 19.03.0 以上
3.8 19.03.0 以上
3.7 18.06.0 以上
3.6 18.02.0 以上
3.5 17.12.0 以上
3.4 17.09.0 以上
3.3 17.06.0 以上
3.2 17.04.0 以上
3.1 1.13.1 以上
3.0 1.13.0 以上
2.4 17.12.0 以上
2.3 17.06.0 以上
2.2 1.13.0 以上
2.1 1.12.0 以上
2.0 1.10.0 以上

この表に示している Compose のファイルフォーマットバージョンに加えて、Compose そのもののリリーススケジュールがあります。 詳しくは Compose リリースに示されています。 しかしファイルフォーマットのバージョンは、個々のリリースに合わせてバージョンアップする必要がありません。 たとえば Compose ファイルフォーマット 3.0 が初めて導入されたのは Compose リリース 1.10.0 ですが、その後のリリースの中で、徐々にバージョンアップを行ってきています。

最新の Compose ファイルフォーマットは Compose 仕様 において定義されていて、Docker Compose 1.27.0 以上 において実装されています。

サービス設定リファレンス

Compose ファイルは YAML 形式のファイルであり、サービス（services）、ネットワーク（networks）、ボリューム（volumes）を定義します。 Compose ファイルのデフォルトパスは./docker-compose.ymlです。

ヒント: このファイルの拡張子は.ymlと.yamlのどちらでも構いません。 いずれでも動作します。

サービスの定義には、対応するサービスを起動する各コンテナーに適用される設定を行ないます。 コマンドラインからdocker runのパラメーターを受け渡すことと、非常によく似ています。 同様に、ネットワークの定義、ボリュームの定義は、それぞれdocker network createとdocker volume createのコマンドに対応づくものです。

docker runに関しても同じことが言えますが、Dockerfile にて指定された CMD、EXPOSE、VOLUME、ENV のようなオプションはデフォルトでは維持されます。したがってdocker-compose.ymlの中で再度設定する必要はありません。

設定を記述する際には環境変数を用いることができます。 環境変数は Bash 風に${VARIABLE}のように記述します。 詳しくは 変数の置換 を参照してください。

このセクションでは、バージョン 2 のサービス定義においてサポートされている設定オプションをすべて説明しています。

blkio_config

サービスのブロック IO に対する制限を行う設定オプションです。

version: "2.4"
services:
  foo:
    image: busybox
    blkio_config:
      weight: 300
      weight_device:
        - path: /dev/sda
          weight: 400
      device_read_bps:
        - path: /dev/sdb
          rate: '12mb'
      device_read_iops:
        - path: /dev/sdb
          rate: 120
      device_write_bps:
        - path: /dev/sdb
          rate: '1024k'
      device_write_iops:
        - path: /dev/sdb
          rate: 30

device_read_bps, device_write_bps

指定されたデバイス上での読み書き操作に対して、秒ごとのバイト上限値を設定します。 設定するリストの各項目には、以下の 2 つのキーが必要です。

  • path、影響を受けるデバイスへのシンボリックパスを指定します。
  • rate、バイト数を表わす整数値、または バイト値 を表現する文字列を指定します。

device_read_iops, device_write_iops

指定されたデバイス上での読み書き操作に対して、秒ごとの操作上限値を設定します。 設定するリストの各項目には、以下の 2 つのキーが必要です。

  • path、影響を受けるデバイスへのシンボリックパスを指定します。
  • rate、許容する操作数を表わす整数値を指定します。

weight

他のサービスと比べたときの、当サービスに割り当てる処理性能比を設定します。 10 から 1000 までの整数値を割り当てるもので、デフォルト値は 500 です。

weight_device

デバイスへの処理割り当て量を調整します。 設定するリストの各項目には以下の 2 つのキーが必要です。

  • path、影響を受けるデバイスへのシンボリックパスを指定します。
  • weight、10 から 1000 までの整数値を指定します。

build

この設定オプションはビルド時に適用されます。

build の指定は 1 つには、ビルドコンテキストへのパスを表わす文字列を指定します。

version: "2.4"
services:
  webapp:
    build: ./dir

あるいは コンテキスト 内にあるパスを指定したオブジェクトとし、必要に応じて Dockerfile や 引数 を指定します。

version: "2.4"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1

buildに加えてimageも指定した場合、Compose はビルドイメージに名前をつけます。 たとえば以下のようにimageを指定すると、イメージ名をwebapp、オプションのタグをtagという名前にします。

build: ./dir
image: webapp:tag

結果としてイメージ名はwebappでありtagというタグづけが行われます。 そしてこのイメージは./dirから作り出されます。

context

ファイルフォーマットバージョン 2.0 において追加されました。

Dockerfile を含むディレクトリへのパスか、あるいは git リポジトリの URL を設定します。

設定された記述が相対パスを表わしている場合、Compose ファイルのあるディレクトリからの相対パスとして解釈されます。 このディレクトリはビルドコンテキストでもあり、Docker デーモンへ送信されるディレクトリです。

Compose は指定された名前により、イメージのビルドとタグづけを行い、後々これを利用します。

build:
  context: ./dir

dockerfile

別の Dockerfile を指定します。

Compose は指定された別の Dockerfile を使ってビルドを行います。 このときは、ビルドパスを同時に指定しなければなりません。

build:
  context: .
  dockerfile: Dockerfile-alternate

args

ファイルフォーマットバージョン 2.0 において追加されました。

ビルド引数を追加します。 これは環境変数であり、ビルド処理の間だけ利用可能なものです。

Dockerfile 内にてはじめにビルド引数を指定します。

# syntax=docker/dockerfile:1

ARG buildno
ARG gitcommithash

RUN echo "Build number: $buildno"
RUN echo "Based on commit: $gitcommithash"

そしてbuildキーのもとにその引数を指定します。 指定は個々をマッピングする形式か、リストとする形式が可能です。

build:
  context: .
  args:
    buildno: 1
    gitcommithash: cdc3b19

build:
  context: .
  args:
    - buildno=1
    - gitcommithash=cdc3b19

ビルド引数のスコープ

Dockerfile にてFROM命令の前にARG命令を指定した場合、FROM以降のビルド命令においてARGの値は利用することができません。 FROMの前後どこでも、そして特にFROM命令の後でもその値を利用したい場合は、ARG と FROM の関連について を参照してください。

ビルド引数の指定にあたって、その値設定を省略することができます。 この場合、ビルド時におけるその値は、Compose を起動している環境での値になります。

args:
  - buildno
  - gitcommithash

ブール値利用時のメモ

YAML のブール値 (true, false, yes, no, on, off) を用いる場合は、クォートで囲む必要があります。 そうすることで、これらの値は文字列として解釈されます。

cache_from

ファイルフォーマットバージョン 2.2 において追加されました。

エンジンがキャッシュ解決のために利用するイメージを設定します。

build:
  context: .
  cache_from:
    - alpine:latest
    - corp/web_app:3.14

extra_hosts

ビルド時におけるホスト名のマッピングを追加します。 Docker Client の--add-hostパラメーターと同じ値を設定してください。

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

ホスト名と IP アドレスによるこの設定内容は、サービスコンテナー内の/etc/hostsに追加されます。 たとえば以下のとおりです。

162.242.195.82  somehost
50.31.209.229   otherhost

isolation

ファイルフォーマットバージョン 2.1 において追加されました。

ビルドにおけるコンテナーの分離技術（isolation technology）を設定します。 Linux においてサポートされるのはdefaultのみです。 Windows ではdefault、process、hypervの設定が可能です。 詳しくは Docker Engine ドキュメント を参照してください。

設定されていない場合、Compose は service 定義の中からisolation値を見つけて、これをビルド時に利用する値とします。

labels

ファイルフォーマットバージョン 2.1 において追加されました。

Docker labels を使ってビルドされるイメージにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

他のソフトウェアが用いるラベルとの競合を避けるため、逆 DNS 記法とすることをお勧めします。

build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""

build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"

network

ファイルフォーマットバージョン 2.2 において追加されました。

ビルド時のRUN命令において接続するネットワークコンテナーを設定します。

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

noneを指定すると、ビルド中のネットワークを無効にします。

build:
  context: .
  network: none

shm_size

ファイルフォーマットバージョン 2.3 において追加されました。

このビルドコンテナーにおける/dev/shmパーティションのサイズを設定します。 指定する値は、バイト数を表わす整数値か、あるいは バイト表現 によって表わされる文字列とします。

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

target

ファイルフォーマットバージョン 2.3 において追加されました。

Dockerfile 内部に定義されている特定のステージをビルドする方法は、マルチステージビルド を参照してください。

build:
  context: .
  target: prod

cap_add, cap_drop

コンテナーケーパビリティーの機能を追加または削除します。 詳細な一覧はman 7 capabilitiesを参照してください。

cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

cgroup_parent

コンテナーに対して、オプションで指定する親の cgroup を指定します。

cgroup_parent: m-executor-abcd

command

デフォルトコマンドを上書きします。

command: bundle exec thin -p 3000

このコマンドは dockerfile の場合と同じように、リスト形式により指定することもできます。

command: ["bundle", "exec", "thin", "-p", "3000"]

container_name

デフォルトのコンテナー名ではない、独自のコンテナー名を設定します。

container_name: my-web-container

Docker コンテナー名はユニークである必要があります。 そこで独自のコンテナー名を設定したときは、サービスをスケールアップして複数コンテナーとすることはできません。 これを行うとエラーが発生します。

cpu_rt_runtime, cpu_rt_period

ファイルフォーマットバージョン 2.2 において追加されました。

Docker デーモンのリアルタイムスケジューラーが利用する CPU 割り当てパラメーターを設定します。

cpu_rt_runtime: '400ms'
cpu_rt_period: '1400us'

マイクロ秒単位で整数値を指定します。

cpu_rt_runtime: 95000
cpu_rt_period: 11000

device_cgroup_rules

ファイルフォーマットバージョン 2.3 において追加されました。

cgroup がアクセス可能なデバイスリストにルールを追加します。

device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'

devices

デバイスのマッピングをリスト形式で設定します。 Docker クライアントの create オプションの--deviceと同じ書式にします。

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"

depends_on

ファイルフォーマットバージョン 2.0 において追加されました。

サービス間の依存関係を表わします。 これにより以下の 2 つの効果が表れます。

  • docker-compose upは依存関係の順にサービスを起動します。 以下の例においてdbとredisはwebの後に起動します。
  • docker-compose up SERVICEを実行すると SERVICEにおける依存関係をもとに動作します。 以下の例においてdocker-compose up webを実行するとdbとredisを生成して起動します。
  • docker-compose stop stops services in dependency order. In the following example, web is stopped before db and redis.

以下がその簡単な例です。

version: "2.4"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

メモ

depends_onではdbやredisが「準備」状態になるのを待たずに、つまりそれらを開始したらすぐにwebを起動します。 準備状態になるのを待ってから次のサービスを起動することが必要な場合は、Compose における起動順の制御 にて示す内容と解決方法を確認してください。

ファイルフォーマットバージョン 2.1 において追加されました。

ヘルスチェックは、依存するコンテナーが起動する場合には、別のコンテナーが「健康」（healthy）となることを待って起動するようにチェックすることを指します。 （「健康」であることは、ヘルスチェックによって正常な状態であることが示されたことを表わします。）

以下がその例です。

version: "2.4"
services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres
    healthcheck:
      test: "exit 0"

上の例において Compose はredisサービスが起動するのを待ちます（従来からの動作）。 さらにdbサービスが「健康」になることを待ってwebサービスを起動します。

さらなる情報については ヘルスチェックの節 を参照してください。

dns

DNS サーバーを設定します。 設定は 1 つだけとするか、リストにすることができます。

dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 9.9.9.9

dns_opt

コンテナーのresolv.confファイルに追加する独自の DNS オプションを、リスト形式で設定します。

dns_opt:
  - use-vc
  - no-tld-query

DNS 検索ドメインを設定します。 設定は 1 つだけとするか、リストにすることができます。

dns_search: example.com

dns_search:
  - dc1.example.com
  - dc2.example.com

entrypoint

デフォルトのエントリーポイントを上書きします。

entrypoint: /code/entrypoint.sh

エントリーポイントはリスト形式で設定することができます。 その指定方法は dockerfile と同様です。

entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]

メモ

entrypointを設定すると、サービスイメージ内に Dockerfile 命令のENTRYPOINTによって設定されているデフォルトのエントリーポイントは上書きされ、さらにイメージ内のあらゆるデフォルトコマンドもクリアされます。 これはつまり、Dockerfile に CMD 命令があったとしたら無視されるということです。

env_file

ファイルを用いて環境変数を追加します。 設定は 1 つだけとするか、リストにすることができます。

Compose ファイルをdocker-compose -f FILEという起動により指定している場合、env_fileにおけるパスは、Compose ファイルがあるディレクトリからの相対パスとします。

環境変数が environment の項に宣言されていれば、ここでの設定をオーバーライドします。 たとえ設定値が空や未定義であっても、これは変わりません。

env_file: .env

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/runtime_opts.env

env ファイルの各行はVAR=VALの書式とします。 行先頭に#があると、コメント行となり無視されます。 空行も無視されます。

# Set Rails/Rack environment
RACK_ENV=development

メモ

サービスに build オプションを指定している場合、env ファイル内に定義された変数は、ビルド時にこのままでは自動的に参照されません。 その場合はbuildのサブオプション args を利用して、ビルド時の環境変数を設定してください。

VALの値は記述されたとおりに用いられ、一切修正はされません。 たとえば値がクォートにより囲まれている（よくシェル変数に対して行う）場合、クォートもそのまま値として Compose に受け渡されます。

ファイルを複数用いる場合の順番には気をつけてください。 特に何度も出現する変数に対して、値がどのように決定されるかです。 ファイルが複数指定された場合、その処理は上から順に行われます。 たとえばa.envファイルに変数が指定されていて、b.envファイルには同じ変数が異なる値で定義されていたとします。 ここでb.envファイルが下に（後に）指定されているとします。 このとき変数の値はb.envのものが採用されます。 さらに例としてdocker-compose.ymlに以下のような宣言があったとします。

services:
  some-service:
    env_file:
      - a.env
      - b.env

ファイルの内容は以下であるとします。

# a.env
VAR=1

# b.env
VAR=hello

この結果$VARはhelloになります。

environment

環境変数を追加します。 配列形式または辞書形式での指定が可能です。 ブール値（true, false, yes, no）を用いる場合は、クォートで囲むことで YML パーサーによって True や False に変換されてしまうのを防ぐ必要があります。

環境変数だけが記述されている場合は、Compose が起動しているマシン上にて定義されている値が設定されます。 これは機密情報やホスト固有の値を設定する場合に利用できます。

environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:

environment:
  - RACK_ENV=development
  - SHOW=true
  - SESSION_SECRET

メモ

サービスに build オプションを指定している場合、env ファイル内に定義された変数は、ビルド時にこのままでは自動的に参照されません。 その場合はbuildのサブオプション args を利用して、ビルド時の環境変数を設定してください。

expose

ホストマシンにはポートを公開せずに、ポートを expose します。 これはリンクされたサービスのみアクセスが可能になります。 内部ポートのみが指定できます。

expose:
  - "3000"
  - "8000"

extends

現ファイルや別のファイルにある他のサービスを拡張します。 必要に応じて設定を上書きすることもできます。

別のサービスをextendsにより拡張する際には、合わせて他の設定キーを指定することができます。 extendsに設定する値は辞書形式であり、serviceキーが必須です。 また必要に応じて指定するfileキーがあります。

extends:
  file: common.yml
  service: webapp

serviceは拡張するサービスの名前を指定します。 たとえばwebやdatabaseです。 fileは、サービスを定義する Compose 設定ファイルのパスを指定します。

fileの指定を省略した場合、Compose はそのサービス設定を現ファイルの中から探します。 fileに指定する値は絶対パス、相対パスのいずれでも構いません。 相対パスを指定した場合、Compose は現ファイルのあるディレクトリからの相対パスとして扱います。

拡張するサービスそのものが、他のサービスを拡張したものも指定可能です。 拡張の繰り返しはいくらでもできます。 ただし Compose は循環参照をサポートしていないため、そのような状況が発生した場合はdocker-composeがエラーを返します。

extendsに関する詳細は extends ドキュメント を参照してください。

今のdocker-compose.ymlからではない別のところから起動されたコンテナーをリンクします。 あるいは Compose の外から、特に共有サービスや汎用サービスとして提供されるコンテナーをリンクします。 external_linksの文法は、古いオプションlinksと同様です。 つまりコンテナー名とリンクのエイリアス名（CONTAINER:ALIAS）を同時に指定します。

external_links:
  - redis_1
  - project_db_1:mysql
  - project_db_1:postgresql

メモ

ファイルフォーマット バージョン 2 以降を利用しているときに、外部にて生成されたコンテナーをネットワークに接続する場合は、そのコンテナーがサービスとしてリンクしているネットワークのうちの 1 つでなければなりません。 Links オプションは古いものなので、networks オプションを用いてください。

extra_hosts

ホスト名のマッピングを追加します。 Docker Client の--add-hostパラメーターと同じ値を設定してください。

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

ホスト名と IP アドレスによるこの設定内容は、サービスコンテナー内の/etc/hostsに追加されます。 たとえば以下のとおりです。

162.242.195.82  somehost
50.31.209.229   otherhost

group_add

コンテナー内部のユーザーを所属させたい追加のグループを（グループ名か ID により）指定します。 追加のグループは、コンテナーとホストシステムの双方に存在している必要があります。 これが必要になるのは、たとえば複数コンテナーが別々のユーザーによって起動していて、しかもホストシステム上の同一のファイルへの読み書きを行いたいような場合です。 そのファイルが、コンテナーすべてに共通するグループにより所有されているようにすればよく、これをgroup_addにより実現できます。 詳しくは Docker ドキュメント を参照してください。

全体的な例として以下です。

version: "2.4"
services:
  myservice:
    image: alpine
    group_add:
      - mail

生成されたコンテナー内において idを実行すると、ユーザーがmailグループに所属していることがわかります。 group_addがなかったとしたら、このようにはなりません。

healthcheck

ファイルフォーマットバージョン 2.1 において追加されました。

このサービスを起動させているコンテナーが「健康」（healthy）かどうかを確認する処理を設定します。 ヘルスチェックがどのように動作するのかの詳細は Dockerfile の HEALTHCHECK 命令 を参照してください。

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s

interval、timeout、start_periodは 時間 を設定します。

ファイルフォーマットバージョン 2.3 において追加されました。

start_periodオプションはファイルフォーマット 2.3 において加えられたものです。

testは 1 つの文字列かリスト形式である必要があります。 リスト形式の場合、第 1 要素は必ず NONE、CMD、CMD-SHELLのいずれかとします。 文字列の場合は、CMD-SHELLに続けてその文字列を指定することと同じになります。

# ローカルのウェブアプリにアクセスします。
test: ["CMD", "curl", "-f", "http://localhost"]

上と同様ですが/bin/shによりラップします。 両書式は同等になります。

test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]

test: curl -f https://localhost || exit 1

イメージが設定するデフォルトのヘルスチェックを無効にするにはdisable: trueを指定します。 これはtest: ["NONE"]と指定することと同じです。

healthcheck:
  disable: true

image

コンテナーを起動させるイメージを設定します。 リポジトリ/タグの形式か、あるいは部分イメージ ID により指定します。

image: redis

image: ubuntu:18.04

image: tutum/influxdb

image: example-registry.com:4000/postgresql

image: a4bc65fd

イメージが存在しなかった場合、build を指定していなければ Compose はイメージを取得しようとします。 取得する際には、指定されたオプションを使ってビルドを行い、指定されたタグ名によりタグづけを行います。

init

ファイルフォーマットバージョン 2.2 において追加されました。

コンテナー内にて init を実行し、シグナルを送信してプロセスを停止させます。 このオプションにtrueを設定することで、サービスに対するこの機能を有効にします。

version: "2.4"
services:
  web:
    image: alpine:latest
    init: true

利用されるデフォルトの init の実行モジュールは Tini であり、デーモンホストの/usr/libexec/docker-initにインストールされています。 デーモンに対して独自の init 実行モジュールを設定するには、init-path設定オプション を利用します。

isolation

ファイルフォーマットバージョン 2.1 において追加されました。

コンテナーの分離技術（isolation technology）を設定します。 Linux においてサポートされるのはdefaultのみです。 Windows ではdefault、process、hypervの設定が可能です。 詳しくは Docker Engine ドキュメント を参照してください。

labels

Docker labels を使ってコンテナーにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

他のソフトウェアが用いるラベルとの競合を避けるため、逆 DNS 記法とすることをお勧めします。

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

他サービスのコンテナーをリンクします。 サービス名とリンクのエイリアス名（"SERVICE:ALIAS"）を指定するか、直接サービス名を指定します。

links は古いオプションです。 この代わりに networks オプションを用いることをお勧めします。

web:
  links:
    - "db"
    - "db:database"
    - "redis"

リンクされたサービスのコンテナーは、エイリアスと同等のホスト名により到達可能になります。 エイリアスが設定されていない場合はサービス名により到達可能です。

Links are not required to enable services to communicate - by default, any service can reach any other service at that service’s name. (See also, the Links topic in Networking in Compose.)

Links は depends_on と同様にサービス間の依存関係を表わします。 したがってサービスの起動順を設定するものになります。

メモ

links と networks をともに設定する場合、リンクするサービスは、少なくとも 1 つのネットワークが共有され通信ができるようにする必要があります。 このオプションではなく networks オプションを用いることをお勧めします。

logging

サービスに対するログ記録の設定をします。

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

driver名にはサービスコンテナーにおけるログドライバーを指定します。 これは docker run コマンドに対する--log-driverオプションと同じです。 （ドキュメントはこちら）

デフォルトは json-file です。

driver: "json-file"

driver: "syslog"

driver: "none"

メモ

ドライバーのうちjson-fileとjournaldだけが、docker-compose upとdocker-compose logsによって直接ログ参照ができます。 その他のドライバーではログ表示は行われません。

ログドライバーへのログオプションの設定はoptionsキーにより行います。 これはdocker runコマンドの--log-optオプションと同じです。

ログオプションはキーバリューのペアで設定します。 たとえばsyslogオプションは以下のようになります。

driver: "syslog"
options:
  syslog-address: "tcp://192.168.0.42:123"

network_mode

ファイルフォーマットバージョン 2 において変更されました。

ネットワークモードを設定します。 Docker クライアントの--networkパラメーターと同じ値を設定します。 これに加えてservice:[service name]という特別な書式も指定可能です。

network_mode: "bridge"

network_mode: "host"

network_mode: "none"

network_mode: "service:[service name]"

network_mode: "container:[container name/id]"

networks

ファイルフォーマットバージョン 2 において変更されました。

ネットワークへの参加を設定します。 設定には 最上位のnetworksキー に設定された値を用います。

services:
  some-service:
    networks:
     - some-network
     - other-network

aliases

ネットワーク上のサービスに対して、ホスト名の別名となるエイリアスを設定します。 同じネットワーク上にある他のコンテナーは、この 1 つのサービスコンテナーに対して、サービス名か、あるいはそのエイリアスを使ってアクセスすることができます。

aliasesはネットワーク範囲内において有効です。 ネットワークが異なれば、同一サービスに違うエイリアスを持たせることができます。

メモ

ネットワーク全体にわたってのエイリアスを複数コンテナー間で共有することができます。 それは複数サービス間でも可能です。 ただしこの場合、名前解決がどのコンテナーに対して行われるかは保証されません。

一般的な書式は以下のとおりです。

services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2

以下の例では 3 つのサービス（web、worker、db）と 2 つのネットワーク（new と legacy）を提供します。 dbサービスはnewネットワーク上では、ホスト名dbあるいはdatabaseとしてアクセスできます。 一方legacyネットワーク上ではdbあるいはmysqlとしてアクセスできます。

version: "2.4"

services:
  web:
    image: "nginx:alpine"
    networks:
      - new

  worker:
    image: "my-worker-image:latest"
    networks:
      - legacy

  db:
    image: mysql
    networks:
      new:
        aliases:
          - database
      legacy:
        aliases:
          - mysql

networks:
  new:
  legacy:

ipv4_address, ipv6_address

サービスをネットワークに参加させる際、そのコンテナーに対してスタティック IP アドレスを設定します。

最上位の networks セクション の対応するネットワーク設定においては、ipamブロックが必要です。 そこでは各スタティックアドレスに応じたサブネットの設定が必要になります。

IPv6 アドレスが必要である場合は、enable_ipv6 オプションの設定が必要になります。

以下に例を示します。

version: "2.4"

services:
  app:
    image: busybox
    command: ifconfig
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 172.16.238.0/24
          gateway: 172.16.238.1
        - subnet: 2001:3984:3989::/64
          gateway: 2001:3984:3989::1

ファイルフォーマットバージョン 2.1 において追加されました。

リンクローカル IP（link-local IP） のリストを設定します。 リンクローカル IP とは特別な IP アドレスのことであり、よく知られた（well known）サブネットに属し、ユーザーが自由に管理するものを指します。 普通、このアドレスはデプロイされたアーキテクチャーとはまったく関係のないものです。 したがって Docker（IPAM ドライバー）によって管理されるものではありません。

利用例を以下に示します。

version: "2.4"
services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge

priority

Compose がサービスのコンテナーをネットワークに接続する際に、その接続の優先順位を設定します。 設定されていない場合のデフォルト値は0です。

以下の例においてappサービスは初めにapp_net_1に接続します。 そこに一番高い優先順位が設定されているためです。 次に接続されるのはapp_net_3です。 最後に、デフォルトの優先順位である0が用いられているapp_net_2に接続します。

version: "2.4"
services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:

メモ

複数のネットワークに同一の優先順位が設定された場合、接続順は定義されません。

pid

pid: "host"

pid: "container:custom_container_1"

pid: "service:foobar"

これがcontainer:<container_name>またはservice:<service_name>の形で設定された場合は、そのサービスは、指定されたコンテナーまたはサービスの PID アドレス空間を共有します。

これが “host” に設定された場合は、サービスの PID モードをホスト PID モードに設定します。 これはコンテナーとホストオペレーティングシステムとの間で、PID アドレス空間の共有を開始します。 このフラグを使って起動したコンテナーは、ベアメタルマシンの名前空間にあるコンテナーにアクセスし、操作することが可能になります。 逆もまた可能です。

ファイルフォーマットバージョン 2.1 において追加されました。

service:とcontainer:の書式を利用するには バージョン 2.1 またはそれ以降である必要があります。

pids_limit

ファイルフォーマットバージョン 2.1 において追加されました。

コンテナーの PID 上限を設定します。 -1に設定すると無制限になります。

pids_limit: 10

platform

ファイルフォーマットバージョン 2.4 において追加されました。

サービスのコンテナーが稼動することになるプラットフォームを設定します。 その記述はos[/arch[/variant]]といった書式で行います。

platform: osx

platform: windows/amd64

platform: linux/arm64/v8

このパラメーターは、どのバージョンのイメージを取得するのか、あるいはサービスがどのプラットフォームでビルドされるかを決定します。

ports

公開用ポートを設定します。 設定は両側のポートを指定するか（HOST:CONTAINER）、あるいはコンテナー側のポートのみを指定します（その場合、ホスト側はエフェメラルポートが採用されます）。

メモ

HOST:CONTAINERの書式によってポートをマッピングした場合に、コンテナー側のポートが 60 番未満であるとエラーになることがあります。 これは YAML パーサーがxx:yyの書式内にある数値を 60 進数値として解釈するからです。 このことからポートマッピングを指定する際には、常に文字列として設定することをお勧めします。

ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"
  - "12400-12500:1240"

runtime

ファイルフォーマットバージョン 2.3 において追加されました。

サービスのコンテナーにおいてどのランタイム（runtime）を用いるかを設定します。 デフォルトのランタイムおよび利用可能なランタイムは、docker info出力から確認できます。

web:
  image: busybox:latest
  command: true
  runtime: runc

scale

ファイルフォーマットバージョン 2.2 において追加されました。

本サービスに対して、デプロイするコンテナーのデフォルト数を設定します。 docker-compose upを実行したとき、Compose はこの設定数に従ってコンテナーの生成や削除を行います。 この値は --scale フラグを使って上書きすることができます。

web:
  image: busybox:latest
  command: echo 'scaled'
  scale: 3

security_opt

各コンテナーにおけるデフォルトのラベリングスキーム（labeling scheme）を上書きします。

security_opt:
  - label:user:USER
  - label:role:ROLE

stop_grace_period

コンテナーが SIGKILL を送信するまでに、SIGTERM（あるいは stop_signal によって設定されたストップシグナル）をどれだけ待つかを設定します。 指定には 時間 を用います。

stop_grace_period: 1s

stop_grace_period: 1m30s

デフォルトで、コンテナーが SIGKILL を送信する前にstopは 10 秒待ちます。

stop_signal

コンテナーに対して別の停止シグナルを設定します。 デフォルトにおいてstopは SIGTERM を用います。 stop_signalを使って別のシグナルを設定するとstopにはそのシグナルが代わりに送信されます。

stop_signal: SIGUSR1

storage_opt

ファイルフォーマットバージョン 2.1 において追加されました。

本サービスに対するストレージドライバーのオプションを設定します。

storage_opt:
  size: '1G'

sysctls

ファイルフォーマットバージョン 2.1 において追加されました。

コンテナーに設定するカーネルパラメーターを設定します。 配列または辞書形式での指定ができます。

sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0

tmpfs

コンテナー内においてテンポラリファイルシステムをマウントします。 設定は 1 つだけとするか、リストにすることができます。

tmpfs: /run

tmpfs:
  - /run
  - /tmp

ulimits

コンテナーにおけるデフォルトの ulimits を上書きします。 1 つの limit を整数値として指定するか、ソフト、ハードの limit をマッピングとして指定することができます。

ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000

userns_mode

ファイルフォーマットバージョン 2.1 において追加されました。

userns_mode: "host"

Docker デーモンにおいてユーザー名前空間が設定されていても、サービスに対してユーザー名前空間を無効にします。 詳しくは dockerd を参照してください。

volumes

マウントホストパスや名前つきボリュームをマウントします。 名前つきボリュームは 最上位のvolumesキー として設定する必要があります。

短い文法

短い文法では汎用的な[SOURCE:]TARGET[:MODE]という書式を用います。 ここでSOURCEはホストパスまたはボリューム名のどちらでも可です。 TARGETはボリュームがマウントされるコンテナーパスです。 標準的なモードは、読み込み専用の場合ro、読み書き可能の場合rw（デフォルト）です。

You can mount a relative path on the host, which expands relative to the directory of the Compose configuration file being used. Relative paths should always begin with . or ...

volumes: # パス指定のみ。Engine にボリュームを生成させます。

  • /var/lib/mysql

# 絶対パスのマッピングを指定。

  • /opt/data:/var/lib/mysql

# ホストからのパス指定。Compose ファイルからの相対パス。

  • ./cache:/tmp/cache

# ユーザーディレクトリからの相対パス。

  • ~/configs:/etc/configs/:ro

# 名前つきボリューム。

  • datavolume:/var/lib/mysql

長い文法

ファイルフォーマットバージョン 2.3 において追加されました。

長い文法は追加の設定項目が加えられていて、短い文法では表現できないものです。

  • type: マウントタイプを表わす volume、bind、tmpfs、npipeのいずれかを指定します。
  • source: マウント元。バインドマウントにおいてはホスト上のパスを指定します。 また 最上位のvolumesキー で定義したボリューム名を指定します。 tmpfs マウントはできません。
  • target: ボリュームがマウントされるコンテナー内のパスを指定します。
  • read_only: ボリュームを読み込み専用に設定します。
  • bind: 追加のバインドオプションを設定します。
    • propagation: バインドにおいて伝播モード（propagation mode）を利用します。
  • volume: 追加のボリュームオプションを設定します。
    • nocopy: ボリュームの生成時にはコンテナーからのデータコピーを無効にします。
  • tmpfs: 追加の tmpfs オプションを設定します。
    • size: tmpfs マウントのサイズをバイト数で指定します。
version: "2.4"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

networks:
  webnet:

volumes:
  mydata:

Note

長い文法を使ってバインドマウントを生成する際には、参照されるフォルダーをあらかじめ生成しておく必要があります。 短い文法を利用する場合、そのフォルダーが存在しなければ生成されます。 詳しくは バインドマウントのドキュメント を参照してください。

volume_driver

本サービス上に宣言されているボリュームすべてに対して、利用するデフォルトのボリュームドライバーを設定します。

volume_driver: mydriver

メモ

ファイルフォーマットバージョン 2 においてこのオプションは、匿名ボリューム（anonymous volume）に対してのみ適用されます。 （これはイメージ内で匿名として設定されるか、あるいはvolumesキー配下において明示的な名前やホストパスが指定されずに設定されるものです。） 名前つきボリュームに対してドライバーを設定するには、最上位のvolumesオプション の配下にてdriverキーを使ってください。

詳しくは Docker ボリューム や ボリュームプラグイン を参照してください。

volumes_from

別のサービスやコンテナーのボリュームをすべてマウントします。 任意の設定として、アクセスを読み込み専用（ro）とするか、読み書き可能（rw）とするかを指定できます。 アクセスレベルが何も設定されていないときは、読み書き可能として設定されます。

volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw

ファイルフォーマットバージョン 2 において変更されました。

restart

再起動ポリシー（restart policy）のデフォルトはnoです。 この場合はどういう状況であってもコンテナーは再起動しません。 alwaysを指定した場合、コンテナーは常に再起動することになります。 またon-failureポリシーでは、終了コードが on-failure エラーを表わしている場合にコンテナーが再起動します。

restart: "no"

restart: "always"

restart: "on-failure"

restart: "unless-stopped"

cpu_count, cpu_percent, cpu_shares, cpu_period, cpu_quota, cpus, cpuset, domainname, hostname, ipc, mac_address, mem_limit, memswap_limit, mem_swappiness, mem_reservation, oom_kill_disable, oom_score_adj, privileged, read_only, shm_size, stdin_open, tty, user, working_dir

ここに示すオプションはいずれも、値 1 つを設定するものであり、docker run のオプションに対応づいています。

ファイルフォーマットバージョン 2.2 における追加

cpu_count、cpu_percent、cpusの各オプションは バージョン 2.2 において追加されました。

ファイルフォーマットバージョン 2.1 における追加

oom_kill_disable、cpu_periodのオプションは バージョン 2.1 において追加されました。

cpu_count: 2
cpu_percent: 50
cpus: 0.5
cpu_shares: 73
cpu_quota: 50000
cpu_period: 20ms
cpuset: 0,1

user: postgresql
working_dir: /code

domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43

mem_limit: 1000000000
memswap_limit: 2000000000
mem_reservation: 512m
privileged: true

oom_score_adj: 500
oom_kill_disable: true

read_only: true
shm_size: 64M
stdin_open: true
tty: true

時間の指定

healthcheck のサブオプションinterval、timeoutのように、時間を設定するオプションがあります。 これは以下のような書式による文字列を時間として受け付けるものです。

2.5s
10s
1m30s
2h32m
5h34m56s

サポートされる単位はus、ms、s、m、hです。

バイト値の表現

blkio_config のサブオプションdevice_read_bpsのようにバイト値を設定するオプションがあります。 バイト値は文字列として指定するものであり、以下のようになります。

2b
1024kb
2048k
300m
1gb

サポートされる単位はb、k、m、gとそれに応じたkb、mb、gbです。 現時点にて 10 進数値の指定はサポートされていません。

ボリューム設定リファレンス

サービスの宣言の一部として、ファイル上に ボリューム を宣言することが可能ですが、このセクションでは（volumes_fromを利用せずに）名前つきボリュームを生成する方法を説明します。 このボリュームは、複数のサービスにわたっての再利用が可能であり、docker コマンドラインや API を使って簡単に抽出したり確認したりすることができます。 詳しくは docker volume のサブコマンドを確認してください。

詳しくは Docker ボリューム や ボリュームプラグイン を参照してください。

以下の例では 2 つのサービスを用います。 データベースのデータディレクトリは、もう一方のサービスに対してボリュームとして共有させます。 これによりデータが定期的に反映されます。

version: "2.4"

services:
  db:
    image: db
    volumes:
      - data-volume:/var/lib/db
  backup:
    image: backup-service
    volumes:
      - data-volume:/var/lib/backup/data

volumes:
  data-volume:

最上位のvolumesキーは指定しないようにすることもできます。 その場合は Engine によってデフォルトで設定されているドライバーが用いられます。 （たいていはlocalドライバーとなります。） さらに追加で、以下のようなキーを設定することができます。

driver

どのボリュームドライバーを現在のボリュームに対して用いるかを指定します。 デフォルトは Docker Engine が利用するものとして設定されているドライバーになります。 たいていはlocalです。 ドライバーが利用できない場合、docker-compose upによってボリューム生成が行われる際に Engine がエラーを返します。

driver: foobar

driver_opts

このボリュームが利用するドライバーに対して、受け渡したいオプションをキーバリューペアのリストとして設定します。 このオプションは各ドライバーによって異なります。 詳しくは各ドライバーのドキュメントを参照してください。 設定は任意です。

volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"

external

このオプションをtrueに設定することにより、Compose の外部において生成されているボリュームを設定します。 docker-compose upはボリュームを生成しないようになりますが、ボリュームが存在しなければエラーとなります。

バージョン 2.0 にてexternalは他のボリューム設定キー（driver、driver_opts、labels）と同時に用いることはできませんでした。 この制約は バージョン 2.1 以降においてはなくなりました。

以下の例では[projectname]_dataというボリュームは生成されることはなく、Compose はすでに存在しているdataという単純な名前のボリュームを探しにいきます。 そしてこれをdbサービスコンテナー内にマウントします。

version: "2.4"

services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data

volumes:
  data:
    external: true

ボリューム名として指定する名前は、Compose ファイル内で参照されている名前以外でも指定することができます。

volumes:
  data:
    external:
      name: actual-name-of-volume

ファイルフォーマットバージョン 2.1 において廃止予定

ファイルフォーマットバージョン 2.1 において external.name プロパティは廃止予定となったためnameプロパティを用いてください。

labels

ファイルフォーマットバージョン 2.1 における追加

Docker labels を使ってコンテナーにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

ここでは逆 DNS 記法とすることをお勧めします。 この記法にしておけば、他のソフトウェアが用いるラベルとの競合が避けられるからです。

labels:
  com.example.description: "Database volume"
  com.example.department: "IT/Ops"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Database volume"
  - "com.example.department=IT/Ops"
  - "com.example.label-with-empty-value"

name

ファイルフォーマットバージョン 2.1 における追加

ボリュームに対して独自の名前を設定します。 name は特殊な文字を含んだボリューム名を参照するために利用できます。 name は記述されたとおりに扱われ、スタック名によってスコープされません。

version: "2.4"
volumes:
  data:
    name: my-app-data

これはexternalプロパティと同時に利用することができます。

version: "2.4"
volumes:
  data:
    external: true
    name: my-app-data

ネットワーク設定リファレンス

最上位のnetworksキーは、生成するネットワークを指定します。 Compose が利用する Docker ネットワーク機能に関して、詳細は ネットワークガイド を参照してください。

driver

現在のネットワークにおいて利用するドライバーを設定します。

デフォルトとなるドライバーは、Docker Engine においてどのドライバーを用いているかによって変わります。 たいていの場合、単一ホストであればbridge、スウォーム上ではoverlayとなります。

ドライバーが利用できない場合、Docker Engine はエラーを返します。

driver: overlay

ファイルフォーマットバージョン 2.1 における変更

Compose ファイルフォーマット 2.1 から、オーバーレイネットワークは、必ず「アタッチ可能」（attachable）として生成されますが、ただし変更できません。 スタンドアロンコンテナーであれば、オーバーレイネットワークに接続することができます。

driver_opts

このネットワーク上で利用するドライバーに対して、受け渡したいオプションをキーバリューペアのリストとして設定します。 このオプションは各ドライバーによって異なります。 詳しくは各ドライバーのドキュメントを参照してください。 設定は任意です。

driver_opts:
  foo: "bar"
  baz: 1

enable_ipv6

ファイルフォーマットバージョン 2.1 における追加

現在のネットワークにおいて IPv6 ネットワークを有効にします。

ipam

独自の IPAM 設定を行います。 いくつかのプロパティにより表わされるオブジェクトであり、それぞれの指定は任意です。

  • driver: デフォルトではない独自の IPAM ドライバーを指定します。
  • config: 設定ブロックを指定します。要素数はゼロでも複数でも可です。 以下のキーを用いることができます。
    • subnet: ネットワークセグメントを表わす CIDR 形式のサブネットを指定します。
    • ip_range: コンテナー IP としてどこからどこまで割り当てるかの範囲を指定します。
    • gateway: マスターサブネットに対する IPv4 または IPv6 のゲートウェイを指定します。
    • aux_addresses: ネットワークドライバーが利用する追加の IPv4 または IPv6 アドレス。 ホスト名から IP へのマッピングとして利用されます。
  • options: キーバリューペアによりドライバー固有のオプションを指定します。

すべてを利用した例が以下です。

ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16
      ip_range: 172.28.5.0/24
      gateway: 172.28.5.254
      aux_addresses:
        host1: 172.28.1.5
        host2: 172.28.1.6
        host3: 172.28.1.7
  options:
    foo: bar
    baz: "0"

internal

デフォルトにおいて Docker はブリッジネットワークに接続する際に、外部接続機能も提供します。 外部に独立した overlay ネットワークを生成したい場合、本オプションをtrueにします。

labels

ファイルフォーマットバージョン 2.1 における追加

Docker labels を使ってコンテナーにメタデータを追加します。 配列形式と辞書形式のいずれかにより指定します。

ここでは逆 DNS 記法とすることをお勧めします。 この記法にしておけば、他のソフトウェアが用いるラベルとの競合が避けられるからです。

labels:
  com.example.description: "Financial transaction network"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""

labels:
  - "com.example.description=Financial transaction network"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

external

このオプションをtrueに設定することにより、Compose の外部において生成されているボリュームを設定します。 docker-compose upはボリュームを生成しないようになりますが、ボリュームが存在しなければエラーとなります。

バージョン 2.0 にて external は、他のボリューム設定キー（driver, driver_opts, ipam, internal）と同時に用いることはできませんでした。 この制約は バージョン 2.1 以降においてはなくなりました。

以下の例においてproxyは外部ネットワークとの間のゲートウェイです。 [projectname]_outsideというネットワークは生成されることはなく、Compose はすでに存在しているoutsideという単純な名前のネットワークを探しにいって、proxyサービスのコンテナーに接続します。

version: "2.4"

services:
  proxy:
    build: ./proxy
    networks:
      - outside
      - default
  app:
    build: ./app
    networks:
      - default

networks:
  outside:
    external: true

ネットワーク名として指定する名前は、Compose ファイル内で参照されている名前以外でも指定することができます。

version: "2.4"
networks:
  outside:
    external:
      name: actual-name-of-network

バージョン 2 のdocker-composeファイルではサポートされません。 かわりに network_mode を利用してください。

name

ファイルフォーマットバージョン 2.1 における追加

ネットワークに対して独自の名前を設定します。 name は特殊な文字を含んだネットワーク名を参照するために利用できます。 name は記述されたとおりに扱われ、スタック名によってスコープされません。

version: "2.4"
networks:
  network1:
    name: my-app-net

これはexternalプロパティと同時に利用することができます。

version: "2.4"
networks:
  network1:
    external: true
    name: my-app-net

変数の置換

設定オプションには環境変数を含めることができます。 Compose は docker-compose が実行されたシェル環境から変数値を取得します。 たとえばシェル環境に POSTGRES_VERSION=9.3 が定義されているとして、以下のような設定を行ったとします。

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

上の設定を使って docker-compose up を実行すると、Compose はシェル環境内の環境変数 POSTGRES_VERSION を見にいき、その値を使って設定を置換します。 この例では image が postgres:9.3 と置換された上で、設定に関する処理へ進みます。

その環境変数が何も設定されていなかった場合、Compose は空文字に置換します。 上の例でいうと POSTGRES_VERSION が設定されていなかったとき、image オプションの値は postgres: になります。

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

.env ファイルによる機能は docker-compose up コマンドを使うときだけ動作します。 docker stack deploy コマンドでは動作しません。

$VARIABLE と ${VARIABLE} という 2 つの文法がともにサポートされます。 さらに 2.1 ファイルフォーマット を利用している場合は、シェル上でも利用されているインラインのデフォルト指定方法を行うことができます。

  • ${VARIABLE:-default} は VARIABLE がセットされていないか空文字であるときに default として評価されます。
  • ${VARIABLE-default} は VARIABLE がセットされていないときのみ default として評価されます。

同様に以下の文法により、変数を必須とする扱いができます。

  • ${VARIABLE:?err} は VARIABLE がセットされていないか空文字であるときに、err を含むエラーメッセージを表示して終了します。
  • ${VARIABLE?err} は VARIABLE がセットされていないときに、err を含むエラーメッセージを表示して終了します。

シェル風のこの他の機能、たとえば ${VARIABLE/foo/bar} などはサポートされていません。

設定ファイル内にドル記号そのものが必要な場合は $$（ドル記号 2 つ）を書きます。 この記述は Compose が値を取り違えないようにします。 つまり $$ と書くことで、環境変数を参照しつつ Compose には処理させないようにすることができます。

web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"

このことを忘れてドル記号 1 つ（$）を用いてしまうと、Compose は環境変数として値を解釈し、以下の警告を出します。

The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.
(VAR_NOT_INTERPOLATED_BY_COMPOSE は設定されていません。空文字として置換します。)

拡張項目

ファイルフォーマットバージョン 2.1 における追加

拡張項目（extension fields）を利用することで、設定内容の再利用が可能になります。 この特別な項目は Compose ファイルの最上位項目として位置していれば、どのような書式であっても構いません。 このとき項目名の先頭は x- で書き始めます。

メモ

（3.x シリーズにおいては）バージョン 3.7 から、また（2.x シリーズにおいては）バージョン 2.4 から、この拡張項目は、service、volume、network、config、secret それぞれの最上位に記述できることになりました。

version: "3.9"
x-custom:
  items:
    - a
    - b
  options:
    max-size: '12m'
  name: "custom"

この項目に記述された内容は Compose からは無視されます。 そして YAML アンカー を利用して、この項目をリソース定義内に挿入します。 たとえば複数のサービスに対して、同様のロギング設定を行いたいとします。

logging:
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

その場合、以下のようにして Compose ファイルを書くことができます。

version: "3.9"
x-logging:
  &default-logging
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

services:
  web:
    image: myapp/web:latest
    logging: *default-logging
  db:
    image: mysql:latest
    logging: *default-logging

また YAML マージタイプ を利用すれば、拡張項目内にて部分的に値を上書きすることもできます。 たとえば以下のとおりです。

version: "3.9"
x-volumes:
  &default-volume
  driver: foobar-storage

services:
  web:
    image: myapp/web:latest
    volumes: ["vol1", "vol2", "vol3"]
volumes:
  vol1: *default-volume
  vol2:
    << : *default-volume
    name: volume02
  vol3:
    << : *default-volume
    driver: default
    name: volume-local

Compose ドキュメント

fig, composition, compose version 2, docker