services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy

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

시작 조건

depends_on만으로는 준비 상태를 보장하지 못한다 — 컨테이너 시작과 서비스 준비는 다르다

depends_on의 기본 동작은 의존 컨테이너가 "생성되어 실행 상태가 됐는지"만 확인합니다. DB 컨테이너가 Running 상태가 됐다고 해서 PostgreSQL이 실제로 쿼리를 받을 준비를 마친 것은 아닙니다. DB 초기화가 끝나기 전에 앱 컨테이너가 먼저 연결을 시도하면 연결 실패로 앱이 죽습니다.

# 위험한 패턴 — DB가 '실행 중'이어도 준비 안 됐을 수 있음
services:
  web:
    depends_on:
      - db  # condition 없이 쓰면 service_started가 기본

condition: service_healthy — healthcheck 통과 후 다음 서비스를 시작한다

depends_on에 condition: service_healthy를 지정하면, 의존 서비스가 healthcheck 결과로 healthy 상태가 될 때까지 다음 서비스 시작을 기다립니다. retries는 healthy가 되기 위한 성공 횟수가 아니라 unhealthy가 되기까지의 연속 실패 횟수입니다. DB가 실제로 연결 가능한 상태임을 확인한 뒤 앱을 올리므로, 시작 순서로 인한 연결 실패를 줄일 수 있습니다.

services:
  web:
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s  # 초기 기동 시간 여유

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 5

service_completed_successfully - 끝나야 다음 서비스가 시작되는 선행 작업

schema migration, asset 생성처럼 성공 후 종료해야 하는 job은 service_completed_successfully를 씁니다. job이 0 이외의 종료 코드로 끝나면 의존 서비스는 시작하지 않으므로, 장기 실행 서비스에 이 조건을 쓰지 않습니다.

services:
  api:
    build: .
    depends_on:
      migrate:
        condition: service_completed_successfully
      db:
        condition: service_healthy
        restart: true  # 명시적인 Compose db 재시작/갱신 때 api도 재시작

  migrate:
    image: my-api:latest
    command: ["./migrate"]

Dockerfile HEALTHCHECK와 Compose healthcheck — 같은 개념이지만 위치가 다르다

Dockerfile에도 HEALTHCHECK 지시어가 있어 이미지 자체에 헬스체크를 내장할 수 있습니다. Compose의 healthcheck 블록은 이미지에 정의된 헬스체크를 덮어쓰거나, 없는 경우에 추가합니다. 팀 공용 이미지에 헬스체크를 넣으면 Compose에서 별도 정의 없이도 service_healthy 조건을 쓸 수 있습니다.

# Dockerfile에 헬스체크 내장
HEALTHCHECK --interval=10s --timeout=3s --retries=5 \
  CMD pg_isready -U postgres || exit 1

재시작 경계