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

この記事のポイント

・depends_on の condition: service_healthy でDBの準備完了を待ってからアプリを起動できる
・HEALTHCHECK 命令でコンテナの「準備完了」基準を定義する（Dockerfile / Composeファイル）
・curl・nc・独自スクリプトで用途に合わせたヘルスチェックを設計できる
・docker inspect でヘルスチェックのログとExitCodeを確認してデバッグできる

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?

# 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", "localhost", "-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

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

# ヘルスチェック詳細を取得
$ docker inspect sample-db-1 | python3 -m json.tool | grep -A 20 '"Health"'

# 出力例（失敗している場合）
"Health": {
    "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"
        }
    ]
}

# 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}

# 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