Docker 컨테이너의 이미지가 제대로 로드되지 않을 때

Docker 컨테이너에서 이미지가 404로 떨어지거나 흰 박스로 나타나면 보통 세 가지 중 하나다: 볼륨 마운트가 잘못됐거나, 포트가 제대로 매핑되지 않았거나, 환경 변수 설정이 빠졌거나.

먼저 컨테이너의 상태를 본다

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

로그에서 에러 메시지를 찾는 게 가장 직접적이다. 볼륨 마운트 경로가 없다는 에러, 포트 바인딩 실패 메시지, 환경 변수 누락 경고 등이 보일 수 있다.

포트 매핑을 확인한다

docker port service-name

host-port:container-port 매핑이 제대로 설정되었는지 확인한다. 특히 기존에 사용 중인 포트가 있으면 새 컨테이너는 실행되지 않는다.

볼륨 마운트 경로를 점검한다

컨테이너 내부에서 실제로 파일이 있는지 확인한다:

docker exec service-name ls -la /app/public

파일이 없으면 호스트 경로가 잘못 설정되었거나, 파일이 실제로 없는 것이다.

환경 변수가 제대로 전달되었는지 확인

docker inspect service-name | grep -i env

혹은 컨테이너 내부에서:

docker exec service-name env | grep IMAGE

이미지 URL이나 API 엔드포인트 같은 환경 변수가 설정 파일에만 있고 실제로 컨테이너에 전달되지 않은 경우가 많다.

변경 후 한 가지씩 확인한다

한 번에 여러 설정을 바꾸면 뭐가 효과가 있었는지 알기 어렵다. 로그를 한 줄로 정리해서 남겨 두면, 다음에 같은 문제가 생길 때 훨씬 빨리 처리할 수 있다.