Docker Composeのdepends_onとHEALTHCHECK｜サービス起動順序を確実に制御する設計パターン

この記事のポイント

・depends_on の condition: service_healthy でDBの準備完了を待ってからアプリを起動できる
・HEALTHCHECK 命令でコンテナの「準備完了」基準を定義する（Dockerfile / Composeファイル両方に書ける）
・MySQLは -h 127.0.0.1・start_period: 30s が必須の設定ポイント
・docker inspect と docker events でヘルスチェックのログと進捗をリアルタイム確認できる
・profiles: [dev] でサービスを環境別に選択起動し、開発ツールを本番に混入させない（Compose v2.2以降）
・adminerのポートを 127.0.0.1:8081:8080 にバインドするとdevプロファイルが誤起動されても外部アクセスを防げる
・Mailpit等のSMTPモックを devプロファイルに隔離し、SMTP接続先を環境変数デフォルト値で切り替えられる
・--profile オプションは docker compose の直後・サブコマンドの前に指定する
・initプロファイルを使えばシードデータ投入などの一回限り処理を分離できる
・testプロファイルで専用DBコンテナを分離すればCI専用のクリーンなDB環境を用意できる
・COMPOSE_PROFILES 環境変数や .env ファイルで起動プロファイルを環境ごとに自動切り替えできる
・本番サーバーは /etc/environment や systemd の EnvironmentFile に COMPOSE_PROFILES= を書いて管理できる
・docker compose config --profiles で定義済みプロファイル一覧を確認できる（Compose v2.15以降）
・profiles付きサービスをdepends_onで参照するときは依存関係の設計に注意が必要
・docker compose run --rm でマイグレーション・テスト・シードを1回きり実行できる（終了後コンテナ自動削除）
・GitHub Actions から docker compose --profile ci run --rm migrate でCIマイグレーションを一時起動できる
・docker compose run と docker compose exec の使い分けは「サービスが停止中か起動中か」で判断する
・docker compose exec -it サービス名 bash で起動中コンテナにシェルセッションを開いてデバッグできる
・docker compose run --rm --entrypoint bash でENTRYPOINTを無視してbashを起動しコンテナ内を調査できる
・「no such service」はサービス名のタイポ確認、「container not running」は exec から run への切り替えで解決できる
・deploy.replicas でスケールした各レプリカには独立してヘルスチェックが実行される（Compose v2.x は Swarm なしでも有効）
・deploy.resources.limits でコンテナごとのCPU・メモリ上限を設定し、レプリカ増加時のリソース過消費を防ぐ
・debug プロファイルで netshoot コンテナを app コンテナのネットワーク名前空間に接続し、本番コンテナへの影響ゼロで ss / tcpdump / curl によるネットワーク診断ができる
・.env.dev / .env.production のように環境別 .env ファイルを用意し、cp .env.dev .env だけでプロファイルを自動切り替えできる
・--profile test up --abort-on-container-exit --exit-code-from で CI テスト全体の起動・実行・停止を1コマンドで制御できる
・include ディレクティブで compose.yml を複数ファイルに分割しながら1プロジェクトで管理できる（Compose v2.20以降）
・include で分割しても depends_on のサービス参照と service_healthy による起動順序制御はそのまま機能する
・docker compose config --services でインクルードを含む全サービス一覧を確認できる
・include はファイル全体を取り込む機能で、サービス定義を継承する extends とは目的が異なる

# PostgreSQLの場合
app_1  | sqlalchemy.exc.OperationalError: (psycopg2.OperationalError)
app_1  | could not connect to server: Connection refused
app_1  |     Is the server running on host "db" (172.18.0.2) and accepting
app_1  |     TCP/IP connections on port 5432?

# MySQLの場合
web_1  | Error: connect ECONNREFUSED 172.20.0.2:3306
web_1  | sqlalchemy.exc.OperationalError: (pymysql.OperationalError)
web_1  | (2003, "Can't connect to MySQL server on 'db' (111)")

# condition を省略した例（service_started と同義）
services:
  app:
    image: myapp:latest
    depends_on:
      - db       # プロセス起動のみ確認。DB準備完了は保証しない
  db:
    image: postgres:16

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy   # dbがhealthyになるまで起動しない
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully  # マイグレーション完了後に起動
  migrate:
    image: myapp:latest
    command: python manage.py migrate
    depends_on:
      db:
        condition: service_healthy   # マイグレーション自体もDBのhealthy待ち
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

# PostgreSQLイメージに対するHEALTHCHECKの例
FROM postgres:16

# pg_isready でDBが接続を受け付けているか確認
HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=5   CMD pg_isready -U postgres || exit 1

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 5s
      start_period: 10s
      retries: 5

# MySQL 8.0 のヘルスチェック
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: appdb
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-u", "root", "-psecret"]
      interval: 5s
      timeout: 5s
      start_period: 30s   # MySQLは初期化に時間がかかるため長めに設定
      retries: 5

# Redis のヘルスチェック（redis-cli ping が PONG を返せば healthy）
services:
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      interval: 5s
      timeout: 3s
      start_period: 5s
      retries: 3

# exec形式（JSON配列・シェルを経由しない・推奨）
HEALTHCHECK --interval=10s --timeout=5s --retries=3   CMD ["curl", "-fsS", "http://localhost:8080/health"]

# shell形式（/bin/sh -c を経由する・パイプを使いたい場合のみ）
HEALTHCHECK --interval=10s --timeout=5s --retries=3   CMD redis-cli ping | grep PONG

# 親イメージのHEALTHCHECKを無効化する
FROM mybaseimage:latest
HEALTHCHECK NONE

# docker-compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 5s
      start_period: 10s
      retries: 5
    volumes:
      - pgdata:/var/lib/postgresql/data

  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: "postgresql://appuser:secret@db:5432/appdb"
    depends_on:
      db:
        condition: service_healthy   # dbがhealthyになってから起動
    restart: on-failure              # 接続失敗時にリスタート

volumes:
  pgdata:

$ docker compose up -d
[+] Running 2/2
 ✔ Container sample-db-1   Healthy    6.5s
 ✔ Container sample-app-1  Started    6.8s

$ docker compose ps
NAME             IMAGE          STATUS                   PORTS
sample-app-1     myapp:latest   Up 10 seconds            0.0.0.0:8000->8000/tcp
sample-db-1      postgres:16    Up 15 seconds (healthy)  5432/tcp

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: myapp
      MYSQL_USER: appuser
      MYSQL_PASSWORD: apppass
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-u", "root", "-prootpass"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  migrate:
    image: myapp:latest
    command: python manage.py migrate
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: mysql+pymysql://appuser:apppass@db:3306/myapp

  web:
    image: myapp:latest
    ports:
      - "8000:8000"
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully  # マイグレーション完了後に起動
    environment:
      DATABASE_URL: mysql+pymysql://appuser:apppass@db:3306/myapp

volumes:
  db_data:

# コンテナ名を確認
$ docker compose ps

# ヘルスチェック詳細を取得（JSON整形表示）
$ docker inspect --format='{{json .State.Health}}' sample-db-1 | python3 -m json.tool

# 出力例（失敗している場合）
{
    "Status": "unhealthy",
    "FailingStreak": 3,
    "Log": [
        {
            "Start": "2026-07-07T08:00:01.234Z",
            "End":   "2026-07-07T08:00:01.239Z",
            "ExitCode": 1,
            "Output": "pg_isready: error: connection to server at localhost failed"
        }
    ]
}

# health_statusイベントのみフィルタ（別ターミナルで実行）
$ docker events --filter event=health_status

2026-07-07T08:00:01.000000000+09:00 container health_status sample-db-1 (health_status=starting)
2026-07-07T08:00:11.000000000+09:00 container health_status sample-db-1 (health_status=unhealthy)
2026-07-07T08:00:51.000000000+09:00 container health_status sample-db-1 (health_status=healthy)

# Composeファイルの解釈結果を表示する（パースエラーも検出できる）
$ docker compose config

# 特定サービスのhealthcheck設定だけ確認する
$ docker compose config | grep -A 8 'healthcheck'
    healthcheck:
      interval: 5s
      retries: 5
      start_period: 10s
      test:
      - CMD-SHELL
      - pg_isready -U appuser -d appdb
      timeout: 5s

# MySQLコンテナに入ってmysqladmin pingを直接実行
$ docker compose exec db mysqladmin ping -h 127.0.0.1 -u root -prootpass
mysqladmin: [Warning] Using a password on the command line interface can be insecure.
mysqld is alive

# exit codeが0かどうか確認（0ならhealthyと判定される）
$ echo $?
0

# curlによるHTTPエンドポイントの確認（-f: 4xx/5xxで終了コード22を返す）
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 10s
  timeout: 5s
  start_period: 15s
  retries: 3

# curlがない場合はncでTCPポート確認（-z: 接続のみ -w 1: 1秒タイムアウト）
healthcheck:
  test: ["CMD", "nc", "-z", "-w", "1", "localhost", "8080"]
  interval: 10s
  timeout: 5s
  start_period: 15s
  retries: 3

# ヘルスチェックが設定されているか確認する
$ docker inspect sample-db-1 --format='{{json .Config.Healthcheck}}'

# 設定なしの場合（healthcheckを追加する必要がある）
null

# 設定ありの場合
{"Test":["CMD-SHELL","pg_isready -U appuser -d appdb"],"Interval":5000000000,"Timeout":5000000000,"StartPeriod":10000000000,"Retries":5}

# 問題のある「全部入り」compose.yaml の例
services:
  app:
    image: myapp:latest
    ports:
      - "8080:8080"

  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

  # 開発時だけ使いたいDB管理ツール
  pgadmin:
    image: dpage/pgadmin4:latest
    ports:
      - "5050:80"

  # 障害調査時だけ使いたい監視ツール
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"

volumes:
  db-data:

# compose.yml
services:
  # profilesなし → 全環境で常に起動する共通サービス
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy

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

  # devプロファイル専用（--profile dev 指定時のみ起動）
  adminer:
    image: adminer
    profiles: [dev]
    ports:
      - "8080:8080"

  # devとstagingの両環境で使うメールトラップ（Mailpit）
  mailpit:
    image: axllent/mailpit
    profiles: [dev, staging]
    ports:
      - "1025:1025"   # SMTP
      - "8025:8025"   # Web UI

  # 本番・負荷試験環境の監視スタック
  prometheus:
    image: prom/prometheus:latest
    profiles: [monitoring]
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

# profilesなしで起動（デフォルトサービスのみ）
$ docker compose up -d
[+] Running 2/2
 ✔ Container myapp-db-1   Started
 ✔ Container myapp-app-1  Started

$ docker compose ps
NAME            IMAGE          STATUS    PORTS
myapp-app-1     myapp:latest   Up        0.0.0.0:8000->8000/tcp
myapp-db-1      postgres:16    Up        5432/tcp

# devプロファイルを指定（開発ツールが追加起動される）
$ docker compose --profile dev up -d
[+] Running 4/4
 ✔ Container myapp-db-1       Running
 ✔ Container myapp-app-1      Running
 ✔ Container myapp-adminer-1  Started
 ✔ Container myapp-mailpit-1  Started

services:
  app:
    image: myapp:latest
    ports:
      - "8080:8080"

  prometheus:
    image: prom/prometheus:v2.52.0
    profiles:
      - monitoring
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus

  grafana:
    image: grafana/grafana:10.4.0
    profiles:
      - monitoring
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_PASSWORD: admin
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - prometheus

volumes:
  prometheus_data:
  grafana_data:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10

  db-seed:
    image: myapp:latest
    profiles:
      - init
    command: ["python", "manage.py", "seed_data"]
    environment:
      DATABASE_URL: postgresql://postgres:secret@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy
    restart: "no"

# DBが healthy になるのを待ってシードを実行する
docker compose --profile init up db-seed

# 終了したコンテナをクリーンアップ
docker compose --profile init rm db-seed

services:
  redis-commander:
    image: rediscommander/redis-commander:latest
    profiles:
      - dev
      - staging
    ports:
      - "8081:8081"
    environment:
      REDIS_HOSTS: local:redis:6379
    depends_on:
      - redis

services:
  redis:
    image: redis:7-alpine

  redis-insight:
    image: redislabs/redisinsight:latest
    ports:
      - "127.0.0.1:5540:5540"
    profiles:
      - dev
      - debug

# 正しい設計：依存するサービス間で同じprofiles名を共有する
services:
  grafana:
    image: grafana/grafana
    depends_on:
      - prometheus
    profiles:
      - monitoring   # prometheusと同じプロファイル名

  prometheus:
    image: prom/prometheus
    profiles:
      - monitoring   # grafanaと同じプロファイル名

# NG: profiles名が食い違う設計
services:
  grafana:
    image: grafana/grafana
    depends_on:
      - prometheus
    profiles:
      - monitoring   # grafanaはmonitoringプロファイル

  prometheus:
    image: prom/prometheus
    profiles:
      - infra        # prometheusはinfraプロファイル（食い違いでエラーになる）

services:
  app:
    image: myapp:latest
    environment:
      SMTP_HOST: ${SMTP_HOST:-mailpit}   # 環境変数未設定時はmailpitに接続
      SMTP_PORT: ${SMTP_PORT:-1025}

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret

  # DEV専用: メールデバッグ（受信したメールをWeb UIで確認できるSMTPモック）
  mailpit:
    image: axllent/mailpit:latest
    profiles: [dev]
    ports:
      - "127.0.0.1:8025:8025"   # Web UI（localhost限定バインド）
      - "127.0.0.1:1025:1025"   # SMTP（localhost限定バインド）

  # DEV専用: DB管理UI
  adminer:
    image: adminer:latest
    profiles: [dev]
    ports:
      - "127.0.0.1:8080:8080"   # localhost限定バインド（誤起動時の外部公開を防ぐ）
    depends_on:
      - db

  # DEV専用: ローカルS3互換（S3 APIのローカル検証に使う）
  minio:
    image: minio/minio:latest
    profiles: [dev]
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: devuser
      MINIO_ROOT_PASSWORD: devpassword
    ports:
      - "9000:9000"
      - "9001:9001"

services:
  app:
    image: myapp:latest
    ports:
      - "8080:8080"

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

  # debug プロファイル専用のネットワーク診断コンテナ
  debug:
    image: nicolaka/netshoot
    profiles:
      - debug
    network_mode: "service:app"   # app コンテナのネットワーク名前空間を共有
    stdin_open: true
    tty: true
    command: ["sleep", "infinity"]

# debug コンテナで診断（app コンテナのネットワーク名前空間を共有）
$ docker compose --profile debug up -d
$ docker compose exec debug bash

# app コンテナの localhost:8080 に直接アクセス可能
bash-5.2# curl -s http://localhost:8080/ | head -3

# app コンテナが listening しているポートを確認
bash-5.2# ss -tlnp
State    Recv-Q   Send-Q   Local Address:Port
LISTEN   0        511      0.0.0.0:8080

# TCP接続をリアルタイム監視
bash-5.2# tcpdump -i any -n tcp port 8080

# 調査終了後は debug コンテナのみ停止（app・db はそのまま）
$ docker compose stop debug

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

  # testプロファイル: テスト専用DBコンテナ（本番DBとは独立して起動）
  db-test:
    image: postgres:16
    environment:
      POSTGRES_DB: testdb
      POSTGRES_USER: testuser
      POSTGRES_PASSWORD: testpass
    profiles:
      - test
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U testuser -d testdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  # testプロファイル: マイグレーション＋シードをまとめて実行
  migrate:
    image: myapp:latest
    profiles:
      - test
    command: ["sh", "-c", "python manage.py migrate && python manage.py seed"]
    depends_on:
      db-test:
        condition: service_healthy

  # testプロファイル: テスト実行コンテナ（マイグレーション完了後に起動）
  app-test:
    image: myapp:latest
    profiles:
      - test
    command: ["python", "-m", "pytest", "tests/"]
    environment:
      DATABASE_URL: postgresql://testuser:testpass@db-test:5432/testdb
    depends_on:
      migrate:
        condition: service_completed_successfully

# CIでテスト全体を一括実行（GitHub Actions の run: に書く）
$ docker compose --profile test up --abort-on-container-exit --exit-code-from app-test

# 実行ログ例（db-test → migrate → app-test の順に起動）
[+] Running 4/4
 ✔ Container myapp-db-1          Healthy
 ✔ Container myapp-db-test-1     Healthy
 ✔ Container myapp-migrate-1     Exited (0)
 ✔ Container myapp-app-test-1    Exited (0)

# 環境変数で直接指定（カンマ区切りで複数プロファイルを同時指定）
export COMPOSE_PROFILES=dev,tools
docker compose up -d

# .env ファイルに書いておく方法（プロジェクトルートの .env に追記）
COMPOSE_PROFILES=dev

# .env が反映されているか確認
docker compose config | grep -A 1 COMPOSE_PROFILES

# 本番サーバーの /etc/environment に書く例（プロファイルなし＝devツール不起動）
COMPOSE_PROFILES=

# systemd サービスの EnvironmentFile に指定する例
# /etc/myapp/compose-env
COMPOSE_PROFILES=monitoring

# systemd ユニットファイル（抜粋）
[Service]
EnvironmentFile=/etc/myapp/compose-env
ExecStart=/usr/bin/docker compose up -d

# 定義済みプロファイル一覧を確認（Compose v2.15以降）
$ docker compose config --profiles
dev
monitoring
staging

# profilesオプションなしで起動するサービス一覧を確認
$ docker compose config --services
app
db
# profiles を付けたサービスはここに出てこない

# 特定のプロファイルを指定した場合のサービス一覧を確認
$ docker compose --profile dev config --services
app
db
adminer
mailpit

# .env.dev（開発環境用）
DB_PASSWORD=devpassword
COMPOSE_PROFILES=dev

# .env.monitoring（監視有効化用）
DB_PASSWORD=prodpassword
COMPOSE_PROFILES=monitoring

# .env.production（本番用。プロファイルは何も指定しない）
DB_PASSWORD=strongpassword
COMPOSE_PROFILES=

# 開発環境を起動する
$ cp .env.dev .env
$ docker compose up -d
# → COMPOSE_PROFILES=dev が読み込まれ、devプロファイルのサービスも起動する

# 本番環境を起動する
$ cp .env.production .env
$ docker compose up -d
# → COMPOSE_PROFILES= なので devサービスは起動しない

# dev プロファイルのサービスをプロファイル名でまとめて停止する（推奨）
$ docker compose --profile dev stop
[+] Stopping 2/2
 ✔ Container myapp-adminer-1   Stopped
 ✔ Container myapp-mailpit-1   Stopped

# サービス名を直接指定して個別に停止する
$ docker compose stop adminer

# dev プロファイルのサービスを名前指定でまとめて停止する
$ docker compose stop adminer mailpit

# compose.yaml（メインファイル）
include:
  - infra/compose.yaml
  - monitoring/compose.yaml

services:
  api:
    build: ./api
    depends_on:
      postgres:
        condition: service_healthy   # infra/compose.yaml に定義した postgres を参照

myproject/
├── compose.yaml          # メインファイル（includeのみ記述）
├── infra/
│   ├── compose.yaml      # postgres, redis
│   └── .env
├── app/
│   ├── compose.yaml      # api, worker
│   └── Dockerfile
└── monitoring/
    ├── compose.yaml      # prometheus, grafana（profilesと組み合わせも可）
    └── prometheus.yml

# compose.yaml（メイン）
include:
  - path: infra/compose.yaml
    project_directory: ./infra
  - path: app/compose.yaml
    project_directory: ./app
  - path: monitoring/compose.yaml
    project_directory: ./monitoring

# インクルード後の全サービスを確認
$ docker compose config --services
api
grafana
postgres
prometheus
redis

# 分割ファイルを含めた最終的なYAML定義を確認（パースエラーも検出できる）
$ docker compose config

# 基本構文
docker compose run [オプション] サービス名 [コマンド [引数...]]

# Djangoのマイグレーション（--rmで終了後コンテナを自動削除）
$ docker compose run --rm app python manage.py migrate

# Laravelのマイグレーション
$ docker compose run --rm app php artisan migrate

# Railsのマイグレーション
$ docker compose run --rm app bin/rails db:migrate

# pytestでテストを実行（終了コードがCIの成否判定に使える）
$ docker compose run --rm app pytest tests/ -v

# 依存サービスを起動せずに staticfiles だけ収集する
$ docker compose run --rm --no-deps app python manage.py collectstatic --noinput

# DATABASE_URLだけをステージング環境のものに差し替えてマイグレーション
$ docker compose run --rm   -e DATABASE_URL=postgresql://user:pass@staging-db.example.com:5432/stg   app python manage.py migrate

# compose.yml の migrate サービスを ci プロファイルに分離する
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 5

  migrate:
    image: myapp:latest
    command: ["python", "manage.py", "migrate"]
    depends_on:
      db:
        condition: service_healthy
    profiles:
      - ci    # CIプロファイル指定時のみ起動

  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy

# GitHub Actions の steps 例
- name: Run DB migration
  run: docker compose --profile ci run --rm migrate

# CI実行ログ（DBが healthy になってからマイグレーションが走る）
[+] Running 2/2
 ✔ Network myapp_default   Created
 ✔ Container myapp-db-1    Healthy
Operations to perform:
  Apply all migrations: auth, contenttypes, myapp
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying myapp.0001_create_users... OK

# ENTRYPOINTを無視してbashを起動する
docker compose run --rm --entrypoint bash app

docker compose exec [オプション] サービス名 コマンド

# 起動中の db コンテナにシェルで接続する
docker compose exec -it db bash

# Webサーバーの設定ファイルを確認する
docker compose exec web cat /etc/nginx/nginx.conf

# MariaDB コンテナで SQL を直接実行する
docker compose exec -it db mariadb -u root -ppassword myapp

# 起動中コンテナの環境変数を確認する
docker compose exec app env | grep -i database

# エラー例（出力例・環境により異なります）
No service found with name "aap"

# 対処: compose.yml の services: 配下のキーを確認する
docker compose config --services

# エラー例（出力例・環境により異なります）
Error response from daemon: container not running

# コンテナの稼働状況を確認する
docker compose ps

# コンテナが停止していた場合はrunを使う
docker compose run --rm サービス名 コマンド

# ポートバインドを有効にしてrunする
docker compose run --rm --service-ports web bash

# プロジェクトに紐付く停止済みコンテナを削除
$ docker compose rm -f

# 全停止コンテナをまとめて削除（他プロジェクトも含む）
$ docker container prune

# 停止済みコンテナを確認してから削除
$ docker ps -a --filter status=exited

# SQLAlchemy の接続リトライ設定例
from sqlalchemy import create_engine

engine = create_engine(
    "postgresql://appuser:secret@db:5432/appdb",
    pool_pre_ping=True,         # 使用前に接続確認
    pool_recycle=3600,          # 1時間で接続を再作成
    connect_args={"connect_timeout": 10}
)

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy
        required: true    # dbがないと起動しない（デフォルト）
      redis:
        condition: service_healthy
        required: false   # redisが起動できなくてもappは起動する
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      interval: 5s
      timeout: 3s
      retries: 3

# NG: profilesなしのappがprofiles付きのmailpitをdepends_onで参照
services:
  app:
    image: myapp:latest
    depends_on:
      mailpit:
        condition: service_healthy   # devプロファイル未指定だと起動不能
  mailpit:
    image: axllent/mailpit
    profiles:
      - dev

# OK: 環境変数をデフォルト値付きにして疎結合にする
services:
  app:
    image: myapp:latest
    environment:
      - MAIL_HOST=localhost
      - MAIL_PORT=25
    # mailpit への depends_on は書かない
  mailpit:
    image: axllent/mailpit
    profiles:
      - dev

# 設定を確認するコマンド一覧
$ echo $COMPOSE_PROFILES          # 現在の環境変数を確認
$ docker compose config --profiles  # 定義済みプロファイル一覧を確認（v2.15以降）
$ docker compose config           # YAML展開後の定義を確認
$ docker compose --profile dev config | grep -A 5 adminer  # devプロファイルでのadminer定義を確認
$ docker compose --profile dev ps --all  # devプロファイル込みで全サービス確認

# CIや本番デプロイスクリプトでCOMPOSE_PROFILESの影響を受けないようにする
$ env -u COMPOSE_PROFILES docker compose up -d

services:
  db:
    image: postgres:16
    deploy:
      replicas: 2          # 2台起動。各コンテナにヘルスチェックが独立実行される
      resources:
        limits:
          cpus: "0.50"
          memory: 512M    # 2台 × 512MB = 最大1GB消費になるため注意
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      start_period: 15s    # 複数起動時は初期化の競合を考慮して長めに設定
      retries: 5

  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy