docker-compose

Docker Compose — 多コンテナーのオーケストレーションと Compose ファイル

本番環境向けの Docker Compose 構成を作成するための専門的なガイダンスです。

使用するタイミング

ユーザーが次のことに言及した場合は、必ずこのスキルを使用します。

• 「docker compose」、「docker-compose.yml」、「compose ファイル」
• 「compose の書き方」、「compose の設定」
• 「複数コンテナー」、「multi-container」、「サービスのオーケストレーション」
• 「depends_on」、「profiles」、「override」
• 「compose network」、「compose volume」

ファイル構成全体

# compose.yml
name: myapp

services:       # Container definitions
networks:       # Network topology
volumes:        # Persistent storage
secrets:        # Sensitive data (Swarm)
configs:        # Non-sensitive configs (Swarm)

サービス — コア設定

services:
  web:
    image: myapp:${TAG:-latest}     # Pull from registry
    # build: .                      # Or build from Dockerfile
    # build:                        # Build with options
    #   context: .
    #   dockerfile: Dockerfile.prod

    container_name: myapp-web       # Explicit name (optional)
    hostname: web

    ports:
      - "8080:8080"                 # host:container
      - "127.0.0.1:8443:443"       # bind to localhost
      - "8080:8080/udp"            # UDP

    environment:
      - NODE_ENV=production
      - DB_HOST=db                  # Service name = hostname!
    # env_file: .env.production    # Load from file

    volumes:
      - app-logs:/var/log/app       # Named volume
      - ./config:/etc/app:ro        # Bind mount (read-only)
      - /tmp/app:/tmp               # Bind mount (read-write)

    depends_on:
      db:
        condition: service_healthy  # Wait for health check
      redis:
        condition: service_started

    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

    restart: unless-stopped

    deploy:                         # Swarm-only
      replicas: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

    profiles:                       # Optional service
      - debug

ネットワーク

デフォルトネットワーク（自動作成）

# Compose auto-creates a default bridge network.
# All services can reach each other by service name.
services:
  web:
    ports: ["8080:8080"]
  db:
    # No ports exposed externally — only accessible by 'web'

カスタムネットワーク

networks:
  frontend:                        # Public-facing
  backend:
    internal: true                 # No external access

services:
  web:
    networks: [frontend, backend]  # In both networks
  db:
    networks: [backend]            # Backend only (isolated)
  cache:
    networks: [backend]

環境変数

設定方法

方法	場所	最適な用途
environment:	compose.yml 内	変数が少ないシンプルな設定
env_file:	外部の .env.prod	変数が多い環境固有の設定
.env ファイル	プロジェクトルート（自動読み込み）	デフォルト値、$VARIABLE の置換

.env ファイル（自動読み込み）

# .env — auto-loaded by docker compose
TAG=v1.2.3
DB_PASSWORD=secret123

# compose.yml — uses ${TAG} and ${DB_PASSWORD}
services:
  web:
    image: myapp:${TAG:-latest}
  db:
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

env_file

# .env.production
DB_HOST=prod-db.example.com
DB_PORT=5432

services:
  web:
    env_file: .env.production

Depends On — サービスの起動順序

services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5

  web:
    depends_on:
      db:
        condition: service_healthy   # Wait for DB to be ready
      redis:
        condition: service_started   # Wait for Redis to start

Profiles — オプションのサービス

services:
  app:
    image: myapp

  debug-tools:
    image: nicolaka/netshoot
    command: sleep infinity
    profiles: [debug]                # Only starts with --profile

  elasticsearch:
    image: elasticsearch:8.15.0
    profiles: [analytics]            # Only starts with --profile

docker compose --profile debug up    # Starts app + debug-tools
docker compose --profile analytics up # Starts app + elasticsearch

Override による複数環境への対応

compose.yml                # Base configuration
compose.override.yml       # Local dev overrides (auto-applied)
compose.prod.yml           # Production overrides

# Local: compose.yml + compose.override.yml (auto)
docker compose up -d

# Production: explicit files
docker compose -f compose.yml -f compose.prod.yml up -d

Kubernetes への移行

kompose convert -f compose.yml   # Generates K8s YAML files
kubectl apply -f .

ワークフロー — 推奨されるオーケストレーション手順

Step 1: サービスを計画する: すべてのサービス、ポート、データボリューム、環境変数を一覧にします Step 2: compose.yml を作成する: services/networks/volumes を定義します Step 3: 依存関係を設定する: depends_on + condition: service_healthy Step 4: ローカルで検証する: docker compose up -d → docker compose ps → docker compose logs Step 5: 本番環境にデプロイする: resource limits、restart policy、ログローテーションを追加します → docker compose -f compose.yml -f compose.prod.yml up -d

注意点 — よくある落とし穴

• healthcheck のない depends_on: depends_on はコンテナーの起動を待つだけで、準備完了までは待ちません。→ 対処法: 必ず condition: service_healthy と healthcheck: ブロックを追加します。docker compose ps を使ってヘルスステータスを確認してください。
• ポートの競合: 複数のサービスで同じホストポートをバインドすることはできません。→ 対処法: 別のホストポートを使用するか、内部通信のみのサービスでは ports: を削除します（サービス名を通じて通信します）。
• バインドマウントのパス: 相対パスは Compose ファイルの場所を基準に解決されます。→ 対処法: config/ ではなく ./config を使用します。docker compose config で解決済みのパスを確認してください。
• .env ファイルのセキュリティ: .env ファイルにはシークレットが含まれていることがよくあります。→ 対処法: .env を .gitignore に追加します。Swarm では Docker secrets を使用し、プレースホルダー値を含む .env.example を用意してください。
• docker compose と docker-compose の違い: 現在の構文は docker compose（プラグイン）です。→ 対処法: docker-compose（スタンドアロンバイナリ）は非推奨です。常に docker compose（スペース区切り）を使用してください。

境界 — 能力の範囲（適用する場面と適用しない場面）

分類	場面	説明
✅ 対応可能	複数コンテナーアプリケーションのオーケストレーション	services/networks/volumes/secrets/configs をすべて定義できます
✅ 対応可能	環境管理	.env / env_file / override ファイルの方針
✅ 対応可能	依存関係の制御	depends_on + healthcheck + profiles
⚠️ 条件付き	複数ホストへのデプロイ	Swarm（docker stack deploy）または K8s に移行します
⚠️ 条件付き	ローリングアップデート／自動スケーリング	Compose は非対応です。Swarm または K8s が必要です
❌ 対象外	Dockerfile の作成	docker-dockerfile を使用してください
❌ 対象外	K8s のデプロイ	kompose convert + K8s スキルを使用してください
❌ 対象外	クラウドサービスのオーケストレーション（Terraform）	IaC ツール

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

❌ 使用しない	✅ 代わりに使用
単一コンテナーのアプリ	docker-run
Dockerfile の作成	docker-dockerfile
Kubernetes のデプロイ	K8s マニフェスト／Helm チャート
Docker の基本	docker-basics

セキュリティと安定性

• 外部からのアクセスを防ぐため、バックエンドネットワークには internal: true を使用します。
• シークレットを含む .env ファイルをコミットしないでください。CI シークレットまたは Docker Swarm secrets を使用します。
• 単一ホストでの本番 Compose では、起動時の自動実行のために systemd と組み合わせます。
• 複数ホストでの本番環境では、Swarm（docker stack deploy）または Kubernetes に移行します。

📚 公式ドキュメントの参考資料

ドキュメント	URL
Docker Compose の概要	https://docs.docker.com/compose/
Compose ファイルのリファレンス	https://docs.docker.com/reference/compose-file/
Compose CLI	https://docs.docker.com/reference/cli/docker/compose/
環境変数	https://docs.docker.com/compose/environment-variables/
Compose ネットワーク	https://docs.docker.com/compose/networking/
本番環境での Compose	https://docs.docker.com/compose/production/

🧭 Docker スキルの道のり

📍 現在地：docker-compose — マルチコンテナのオーケストレーション

← 前へ：docker-buildx / docker-networking → 次へ：docker-production / docker-cicd