docker-compose-patterns

Docker Compose のパターン

概要

このスキルでは、Docker Compose の設定を作成、レビュー、デバッグするためのルールを説明します。主な成果物が compose.yaml または compose.override.yaml で、タスクがイメージビルドの内部処理ではなく、サービスの接続方法に関する場合に使用してください。

このスキルを使用する場合

次の場合にこのスキルを有効にしてください。

• プロジェクト用の新しい compose.yaml を作成する
• 既存の Compose ファイルにサービスを追加または変更する
• compose.override.yaml を使って開発用のオーバーライドを設定する
• サービスの起動順序や接続に関する問題をデバッグする

このスキルを使用しない場合

次の場合はこのスキルを使用しないでください。

• プロジェクトに Docker の設定がまだなく、主な目的が初期構成の作成である
• 主なタスクが Dockerfile の作成または最適化である
• 主なタスクがビルドキャッシュ、イメージサイズ、または実行時のユーザー設定の改善である

基本的なガイダンス

ファイル名

標準のファイル名として compose.yaml を使用してください。これらは古いファイル名なので、docker-compose.yml や docker-compose.yaml は使用しないでください。

サービス定義

• サービスの役割が伝わる、明確な小文字の名前を付けてください。例：web、db、cache、worker。
• イメージタグは必ず特定のバージョンに固定してください。latest を使用したり、タグを省略したりしないでください。
• 長時間稼働するインフラサービスや開発環境以外のデプロイでは、restart: unless-stopped を設定してください。
• 外部ツールで予測可能な名前が必要な場合に限り、container_name を追加してください。それ以外の場合は、Compose に名前を生成させてください。

依存関係のモデル化

• 依存先のサービスが起動する前に準備完了している必要がある場合は、condition: service_healthy を指定して depends_on を使用してください。
• ヘルス条件を指定した depends_on に記載する各サービスには、healthcheck を定義する必要があります。
• 条件を指定しない depends_on に頼らないでください。保証されるのはコンテナの起動だけで、準備完了ではありません。

ヘルスチェック

• データベースサービス（Postgres、MySQL、Redis、MongoDB）には、必ず healthcheck を追加してください。
• 利用できる場合は、ヘルスチェックにサービス固有のクライアントツール（例：pg_isready、redis-cli ping、mysqladmin ping）を使用してください。
• 適切な interval、timeout、retries、start_period の値を設定してください。まずは interval: 5s、timeout: 3s、retries: 3、start_period: 10s から始めてください。

distroless または scratch イメージのヘルスチェック

Distroless、scratch ベース、および強化イメージには、シェル、curl、wget が含まれていません。これらのイメージにツールを組み込まないでください。それでは、そうしたイメージを使う目的が損なわれます。代わりに、アプリケーションのネットワーク名前空間を共有するヘルスチェック用サイドカーを使用してください。

services:
  api:
    build:
      context: .
      target: runtime          # distroless / hardened image
    ports:
      - "8080:8080"
    # No healthcheck here — the image has no tools to run one

  api-health:
    image: curlimages/curl:8.22.0
    network_mode: "service:api"   # shares api's localhost
    entrypoint: ["sleep", "infinity"]  # keep sidecar alive for healthcheck
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 45s
    deploy:
      resources:
        limits:
          memory: 32M

要点：

• Compose がサイドカー内でヘルスチェックを実行できるように、サイドカーは entrypoint: ["sleep", "infinity"] で起動したままにしてください。
• network_mode: "service:api" を指定すると、サイドカー内の localhost が api コンテナのループバックを参照するため、追加のネットワーク設定は必要ありません。
• リソース制限を設定して、サイドカーを軽量に保ってください（curl には 32MB で十分です）。
• api の準備完了を待つサービスは、api を直接参照するのではなく、サイドカーを参照してください。

  worker:
    depends_on:
      api-health:
        condition: service_healthy

ボリューム

• コンテナの再作成後も保持する必要があるデータ（データベースデータ、アップロードされたファイル）には、名前付きボリュームを使用してください。
• バインドマウントは、開発時のソースコード同期にのみ使用してください。
• 名前付きボリュームはすべて、トップレベルの volumes: キーで定義してください。
• サービスが本当に必要とする場合を除き、Docker ソケットをマウントしないでください。

ネットワーク

• 単一アプリケーションのスタックでは、デフォルトネットワークで十分です。サービスグループ間の分離が必要な場合を除き、カスタムネットワークを作成しないでください。
• カスタムネットワークを作成する場合は、bridge ドライバーを優先し、用途が分かる名前を付けてください。
• カスタムネットワークはすべて、トップレベルの networks: キーで定義してください。

環境変数

• 数が少なく、機密情報ではない値には environment: を使用します。
• 変数の一覧が長い場合は、.env ファイルを指定する env_file: を使用します。
• パスワードや API キーなどのシークレットを compose.yaml に直接ハードコードしないでください。env_file: または Docker secrets を使用します。
• ローカル開発用に environment: ブロックでデフォルト値が必要な場合は、フォールバック付きの変数置換を使用します：${DB_PASSWORD:-postgres}。パスワード欄に平文の値をそのまま記述しないでください。
• .env を .gitignore に追加します。

開発用オーバーライド

• 開発専用の設定には compose.override.yaml を使用します。Compose はこれを compose.yaml とともに自動的に読み込みます。
• ソースコードのバインドマウント、デバッグポート、開発環境変数はオーバーライドファイルに記述します。
• 対応している場合は、開発時のファイル同期と自動再ビルドに develop.watch を使用します。
• 本番環境向けの設定はベースの compose.yaml に維持し、開発時に変更する設定だけをオーバーライドします。

Compose Watch

• 開発ワークフローでは、手動のバインドマウントより develop.watch を優先します。
• 変更時にコンテナへコピーするファイル（ソースコード）には action: sync を使用します。
• イメージ全体の再ビルドが必要なファイル（package.json や requirements.txt などの依存関係ファイル）には action: rebuild を使用します。
• プロセスの再起動が必要な設定ファイルには action: sync+restart を使用します。

破壊的なコマンド

Compose の一部のコマンドは、データを取り消し不能な形で削除します。以下を実行する前に、どのデータが削除されるかを正確に説明し、ユーザーから明示的な確認を得てください。デバッグ、再起動、スタックの「クリーンアップ」に伴う処理として実行してはいけません。

• docker compose down -v ／ docker compose down --volumes — データベースのデータを含む、名前付きボリュームを削除します。
• Compose プロジェクトのボリュームに対して実行する docker volume rm ／ docker volume prune — ボリュームを直接削除します。Compose プロジェクトが関与しない単独の場合は、docker-destructive-guardrails を参照してください。external: true を介して参照されるボリュームも Compose プロジェクトの管理対象ではありません（down -v では削除されません）。その場合も単独の場合と同様に扱い、まず -f を付けずに docker volume rm を実行し、削除する前に明示的な確認を得てください。
• docker compose rm -v — 削除対象のコンテナに付属する匿名ボリュームを削除します。

サービスの再起動や、コンテナ／ネットワークの解放だけが目的の場合は、代わりに docker compose down（-v なし）または docker compose restart を使用してください。これらのコマンドでは、名前付きボリュームはそのまま残ります。

関連スキル

• Docker プロジェクトの初回のひな形作成と基本ファイルの作成には、docker-project-foundations を使用します。
• Dockerfile の内部構造、ビルドキャッシュ、マルチステージビルド、.dockerignore については、docker-build-strategies を使用します。
• Compose の外部で実行する破壊的な Docker CLI コマンド（docker system prune、docker rm -f、イメージ／ネットワーク／ビルダーのプルーニング、単独のボリューム削除）と、破壊的コマンドに対するガードレールの一覧については、docker-destructive-guardrails を使用します。

リファレンス

• references/service-dependencies.md — depends_on、一般的なデータベースのヘルスチェックパターン、起動順序の戦略について詳しく説明します。
• references/volumes-and-networks.md — ボリュームマウント、名前付きボリューム、バインドマウント、ネットワーク設定のパターンを説明します。

アセット

• assets/compose-web-app.yaml — ヘルスチェック、依存関係、名前付きボリュームを備えた、複数サービスの Web アプリ（app + Postgres + Redis）の完全な例です。
• assets/compose-dev-override.yaml — バインドマウント、デバッグポート、Compose Watch の設定を示す開発用オーバーライドです。
• assets/bad-vs-good.md — Compose でよくある誤りとその修正方法を、修正前／修正後で比較します。

スクリプト

• scripts/verify-compose.sh — 現在のディレクトリにある Compose プロジェクトを、解決済みの設定を出力せずに docker compose config --quiet で検証します。プロジェクトルート（compose.yaml を含むディレクトリ）から、このスキルのディレクトリ内にあるスクリプトのパスを指定して実行してください。

  bash "<skill-dir>/scripts/verify-compose.sh" [--help]
  

  <skill-dir> を、この SKILL.md を含むフォルダーの絶対パスに置き換えてください。scripts/ のパスはプロジェクトではなく、そのフォルダーを基準とします。先にスキルのディレクトリへ移動しないでください。このスクリプトは、現在のディレクトリにある Compose プロジェクトを検証します。スキルのディレクトリを特定できない場合は、docker compose config --quiet を直接実行してください。Compose の設定が有効な場合、またはヘルプが要求された場合の終了ステータスは 0、検証に失敗した場合は docker compose config --quiet のゼロ以外の終了ステータス、不正な引数が指定された場合は 2 です。通常の docker compose config は、補間された認証情報や env_file の認証情報をツールの出力やログに露出する可能性があります。デフォルトでは quiet 検証を使用してください。Compose の警告やエラーは引き続き出力され、機密情報が含まれる場合があります。

チェック

• checks/verification.md — 手動レビュー用の詳細な検証手順書です。