Docker 컨테이너는 실행 중인데 서비스가 안 된다면? 헬스체크와 시작 순서

Docker 목록에서 컨테이너가 Up으로 표시되는데 웹페이지는 오류를 낼 때가 있습니다. 프로그램이 실행 중이라는 사실과 요청을 처리할 준비가 끝났다는 사실은 다릅니다. 데이터베이스가 초기화되는 동안 웹 프로그램이 먼저 접속을 시도하는 경우가 대표적인 예입니다.

앞선 Docker 저장 공간과 데이터 유지 글이 재생성 후 데이터를 다뤘다면, 이번에는 서비스가 시작되는 순서와 준비 상태를 살펴봅니다. Docker Compose의 depends_on과 healthcheck가 각각 무엇을 해결하는지 구분해 보겠습니다.

1. 실행 중·정상 판정·사용 가능은 다릅니다

확인 수준	알 수 있는 것	추가로 확인할 것
컨테이너 실행 중	주 프로세스가 살아 있음	초기화 완료와 요청 처리
헬스체크 통과	설정한 검사에 성공함	검사가 필요한 기능을 다루는지
외부에서 사용 가능	실제 이용 경로가 동작함	로그인·저장 등 주요 기능

예를 들어 DB 접속을 확인하는 검사에 통과해도 웹 프로그램이 요구하는 테이블 생성이 끝났다는 뜻은 아닐 수 있습니다. 웹 컨테이너 내부의 응답이 정상이어도 외부 도메인의 프록시나 포트 연결에 문제가 있을 수 있습니다. “정상”이라는 표현 옆에 무엇을 검사했는지 적어야 결과의 범위가 분명해집니다.

직접 제작한 시작 순서 개념도. DB 준비 여부를 확인한 뒤 웹 서비스를 시작하는 단계와 운영 중 연결 복구를 구분했습니다.

2. depends_on은 준비 상태까지 기다릴까?

Compose는 의존 관계에 따라 시작 순서를 정합니다. 하지만 기본적인 실행 순서만으로 의존 서비스가 요청을 받을 준비까지 끝났다고 판단하지는 않습니다. 준비 완료를 기다리려면 healthcheck를 정의하고, 의존 조건에 service_healthy를 사용합니다. Docker 공식 시작 순서 안내에서 이 차이를 설명합니다.

가령 DB가 프로세스를 띄운 뒤 데이터를 읽고 초기화하는 데 시간이 필요하다고 가정해 보겠습니다. 웹 프로그램이 이 구간에 접속하면 실패할 수 있습니다. 일정한 초만큼 기다리는 방식은 개발 PC에서는 맞아도 저장 장치나 데이터량이 다른 환경에서 어긋날 수 있으므로, 실제로 확인할 준비 조건을 정하는 편이 명확합니다.

3. DB 준비를 기다리는 Compose 구조 예시

아래 코드는 PostgreSQL 연결 수락 여부를 확인한 뒤 웹 서비스를 시작하는 구조 예시입니다. web의 build 경로에는 본인의 Dockerfile과 애플리케이션이 있어야 하며, DB 접속 설정도 그 프로그램에 맞게 추가해야 합니다. 운영 배포용 완성 파일이나 이 글에서 실행해 성능을 측정한 예제는 아닙니다.

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

  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: app
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -U app -d app
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

volumes:
  db_data:

DB_PASSWORD는 실행 환경에서 별도로 제공하는 값입니다. 실제 비밀번호를 공개 예제나 저장소에 적지 않도록 변수로 표시했습니다. 위 예시는 DB 포트를 호스트에 공개하지 않으며, 웹 프로그램의 외부 공개 포트나 프록시는 포함하지 않습니다.

healthcheck의 test는 컨테이너 안에서 실행할 검사입니다. interval은 검사 간격, timeout은 검사 제한 시간, retries는 연속 실패 판정 기준입니다. start_period는 초기 기동을 위한 유예 구간이며 무조건 그 시간만큼 시작을 멈추는 설정은 아닙니다. 성공하면 준비 상태로 바뀔 수 있습니다. 상세 동작은 Compose healthcheck 참조 문서를 확인하세요.

또한 검사 명령이 이미지 안에 있어야 합니다. 작은 이미지에 curl이 없는데 curl로 검사를 작성하면, 서비스가 정상이어도 검사 도구가 없어서 실패할 수 있습니다. 위 예시의 pg_isready도 DB 서버의 연결 수락 상태를 살피는 것이므로, 애플리케이션의 실제 로그인·조회·테이블 준비를 대신하는 검사는 아닙니다.

4. 시작 후 DB가 끊기면 어떻게 될까?

service_healthy 조건으로 초기 시작을 맞췄더라도 운영 중 DB가 재시작되거나 네트워크 연결이 끊길 수 있습니다. 이때 필요한 것은 애플리케이션의 재접속, 제한된 재시도, 사용자에게 보여 줄 오류 처리입니다. 시작 순서 설정을 운영 중 모든 장애의 자동 복구 기능으로 해석하면 안 됩니다.

unhealthy 상태 표시 자체가 실행 중인 컨테이너를 자동으로 재시작시키지는 않습니다. Docker의 restart 정책은 컨테이너 종료와 관련된 조건을 다룹니다. 자동 시작·재시작 공식 안내의 정책 설명을 함께 확인해야 합니다.

한편 depends_on 아래의 restart: true는 명시적인 Compose 작업으로 의존 서비스를 갱신하거나 재시작할 때 연결된 서비스를 다시 시작하는 설정입니다. 서비스 최상위의 restart 정책과 위치 및 의미가 다릅니다. 단순한 이해를 위해 위 코드에는 이 옵션을 넣지 않았습니다.

5. 오류를 좁히는 확인 순서

프로젝트의 Compose 파일이 있는 위치에서 다음처럼 상태와 최근 로그를 확인할 수 있습니다. 서비스 이름은 위 구조 예시에 맞춘 web과 db이며, 자신의 파일에서 이름이 다르면 바꿔야 합니다.

docker compose ps
docker compose logs --tail=100 db
docker compose logs --tail=100 web

1. 컨테이너가 종료됐는지, 실행 중인지, 헬스체크가 어떤 상태인지 확인합니다.
2. DB 로그에서 초기화 완료 시점과 오류를 확인합니다.
3. 웹 로그에서 DB 연결 거부인지, 인증 실패인지, 테이블 누락인지 구분합니다.
4. 웹 내부 응답과 외부 도메인 접속을 나눠 확인해 프록시·포트 문제를 좁힙니다.
5. 별도 시험 환경에서 DB 재시작 후 웹 프로그램이 연결을 복구하는지 확인합니다.

오류를 발견했다고 바로 전체 컨테이너를 삭제할 필요는 없습니다. 먼저 실패한 구간과 시간을 남기고, 시작 문제인지 운영 중 복구 문제인지 구분하면 수정 범위를 줄일 수 있습니다. 데이터를 유지하는 설정과 요청을 받을 준비를 확인하는 설정을 함께 이해해야 재시작 뒤 서비스 상태를 설명할 수 있습니다.

자료 확인일: 2026년 9월 7일. 공식 문서에 근거한 설명과 구성 예시입니다. 이미지 버전·검사 명령·준비 조건은 실제 프로그램에 맞춰 검토해야 합니다.