Docker 빌드가 자꾸 실패하면 컨텍스트부터 확인하자

Docker 빌드가 로컬에선 잘되는데 배포 환경에선 실패한다면, 컨테이너 전체 설정을 체계적으로 점검해야 한다.

먼저 현재 상태 확인하기

실행 중인 컨테이너와 이미지를 확인해서 어디가 문제인지 범위를 좁힌다.

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

로그의 마지막 100줄을 보면 보통 에러 메시지가 명확하다. 어디서 멈췄는지를 보는 게 다음 단계를 결정한다.

컨테이너 상세 정보 확인

Docker inspect로 상세 정보를 본다.

docker inspect service-name

이 명령어는 다음을 보여준다:

• 현재 이미지 ID
• 마운트된 볼륨
• 포트 매핑
• 환경변수
• 상태 (running, exited 등)

특히 exited 상태면, 왜 꺼졌는지를 확인해야 한다.

환경변수와 포트 매핑 이중 확인

Dockerfile에서 설정한 환경변수와 실제 실행 시 넘긴 환경변수가 다를 수 있다. docker-compose.yml이나 배포 설정을 다시 읽어본다.

docker exec service-name env

포트도 마찬가지다. 컨테이너 내부 포트와 호스트 포트가 제대로 연결됐는지 확인한다.

이미지 빌드할 때 로그 읽기

빌드 중에 실패한다면, docker build 로그를 세심하게 읽는다.

docker build -t image-name:tag .

RUN 명령 중 어느 단계에서 실패했는가? npm install이 실패했다면 node_modules가 빠진 걸 텐트고, apt-get이 실패했다면 패키지 소스 문제일 수 있다.

한 가지씩 확인하는 작은 실험

Dockerfile의 여러 줄을 한번에 고치면, 어느 것 때문에 실패했는지 알 수 없다.

1. base 이미지를 검증한다 (예: node:18 태그가 정말 존재하는가?)
2. COPY 명령의 경로를 확인한다 (파일이 빌드 컨텍스트에 있는가?)
3. RUN 명령 각각을 독립적으로 테스트해본다
4. 각 단계마다 빌드를 시도해서 언제부터 문제가 생기는지 파악한다

로컬과 배포 환경의 차이

배포 환경의 OS나 네트워크가 다를 수 있다. 로컬에서 docker run으로 같은 명령을 실행해보고, 배포 환경에서도 동일하게 실행되는지 테스트한다.

디스크 공간과 리소스 확인

드물지만, 디스크 부족이나 메모리 부족으로 빌드가 실패할 수 있다.

df -h
free -h

특히 대용량 이미지를 자주 빌드하면 디스크가 부족할 수 있으니, 가끔 정리해주자.