Dockerfile 빌드 실패할 때 로그 읽는 순서

Docker 문제를 디버깅할 때 가장 흔한 실수는 에러 메시지 한 줄에만 집중하는 것이다. 전체 빌드 흐름에서 어느 지점이 깨졌는지 파악하는 게 훨씬 빠르다.

먼저 확인할 것들

문제가 생기면 느낌으로 고쳐 보기보다 먼저 현재 상태를 기록해 두자. 다음에 같은 문제가 나올 때 비교할 근거가 된다.

컨테이너 상태를 보는 기본 명령

볼륨 마운트나 환경변수 설정이 꼬여 있으면 아무리 코드를 고쳐도 결과가 안 바뀐다. 배포하기 전에 한 번씩 확인하는 습관이 중요하다.

docker ps
docker logs --tail=100 service-name
docker inspect service-name

위 세 명령만으로 대부분의 단서를 모을 수 있다. docker ps로 컨테이너가 실행 중인지 확인하고, logs로 에러 스택을 본 뒤, inspect로 설정 값이 제대로 적용됐는지 확인한다.

환경 차이가 숨겨진 곳들

로컬에서 잘 동작한다고 해서 서버에서도 잘 동작하는 건 아니다. 다음을 체크해 보자:

• 환경변수: 로컬과 서버에서 값이 다른가?
• 볼륨 마운트: 경로가 정말 존재하는가?
• 포트 매핑: 열려 있는 포트가 맞는가?

이 세 가지를 함께 적어 두면 나중에 같은 증상이 나올 때 원인 추적이 훨씬 쉬워진다.

로그를 읽는 순서

에러는 보통 맨 앞에 나타나지 않는다. 컨테이너 시작 과정 전체를 따라가면서 어디서 첫 번째 문제가 나는지 찾자. 특히 다음을 눈여겨봐라:

1. 처음 증상이 같은 조건에서 다시 나는지 확인한다.
2. 로그나 응답에서 바뀐 부분을 한 줄로 설명해 본다.
3. 공개 화면, 빌드 결과, 실제 요청 중 하나로 마지막 확인을 한다.

문제를 남기는 방법

해결했다고 끝내지 말고, 이번에 뭐가 잘못됐는지 기록해 두자. 그다음 문제를 훨씬 빠르게 처리할 수 있다. 가장 중요한 건 느낌이 아니라 증거를 남기는 것이다.