Zenn
Open2

Docker Composeを本番と開発環境で分ける方法について📝

docker-compose
dockertips
まさぴょん🐱まさぴょん🐱

Docker Composeを本番と開発環境で分ける方法について📝

Docker Compose では「開発 (dev) 用」と「本番 (prod) 用」をきれいに分離するための仕組みがいくつか用意されています。
それぞれの長所・短所と代表的な構成例をまとめました。

1. 複数の Compose ファイルをマージする（王道パターン）

仕組み

  • ベース定義 docker-compose.yml
  • 環境別差分 docker-compose.dev.yml, docker-compose.prod.yml などを追加
  • 実行時に -f を並べて指定すると、後ろのファイルが前の設定を上書き・追加します。(Docker Documentation)
# 開発
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# 本番
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

こんなとき便利

  • “違い” が明確に分かる（差分ファイルにだけ書けばよい）
  • CI/CD で -f の組み合わせを変えるだけで環境を切り替えられる

2. override ファイルを利用する（ローカル開発を自動で上書き）

docker-compose.override.yml という名前のファイルは、docker compose を実行しただけで 自動的にマージ されます。テスト用のボリュームやホットリロード設定など、開発専用の調整をここにまとめておくと便利です。(LibreChat)

  • 本番では 指定しなければ override が読まれないので、次のように実行するだけで OK:

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

3. Compose Profiles（1 ファイルで環境を切り替える）

services.<name>.profiles に "dev", "prod" などのラベルを付け、--profile オプションで起動するサービスを切り替える方法です。(Docker Documentation, Collabnix)

services:
  server:
    build: .
    profiles: ["dev","prod"]

  db:
    image: postgres:16
    profiles: ["dev"]       # 本番では起動しない

# ローカル開発
docker compose --profile dev up

# 本番
docker compose --profile prod up -d

メリット

  • ファイルを分けずに YAML 1 枚で完結
  • サービス単位で「起動する／しない」を柔軟に制御できる

4. .env / --env-file で切り替える

  • 共通 docker-compose.yml は 変数 だらけにしておき、

    • env/.dev.env
    • env/.prod.env

  • 起動時に --env-file env/.dev.env を指定。
    設定は一行も重複しない ので YAML が最小限に。
    ただし “どの値が入るか” は外から見えにくい点に注意。

5. extends キーワードで共通設定を継承する

Compose v3.9+ の x-common & extends で DRY に記述できます。大規模プロジェクト向け。(Docker Documentation)

どの方法を選ぶ？

方式 特徴 向いているケース
複数ファイル (-f) シンプルで学習コスト低め 差分が少なく、CI/CD でファイルを切り替えたい
override dev を自動で上書き ローカル開発と本番でしか分けない
profiles 1 ファイル運用、サービス単位切り替え ステージング・テストなど複数環境を細かく制御
.env / --env-file YAML 最小化、GitOps 向け 値が多く頻繁に変わる（DB パス・API キーなど）
extends 共通定義を複数プロジェクトで共有 マイクロサービス全体を Compose で管理

最小サンプル：-f ＋ profiles を組み合わせる

project/
├ docker-compose.yml          # 共通
├ docker-compose.dev.yml      # dev 用 差分
├ docker-compose.prod.yml     # prod 用 差分
└ .env                        # 共通環境変数

# 開発（db やホットリロードが有効）
docker compose \
  -f docker-compose.yml \
  -f docker-compose.dev.yml \
  --profile dev up

# 本番（alpine イメージ・ステートレス前提）
docker compose \
  -f docker-compose.yml \
  -f docker-compose.prod.yml \
  --profile prod up -d

補足ベストプラクティス

  1. マルチステージ Dockerfile で本番イメージを最小化
  2. Compose の healthcheck を prod にだけ入れる
  3. GitHub Actions / Cloud Build などで docker compose config を実行し、
    マージ結果を検証してからデプロイ
  4. Docker Context を使うと docker compose ... のままリモートホストへデプロイできる (Docker Documentation)

このあたりを押さえておけば、開発と本番の切り替えが格段に楽になります。既存の docker-compose.yml をベースに、まずは -f 方式から試してみると理解しやすくておすすめですよ。