docker-compose

Docker Compose

アプリケーションのモデル化、解決済み設定の検証、サービスの起動または更新、実行時の状態確認、障害の診断など、Compose のライフサイクル全体でこのスキルを使用してください。現行の Compose Specification を優先してください。新しいファイルにトップレベルの version キーを追加しないでください。これは廃止されており、スキーマを選択するものではありません。

運用サイクル

1. 調査：Compose ファイル、プロジェクトディレクトリ、env ファイル、プロファイル、外部リソースを特定し、タスクが開発、CI、ステージング、本番のいずれに当たるかを確認します。
2. モデル化：サービス、永続データ用の名前付きボリューム、分離用の明示的なネットワーク、機密ファイル用のシークレット、オプションのサービス用のプロファイルを設定します。
3. 実行前に解決：

   docker compose -f compose.yaml config --quiet
   docker compose -f compose.yaml config
   docker compose -f compose.yaml config --services
   

4. 操作：up -d SERVICE、restart SERVICE、run --rm SERVICE COMMAND、exec SERVICE COMMAND など、対象を絞ったコマンドを使用します。データの削除が意図的で、確認済みの場合を除き、down -v は避けてください。
5. 検証：ps、ヘルスステータス、ログ、コンテナ内での確認、該当する場合は外部に公開されたエンドポイントを確認します。
6. 順に診断：解決済みモデル → コンテナの状態 → ログ → ヘルスチェック → ネットワークメンバーシップ／DNS → マウント／権限 → イメージ／ビルドのアーキテクチャ → ホストリソース。

判断基準

• depends_on が制御するのは作成順であり、準備完了状態ではありません。実際の healthcheck と condition: service_healthy を使用してください。マイグレーションやジョブには service_completed_successfully を使用します。準備完了の判定に sleep を使用しないでください。
• コンテナは、兄弟サービスにサービス名とコンテナポート（db:5432）でアクセスします。ホストに公開されたポートやコンテナの IP アドレスではありません。
• 単純なプロジェクトではデフォルトネットワークを使用します。階層を分離するにはネットワークを分け、外部ゲートウェイのないネットワークには internal: true を設定します。プロジェクト外で作成されたネットワークを使う場合に限り、明示的に名前を指定した external: true ネットワークを使用します。
• 開発中のソース／設定にはバインドマウント、状態の保存には名前付きボリューム、変更されない入力には読み取り専用マウントを使用します。ホストパスのマウントはプラットフォームによって動作が異なることを考慮してください。
• 認証情報は、イメージ、Git、通常の環境変数ではなく、Compose のシークレットまたは外部のシークレットマネージャーに保管します。各シークレットへのアクセスは、必要とするサービスだけに許可してください。Compose のシークレットは /run/secrets/<name> にマウントされます。
• デバッグ、マイグレーション、オブザーバビリティ、GPU ワークロードなど、オプションのツールにはプロファイルを使用します。コアサービスにはプロファイルを設定しないでください。
• インターポレーションを明示的に解決します。シェル変数は --env-file より優先され、--env-file はプロジェクトの .env より優先されます。必須の値には ${REQUIRED:?explain} を使用し、ドル記号をそのまま使うには $$ を使用します。たとえば、Compose ではなくコンテナのシェルで変数を展開する必要がある場合は、test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"] と記述します。docker compose config --environment で確認してください。
• 複数ファイルをマージする場合、後続のファイルがベースファイルに適用されます。相対パスは最初のファイル（ベースファイル）を基準に解決されます。結果を docker compose config で確認してください。通常のマージ動作が望ましくない場合は、!reset または !override を使用します。
• Compose Watch は、ローカルソースからビルドされるサービス向けです。ホットリロード可能なソースには sync、設定には sync+restart、依存関係やイメージの変更には rebuild を使用します。コンテナのユーザーには、対象パスへの書き込み権限が必要です。
• deploy フィールドの動作は実装によって異なるものとして扱ってください。対象の Compose 実装で何が適用されるかを確認してください。仕様では、一部のみのサポートが明示的に認められています。

クイックコマンド一覧

docker compose version
docker compose config --quiet
docker compose up -d --build
docker compose ps
docker compose logs -f --tail=100 SERVICE
docker compose exec SERVICE COMMAND
docker compose run --rm SERVICE COMMAND
docker compose restart SERVICE
docker compose stop
docker compose down                    # preserves named volumes
docker compose down --remove-orphans
docker compose pull && docker compose up -d
docker compose --profile debug up -d
docker compose up --watch
docker compose port SERVICE CONTAINER_PORT
docker network inspect PROJECT_default
docker volume inspect PROJECT_VOLUME

高価値なデフォルト設定

• compose.yaml と同じ場所に compose.override.yaml があり、-f ファイルが指定されていない場合、Compose はオーバーライドを自動的に読み込みます。本番環境の組み合わせには、明示的に -f ファイルを指定してください。
• 破壊的な CI ゲート： docker compose -p ci-${CI_JOB_ID:?CI_JOB_ID is required} config --services で分離されたプロジェクト名を確認するまで、down --volumes は実行しないでください。共有環境では、対象データの範囲を明確に意図している場合を除き、--volumes を省略してください。
• deploy のリソースおよび配置フィールドは、対象によって動作が異なるものとして扱ってください。レンダリングされたフィールドが有効でも、ローカルの実装では無視されることがあります。実行時に適用されていることを確認してください。

base／dev／prod コマンドマトリックス

# Base or default development override
docker compose config --quiet
docker compose up --watch

# Explicit production model
IMAGE_TAG=release-1 docker compose -f compose.yaml -f compose.prod.yaml config --quiet
IMAGE_TAG=release-1 docker compose -f compose.yaml -f compose.prod.yaml up -d

# Optional tooling
docker compose --profile debug up -d

デフォルトの compose.override.yaml は自動的に読み込まれます。本番環境用のオーバーライドは明示的に選択してください。

レンダリングされた設定は、実行時の証明にはなりません。 config では、シークレットの宣言、リソース制限、ヘルスチェックが含まれていることを確認できます。しかし、シークレットファイルがマウントされていること、ヘルスチェックが成功すること、対象の実装で deploy の制限が適用されることを証明できるのは、実行時の検査だけです。対象ホストで exec、ps、inspect を使って確認し、動作を測定してください。

リファレンスの参照先

読み込むタイミング	リファレンス
プロジェクトの開始時、またはプリミティブの選択時	references/01-model-and-file-design.md
依存関係、ヘルスチェック、シャットダウン、またはジョブについて	references/02-lifecycle-and-health.md
DNS、ポート、ネットワーク、ボリューム、または永続化について	references/03-networking-and-storage.md
.env、補間、プロファイル、またはオーバーライドについて	references/04-configuration-and-overrides.md
Watch、ビルド、CI、または本番環境の運用について	references/05-development-and-production.md
シークレット、最小権限、またはサプライチェーン上の懸念について	references/06-security.md
障害に体系的なワークフローが必要な場合	references/07-troubleshooting.md
CLI コマンドまたはフィールドの検索	references/08-command-playbook.md
ソースの網羅状況と鮮度チェック	references/00-source-index.md

同梱される成果物

• templates/：移植可能な base、開発、本番、環境、シークレットファイルの各例。
• assets/project-review-checklist.md：引き継ぎおよびデプロイ前のレビューチェックリスト。
• scripts/compose-doctor.sh：テキストまたは JSON 形式で出力する、決定論的な検証および実行時診断。

障害の境界

• config --quiet で証明できるのはモデルの解決であり、イメージのプル、起動、アプリケーションの正しさではありません。
• コンテナが実行中でも、サービスの準備が整っているとは限りません。ヘルスチェックが成功しても、エンドツーエンドの検証にはなりません。
• docker compose down はプロジェクトのコンテナとネットワークを削除しますが、通常、名前付きボリュームは保持されます。down -v は破壊的な操作です。

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

Kubernetes、Swarm のスケジューリング、または他のプラットフォームのデプロイコントローラーを使う場合は、そのオーケストレーター専用のスキルを使用してください。Compose では一部のデプロイ概念を記述できますが、そのプラットフォームの運用 API の代わりにはなりません。