環境差を吸収する - compose.override.yml
compose.override.yml は同じディレクトリにあれば自動でマージされ、`-f base.yml -f prod.yml` で任意の差分ファイルを重ねられる。env_file と environment の優先順位も把握しておく。
概念図
構文
実例
ベースに対して dev 用 override を自動マージする例
# compose.yml (base)
services:
api:
image: myorg/api:${TAG:-latest}
environment:
LOG_LEVEL: info
# compose.override.yml (dev)
services:
api:
build: ./api
volumes:
- ./api:/app
environment:
LOG_LEVEL: debug本番用 / CI 用 override を明示して起動・設定確認
docker compose -f compose.yml -f compose.prod.yml up -d
docker compose -f compose.yml -f compose.ci.yml configcompose.override.yml の自動マージ
同じディレクトリに compose.yml と compose.override.yml があると、docker compose は何も指定しなくてもこの 2 ファイルを重ねて読み込む。
マージは「同じサービス名のキーを上書き」と「配列は後勝ちで置換」が基本挙動になる。
開発者ごとに異なる bind mount やポートを override 側に書き、ベースの compose.yml をクリーンに保つという使い方が一般的。
compose.override.yml は .gitignore に入れて個人設定にすることもできるが、チーム全員の dev 環境を揃えたい場合はリポジトリに含めておく方が再現性が高くなる。
マージ結果を確認したいときは docker compose config を使うとよい。
`-f base.yml -f prod.yml` パターン
自動マージされるのは compose.override.yml 一種類だけなので、dev / staging / prod のように 3 つ以上の環境を扱うときは -f を明示的に並べる。
左から右に向かって後勝ちで重ねられ、docker compose -f compose.yml -f compose.prod.yml up -d とすれば base → prod の順にマージされる。
CI では -f compose.yml -f compose.ci.yml のようにサービスをテスト用コンテナに差し替える使い方も多い。
ファイル名に環境名を含めておくとコマンドラインで意図が伝わりやすく、誤ったファイルを読んだ場合も docker compose config で最終結果を確認できる。
# 本番 / production
docker compose -f compose.yml -f compose.prod.yml up -d
# CI
docker compose -f compose.yml -f compose.ci.yml run --rm api pytest
# マージ結果を確認 / inspect merged config
docker compose -f compose.yml -f compose.prod.yml configenv_file と environment の優先順位
環境変数の供給源は複数あり、優先順位を誤解するとトラブルの原因になる。
compose の仕様上は「シェルの環境変数 > compose.yml の environment > env_file で指定したファイル > Dockerfile の ENV」の順で後から来たものほど弱い。
つまりシェルで export LOG_LEVEL=debug している場合、compose.yml の environment で LOG_LEVEL: info と書いてもシェル側が優先される（厳密には ${LOG_LEVEL} 展開時）。
加えて、env_file に同じキーが複数ある場合は後ろの行が勝つ。
機密情報を .env ファイルに置くときは .gitignore に必ず追加し、本番は Docker secrets や外部の Vault に切り出すのが安全になる。
services:
api:
image: myapp
env_file:
- ./env/common.env
- ./env/prod.env
environment:
LOG_LEVEL: info # env_file より強い / stronger than env_file