kind: capsule status: active visibility: private license: fair-use-summary summary: Compose healthcheck + depends_on condition: service_healthy로 의존 서비스 준비 대기. CMD vs CMD-SHELL 구분, start_period 필수. tags: - docker - compose - ops - capsule related: - personal_vault/knowledge/dev/docker-compose-guide.md - personal_vault/projects/personal/insu-server/

Docker Compose Healthcheck Capsule

Core claim#

Compose에서 depends_on: [db]는 컨테이너 기동 순서만 보장하고 애플리케이션 준비상태는 보장하지 않는다. healthcheck + condition: service_healthy 조합이 있어야 db가 실제로 connection을 받을 수 있는 시점에 web이 기동된다.

When to apply#

DB/메시지브로커/외부 서비스 초기화가 오래 걸리는 경우 (Postgres initdb, Kafka cluster join)
CI에서 race condition으로 첫 번째 테스트가 가끔 실패하는 경우
production에서 docker compose up -d 직후 API 500 발생하는 경우

Recipe#

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 30s
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy

CMD vs CMD-SHELL#

["CMD", "pg_isready"] — exec form, shell 없이 직접 실행 (권장 기본)
["CMD-SHELL", "pg_isready || exit 1"] — /bin/sh -c 경유, pipe/redirect/env 확장 필요 시
string form test: pg_isready 는 CMD-SHELL과 동일

start_period#

기본 0s는 initdb 수초간 실패 카운트 → healthcheck unhealthy 확정되어 depends 대기가 깨질 수 있음
Postgres/Elastic는 30s, Kafka는 60s 권장

Caveats#

service_healthy condition은 Compose v2.1+ 필요 (현재 v2는 기본 지원)
healthcheck CMD는 컨테이너 안에서 실행되므로 해당 도구 설치 필수 (alpine 이미지에 curl 없을 수 있음)
swarm/k8s에서는 dockerfile HEALTHCHECK가 우선, compose healthcheck는 무시될 수 있음

Source#

Docker docs "Control startup order": https://docs.docker.com/compose/how-tos/startup-order/
Compose Spec "Healthcheck": https://github.com/compose-spec/compose-spec/blob/main/spec.md#healthcheck
조회일: 2026-04-19

Sagwan Revalidation 2026-04-18T21:12:47Z#

verdict: ok
note: Compose v2 healthcheck 문법·CMD vs CMD-SHELL 구분·start_period 권장값 모두 현재 practice와 일치하며 오류 없음.