Docker 이미지가 제대로 로딩되지 않을 때

Docker 이미지 빌드나 배포 중에 문제가 생기면, 한 단어의 에러 메시지에만 집중하기 쉽다. 하지만 컨테이너 전체 흐름에서 원인을 찾아야 한다.

처음 보이는 증상을 기록해 두기

로컬과 운영의 차이가 자주 숨어 있다. 환경 차이까지 같이 적어 두면, 원인 추적이 훨씬 쉬워진다.

원인을 나누는 기준

로컬과 운영의 차이가 자주 숨어 있다. 다음을 확인해 보자:

• 이미지 태그가 정말 그 버전인가?

• 환경변수가 제대로 전달됐는가?

• 볼륨 마운트가 올바른가?

• 먼저 볼 값: 이미지 태그

• 같이 비교할 값: 정상 상태

• 남겨둘 기록: 빌드 명령 출력, HTTP 상태 코드, 수정 내역

환경변수부터 확인하기

이미지 자체보다 재현 가능한 단서를 남기는 게 중요하다. 환경변수를 확인하면, 다음으로 볼 범위가 확 줄어든다.

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

이 세 명령으로 실행 중인 컨테이너, 로그, 상세한 설정을 모두 볼 수 있다.

명령어로 직접 확인해 보기

이미지 자체보다 재현 가능한 단서를 남기는 게 중요하다. 볼륨 마운트를 확인하면, 다음으로 볼 범위가 확 줄어든다.

volume이 정말로 마운트되었는지, 경로가 맞는지 docker inspect로 직접 확인해 보자.

포트 매핑 확인하고 해석하기

컨테이너의 흐름을 먼저 끊어서 본다. 특히 포트 매핑이 애매하면, 다른 부분을 고쳐도 결과가 안 바뀐다.

어느 포트가 열려 있는지, 제대로 포워딩되는지 확인하자.

마지막 점검 사항

문제가 반복되면, 확인 순서를 고정해 두는 편이 낫다. 매번 다르게 접근하면 같은 실수를 반복하게 된다.

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

다음 문제에 대비하기

다음에 비슷한 증상이 나오면, 지금 기록한 값과 비교하면 된다. 현재 값을 기록하고 하나씩 비교하면서 진행하면, 문제를 훨씬 빠르게 해결할 수 있다.