Dockerfile 문제로 서비스가 실패할 때 확인할 것

Dockerfile을 수정했는데 서비스가 실패한다면, 화면 하나만 보고는 절대 원인을 찾을 수 없다. 로그와 응답을 동시에 봐야 한다.

핵심은 컨테이너가 어디서 멈추는지, 왜 시작되지 않는지를 추적하는 것이다. 이미지 빌드, 컨테이너 시작, 포트 매핑, 환경 변수 등 여러 단계에서 문제가 발생할 수 있다.

현재 실행 중인 컨테이너 상태 확인하기

먼저 지금 어떤 컨테이너들이 실행 중인지, 어떤 포트를 사용하는지 봐야 한다.

docker ps

예상하는 서비스가 보이지 않는다면 이미 죽었다는 뜻이다. 모든 컨테이너를 보려면 -a 옵션을 붙인다.

컨테이너 로그 확인

왜 컨테이너가 시작되지 않았는지는 로그에 나와 있다. 마지막 100줄을 확인하는 것으로 충분한 경우가 많다.

docker logs --tail=100 service-name

ENTRYPOINT가 실행되지 않았다면 Dockerfile에 문제가 있다. 포트가 이미 사용 중이라면 포트 충돌이다. 환경 변수가 없다면 설정 누락이다.

이미지 상세 정보 확인

Dockerfile에서 설정한 환경 변수, 포트, 볼륨이 제대로 적용되었는지 확인한다.

docker inspect service-name

JSON 형식으로 컨테이너의 모든 정보가 출력된다. Config, Mounts, PortBindings, Env 섹션을 특히 잘 봐야 한다.

로컬과 운영 환경의 차이

Dockerfile은 같지만 실행 환경이 다를 수 있다. 포트 번호, 네트워크 설정, 볼륨 마운트 경로 등이 로컬에서는 통하지만 서버에서는 실패할 수 있다.

한 번에 여러 설정을 바꾸지 말고, 하나씩 수정해본다. 각 단계마다 컨테이너를 재시작하고 로그를 확인한다.

포트 매핑이 제대로 되어 있는가

Dockerfile에서 포트를 노출(EXPOSE)했다고 해서 호스트에서 접근할 수 있는 건 아니다. 실제로 포트를 바인드해야 한다.

docker run -p 3000:3000 service-name

포트가 이미 사용 중이면 다른 포트로 시도해본다. 시스템 포트는 피하고 1024 이상의 포트를 사용한다.

체크리스트

Dockerfile 문제를 다룰 때는 이 순서로 확인한다:

1. docker ps로 현재 실행 중인 컨테이너를 확인한다
2. docker logs로 마지막 에러를 본다
3. docker inspect로 설정을 상세히 확인한다
4. 환경 변수와 포트 매핑이 제대로 되었는지 본다
5. 한 가지씩만 수정하고 매번 결과를 기록한다

한 번에 여러 설정을 바꾸지 않는 것만으로도 원인 추적이 훨씬 쉬워진다. 관련 기록을 짧게라도 남겨두면 다음 확인이 훨씬 빨라진다.