Docker Compose healthcheck 제대로 쓰기｜depends_on만 믿으면 생기는 문제

컨테이너가 실행 상태라는 사실은 애플리케이션이 요청을 받을 준비가 됐다는 뜻이 아니며 초기 마이그레이션이나 캐시 준비가 남아 있을 수 있습니다. 이번 글은 한눈에 읽히도록 준비, 실행, 확인 순서로 나눴습니다.

핵심은 정보를 많이 나열하는 것이 아니라 실제 행동으로 옮길 수 있는 기준을 남기는 것입니다. 아래 순서대로 확인하면 처음 접하는 사람도 중간에 길을 잃지 않습니다.

1. 확인 포인트

컨테이너가 실행 상태라는 사실은 애플리케이션이 요청을 받을 준비가 됐다는 뜻이 아니며 초기 마이그레이션이나 캐시 준비가 남아 있을 수 있습니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 이 항목은 사소해 보여도 실제로 해보면 결과 차이가 큰 부분입니다. 한 번에 전부 바꾸기보다 현재 상태를 기록하고 한 가지씩 조정하면 원인을 찾기 쉽습니다.

2. 확인 포인트

healthcheck는 실제 서비스가 준비됐는지 확인하는 명령이며 HTTP 엔드포인트, 데이터베이스 접속, 프로세스 상태 중 목적에 맞는 검사를 선택해야 합니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 특히 초보자는 눈에 띄는 숫자 하나만 기준으로 삼기 쉽습니다. 사용 환경과 준비 과정까지 함께 보면 불필요한 비용과 반복 작업을 줄일 수 있습니다.

3. 확인 포인트

interval은 검사 주기, timeout은 한 번의 검사 제한 시간, retries는 실패를 허용할 횟수라서 시작 시간이 긴 서비스에 맞게 조정해야 합니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 확인 과정은 복잡할 필요가 없습니다. 휴대전화 메모에 조건과 결과를 짧게 남겨두면 다음 선택에서 같은 실수를 반복하지 않게 됩니다.

4. 확인 포인트

start_period를 사용하면 정상적인 초기화 시간 동안의 실패를 재시도 횟수에서 제외해 불필요한 unhealthy 판정을 줄일 수 있습니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 안전이나 기기 손상과 연결되는 부분은 공식 설명서를 우선해야 합니다. 인터넷의 요약 팁은 방향을 잡는 보조 자료로만 활용하는 편이 좋습니다.

5. 확인 포인트

depends_on의 service_healthy 조건은 의존 서비스 준비를 기다리는 데 도움이 되지만 런타임 장애 뒤 자동 복구까지 대신하지는 않습니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 이 항목은 사소해 보여도 실제로 해보면 결과 차이가 큰 부분입니다. 한 번에 전부 바꾸기보다 현재 상태를 기록하고 한 가지씩 조정하면 원인을 찾기 쉽습니다.

6. 실전 메모

검사 명령은 컨테이너 안에 실제 설치된 curl·wget·셸을 기준으로 작성해야 하며 최소 이미지에서는 도구가 없을 수 있습니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 특히 초보자는 눈에 띄는 숫자 하나만 기준으로 삼기 쉽습니다. 사용 환경과 준비 과정까지 함께 보면 불필요한 비용과 반복 작업을 줄일 수 있습니다.

7. 실전 메모

너무 무거운 쿼리나 외부 API 호출을 상태 검사에 넣으면 검사 자체가 부하와 장애 원인이 되므로 작고 독립적인 신호가 좋습니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 확인 과정은 복잡할 필요가 없습니다. 휴대전화 메모에 조건과 결과를 짧게 남겨두면 다음 선택에서 같은 실수를 반복하지 않게 됩니다.

8. 실전 메모

docker compose ps와 inspect의 Health 로그를 함께 보면 종료 코드와 최근 출력이 남아 있어 단순 재시작보다 원인을 찾기 쉽습니다. 판단 기준은 ‘재현 가능한가’와 ‘다른 환경에서도 같은가’ 두 가지로 두면 좋습니다. 안전이나 기기 손상과 연결되는 부분은 공식 설명서를 우선해야 합니다. 인터넷의 요약 팁은 방향을 잡는 보조 자료로만 활용하는 편이 좋습니다.

마무리

마지막으로 결과를 확인할 때는 성공한 장면만 보지 말고 불편했던 지점도 함께 적어두세요. 다음번에는 그 기록이 가장 현실적인 체크리스트가 됩니다.

마무리

정리하면 준비 단계에서 조건을 확인하고, 실행 중에는 변수를 하나씩 바꾸며, 끝난 뒤에는 결과를 기록하는 흐름이 핵심입니다. 이 순서만 지켜도 시행착오가 크게 줄어듭니다.

다른 사용자 계정이 만든 저장소나 Docker, WSL, 공유 폴더에서 Git 명령을 실행하면 아래 오류가 날 수 있다.

fatal: detected dubious ownership in repository at '/path/to/project'

Git이 현재 저장소 소유자를 신뢰할 수 없다고 판단해서 실행을 막는 보안 기능이다.

1. 저장소 소유자부터 확인

# Linux / macOS
ls -ld /path/to/project

# 현재 사용자
whoami

내 저장소인데 소유자가 잘못됐다면 safe.directory를 추가하기 전에 소유권을 먼저 고치는 게 맞다.

sudo chown -R $(whoami) /path/to/project

위 명령은 폴더 전체 소유자를 바꾸므로 경로를 반드시 확인하고 실행한다. 서버 공용 저장소라면 함부로 실행하면 안 된다.

2. 의도적으로 공유하는 저장소라면

git config --global --add safe.directory /path/to/project

현재 사용자 전역 설정에 해당 경로 하나만 안전한 저장소로 추가한다.

3. 등록됐는지 확인

git config --global --get-all safe.directory

4. 잘못 추가한 경로 삭제

git config --global --unset-all safe.directory /path/to/project

모든 경로 허용은 피하기

git config --global --add safe.directory '*'

위 설정은 모든 저장소를 신뢰하므로 오류는 빨리 없어지지만 보안 검사를 사실상 끈다. 개인 개발 PC라도 문제 저장소의 정확한 경로만 추가하는 편이 좋다.

공식 설명은 Git safe.directory 문서에서 확인할 수 있다.

결론: 소유권이 잘못됐으면 소유권을 수정하고, 의도적인 공유 저장소일 때만 safe.directory에 정확한 경로를 추가한다.