llm-wiki/raw/official-docs/docker-compose-depends-on-healthcheck.md

---

title: official-doc / Docker Compose — depends_on long syntax condition: service_healthy source_type: official-doc url: https://docs.docker.com/reference/compose-file/services/ archive_url: related_branches: [feature-keycloak-docker-compose-stack] related_projects: [keycloak-patterns] tags: [official-doc, keycloak-patterns, infra, docker] created: 2026-07-16

official-doc / Docker Compose — depends_on long syntax condition: service_healthy

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-docker-compose-stack	D3: depends_on: condition: service_healthy 로 keycloak → app 기동 순서를 강제하는 결정의 Compose 사양 근거 — 이 자료가 long-form depends_on + condition 키의 존재와 service_healthy 의 의미(healthcheck 통과 후에만 dependent 기동)를 확인시켜, 기존 branch-note 의 UNSUPPORTED_DECISION 라벨을 해소할 근거를 제공한다.

출처 / Source

• 원본 URL: https://docs.docker.com/reference/compose-file/services/
• 아카이브 URL: (미제공)
• 저자 / 조직: Docker, Inc. (Compose Specification 공식 레퍼런스)
• 발행일: (페이지에 명시 없음 — 지속 갱신되는 living reference 문서)
• 마지막 확인일: 2026-07-16

왜 저장했는지 / Why archived

feature-keycloak-docker-compose-stack branch 의 D3 결정("healthcheck 로 의존성 강제, depends_on: condition: service_healthy")이 기존에는 Docker Compose spec 자체가 raw 에 미등록이라 UNSUPPORTED_DECISION 이었다. 본 자료는 Docker 공식 Compose file reference 의 depends_on/healthcheck 섹션 원문을 발췌해 그 결정의 1차 근거로 삼는다.

핵심 인용 / Key quotes (verbatim)

[§depends_on / Long syntax] "- condition: Sets the condition under which dependency is considered satisfied

• service_healthy: Specifies that a dependency is expected to be "healthy" (as indicated by healthcheck) before starting a dependent service." (line 462, 464-466 in fetched markdown)

[§depends_on / Long syntax] "- service_completed_successfully: Specifies that a dependency is expected to run to successful completion before starting a dependent service." (line 467-468)

[§depends_on / Short syntax] "With short syntax, Compose does not wait for dependency services to be "healthy" before starting a dependent service." (line 450-451)

[§depends_on / Long syntax, 결과 보증 문단] "Compose guarantees dependency services marked with service_healthy are "healthy" before starting a dependent service." (line 502-503)

[§healthcheck] "The healthcheck attribute declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the HEALTHCHECK Dockerfile instruction" (line 1095)

[§healthcheck, 예시 코드블록]

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s

(line 1103-1109)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
COMPOSE-DEP-C1	depends_on 의 long-form syntax 는 condition 키를 지원하며, 그 값 중 하나가 service_healthy 다.	[line 462] "condition: Sets the condition under which dependency is considered satisfied"	official-standard	Compose 파일 작성 시 서비스 간 시작 순서를 depends_on.<service>.condition 형태로 세밀 제어하고자 할 때	이 claim 만으로는 특정 Docker Compose 버전에서 이 문법이 최초 지원된 시점(버전)까지는 증명하지 않음 (restart, required 키는 각각 버전 도입 각주가 있으나 condition 자체엔 버전 각주 없음)
COMPOSE-DEP-C2	service_healthy 조건은 "dependency 가 healthcheck 로 표시된 대로 'healthy' 상태가 된 뒤에야 dependent 서비스를 시작한다"는 것을 의미한다.	[line 464-466] "service_healthy: Specifies that a dependency is expected to be "healthy" (as indicated by healthcheck) before starting a dependent service."	official-standard	keycloak(dependency) 에 healthcheck 가 정의되어 있고, app(dependent) 이 depends_on: keycloak: condition: service_healthy 를 선언하는 구성	keycloak 서비스 자체에 healthcheck 가 없거나 잘못 정의된 경우 이 조건이 영원히 unhealthy 로 남아 app 이 기동하지 않을 수 있다는 실패 모드까지는 이 인용이 직접 말하지 않음 (별도 확인 필요)
COMPOSE-DEP-C3	service_completed_successfully 조건은 dependency 가 "성공적으로 완료 실행된 뒤에야" dependent 서비스를 시작한다는 의미다 (service_healthy, service_started 와 대비되는 별도 조건).	[line 467-468] "service_completed_successfully: Specifies that a dependency is expected to run to successful completion before starting a dependent service."	official-standard	init-container 성격의 1회성 job 서비스에 의존하는 구성 (본 branch 의 keycloak/app 상시 실행 서비스에는 미해당)	keycloak/postgres/app 모두 상시 실행 서비스이므로 이 조건이 D3 결정에 직접 쓰이지는 않음 — 대조용 claim
COMPOSE-DEP-C4	short syntax (depends_on: [db]) 는 healthcheck 를 기다리지 않고 시작 순서만 보장한다 — long syntax condition: service_healthy 와 대조되는 기본 동작.	[line 450-451] "With short syntax, Compose does not wait for dependency services to be "healthy" before starting a dependent service."	official-standard	short-form 을 쓸지 long-form 을 쓸지 결정하는 근거 — D3 가 명시적으로 long-form 을 선택해야 하는 이유	short syntax 를 쓸 때 실제로 발생하는 실패 사례(예: keycloak JWKS 미준비 시 앱 기동 실패)의 재현 로그까지 증명하지는 않음 — 그건 실 구현 후 raw/errors/에서 별도 검증
COMPOSE-DEP-C5	Compose 는 service_healthy 로 표시된 dependency 들이 "healthy" 상태가 된 뒤에만 dependent 서비스를 생성한다는 것을 보증(guarantee)한다.	[line 502-503] "Compose guarantees dependency services marked with service_healthy are "healthy" before starting a dependent service."	official-standard	D3 결정의 핵심 정당화 문장 — "app 이 keycloak ready 이전에 기동해 JWKS 호출 실패" 문제를 depends_on: condition: service_healthy 로 해결할 수 있다는 근거	이 guarantee 는 "시작 순서"에 대한 것이며, keycloak 컨테이너 내부의 애플리케이션(realm import, admin bootstrap 등)이 완전히 초기화됐다는 것까지 보증하지 않음 — healthcheck 자체가 무엇을 검사하는지에 따라 다름 (keycloak /health/ready 엔드포인트 정의는 별도 raw 필요, branch-note Claims To Verify 참조)
COMPOSE-DEP-C6	healthcheck 속성은 서비스 컨테이너가 "healthy" 한지 판정하는 체크를 선언하며, test(문자열 또는 리스트), interval, timeout, retries, start_period, start_interval 필드를 가진다 (예시: interval: 1m30s, timeout: 10s, retries: 3, start_period: 40s).	[line 1095] "The healthcheck attribute declares a check that's run to determine whether or not the service containers are "healthy"." + [line 1103-1109] 코드블록	official-standard	keycloak/postgres 서비스에 실제 healthcheck: 블록을 작성할 때 필드명·형식의 근거	이 자료는 healthcheck 필드의 문법만 정의할 뿐, keycloak 이미지에 적합한 test 커맨드 값(예: curl 이 이미지에 존재하는지, /health/ready 경로가 맞는지)까지는 증명하지 않음 — Keycloak 벤더 문서에서 별도 확인 필요 (branch-note 의 KC-CONTAINER-C5 needs-confirmation claim 참조)

Strength 허용값 참고

본 문서 전 claim 은 Docker 공식 Compose file reference (docs.docker.com) 원문에서 직접 발췌했으므로 모두 official-standard — Compose Specification 은 Docker 가 관리하는 오픈 사양(Compose Spec)의 공식 레퍼런스 구현체 문서다.

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • COMPOSE-DEP-C1~C2, C5: Docker Compose long-form depends_on 문법에 condition: service_healthy 가 존재하며, 이는 dependency 의 healthcheck 가 healthy 를 보고한 뒤에만 dependent 서비스가 시작됨을 보증한다.
  • COMPOSE-DEP-C3: service_completed_successfully 조건의 존재 (대조용, 본 branch 미사용).
  • COMPOSE-DEP-C4: short syntax 와 long syntax 의 동작 차이.
  • COMPOSE-DEP-C6: healthcheck 속성 자체의 필드 문법(test/interval/timeout/retries/start_period/start_interval).
• 이 자료가 증명하지 않는 것:
  • keycloak 컨테이너에 실제로 어떤 healthcheck.test 커맨드가 적합한지 (예: curl 바이너리 존재 여부, /health/ready 엔드포인트 활성화 조건) — 이는 Keycloak 벤더 문서 영역.
  • condition: service_healthy 가 정확히 어느 Docker Compose 버전부터 지원되는지의 버전 각주 (restart/required 키는 버전 각주가 있으나 condition 자체엔 없음).
  • service_healthy guarantee 가 애플리케이션 수준의 완전한 준비 상태(예: realm import 완료)까지 보증한다는 것 — 이건 컨테이너 healthcheck 정의 범위에 달려 있음.
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • keycloak 서비스에 실제 healthcheck: 블록을 작성할 때 쓸 test 커맨드 (Keycloak 26.x 이미지에 curl/wget 존재 여부, management port 9000 분리 여부) — branch-note 의 needs-confirmation claim.
  • postgres healthcheck (pg_isready) 는 이 자료 범위 밖 (postgres 공식 이미지 문서에서 확인).

메모 / Notes

• 이 발췌는 docs.docker.com/reference/compose-file/services.md (사이트가 제공하는 plaintext/markdown 미러 — 페이지 하단 "View Markdown" 버튼이 가리키는 URL) 에서 가져온 원문이다. 렌더링된 HTML 페이지가 아니라 이 markdown 소스를 사용한 이유: HTML 은 Tailwind 클래스와 pagefind 마크업이 뒤섞여 있어 verbatim self-grep 이 어렵고, WebFetch 도구는 내부적으로 소형 모델을 거쳐 paraphrase 된 요약을 반환해 self-grep 검증이 불가능했다. curl 로 두 URL 모두 raw 상태로 저장해 대조했다.
• (미검증 추론 금지 — 추가 해석 없음)
• 추가로 봐야 할 동일 출처 페이지: Keycloak 공식 /health/ready 엔드포인트 정의 페이지 (management port 분리 여부), postgres 공식 이미지의 pg_isready healthcheck 예시.

Related / 관련

• raw/official-docs/keycloak-server-containers-docker — Keycloak Docker 공식 (KC_* 환경 변수, feature-keycloak-docker-compose-stack D1/D5 근거)
• raw/official-docs/keycloak-getting-started-docker — Docker quickstart (D6 근거)
• 이 자료를 인용한 wiki 요약: (미생성)