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`](#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, 예시 코드블록] 
> ```yml
> 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`](#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 요약: (미생성)