Docker 컨테이너가 로컬에서는 되는데 배포 후에 안 될 때

운영 중에는 작은 신호도 빨리 분리해서 본다

Docker 컨테이너로 Node 애플리케이션을 배포했을 때, 로컬 개발 환경에서는 완벽하게 작동하지만 운영에서는 문제가 생기는 경험을 한다. 혼자 개발할 때는 이런 작은 이상 신호를 빨리 캐치하지 못하고, 나중에야 문제의 크기를 깨닫는다.

컨테이너 문제의 핵심은 단편적인 에러 메시지가 아니라 전체 환경 설정을 확인하는 것이다. 로그, 환경변수, 포트 매핑, 볼륨 마운트를 차례대로 점검해야 원인을 찾을 수 있다.

먼저 로그를 본다

Docker 컨테이너에서 문제가 생기면, 가장 먼저 할 일은 컨테이너 로그를 확인하는 것이다:

• 먼저 볼 값: 컨테이너 로그와 시작 메시지
• 함께 비교할 값: 로컬에서 실행했을 때의 로그
• 남겨둘 기록: 환경변수, 포트 설정, 볼륨 마운트

환경변수를 의심한다

Docker는 환경변수를 통해 설정을 전달하지만, 로컬 개발 환경과 배포 환경에서 설정되는 값이 다를 수 있다. 데이터베이스 연결 문자열, API 키, 서버 포트 등이 제대로 설정되었는지 확인해야 한다:

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

이 명령들로 컨테이너 상태, 실제 로그, 설정된 환경변수를 확인할 수 있다.

포트 매핑을 확인한다

Node 애플리케이션이 3000번 포트에서 실행되지만, Docker 포트 매핑이 잘못되면 외부에서 접근할 수 없다. Dockerfile의 EXPOSE와 docker run의 -p 옵션이 일치하는지, 호스트에서 그 포트가 이미 사용 중인지 확인해야 한다.

로그를 체계적으로 읽는다

container logs에서 다음을 확인한다:

• 애플리케이션이 정상 시작되었는가
• 데이터베이스 연결 오류가 없는가
• 권한 관련 에러가 없는가

단계별로 검증한다

같은 문제가 반복되는 것을 방지하려면 확인 순서를 고정한다:

1. 원래 증상이 같은 조건에서 다시 나타나는지 확인한다
2. 로그, 환경변수, 포트 설정에서 바뀐 부분을 명확히 설명할 수 있는지 확인한다
3. 실제 컨테이너 프로세스와 네트워크 상태를 최종 확인한다

다음을 위해 기록한다

Docker 컨테이너 문제를 해결한 후, 어떤 환경 설정이 원인이었는지, 어떻게 수정했는지 정리해두면 비슷한 문제가 생겼을 때 대응 속도가 크게 빨라진다.