Docker의 Node.js 컨테이너 문제를 체계적으로 좁혀가기

Node.js 이미지로 컨테이너를 띄웠는데 뭔가 동작이 이상할 때, 문제를 너무 크게 보면 모든 게 의심스러워진다. 지금까지 겪은 대부분의 문제는 사실 작은 신호들을 무시했을 때였다.

처음부터 다시 생각해보니 컨테이너 문제는 크게 세 가지를 먼저 확인하면 대부분 분명해진다. 포트 매핑, 환경변수, 그리고 로그. 이 셋이 맞으면 나머지는 거의 자동으로 따라온다.

포트 매핑 먼저 확인하기

컨테이너 내부에서는 3000번 포트로 떠 있는데 호스트에서 8080으로 연결했다면, 다른 모든 게 완벽해도 소용없다. 내가 자주 하는 실수다.

docker ps

이 명령으로 어떤 포트가 매핑되었는지 확인한다. PORTS 컬럼에 0.0.0.0:8080->3000/tcp 같은 형태로 나와야 한다.

환경변수와 로그

다음은 반드시 필요한 환경변수가 제대로 전달됐는지 본다. API 키, 데이터베이스 주소, 노드 환경 같은 것들.

docker inspect service-name | grep -A 20 Env

그 다음 로그를 봐야 한다. 컨테이너가 실제로 뭐라고 말하는지.

docker logs --tail=100 service-name

최근 100줄만 보고도 대부분 뭔가 반응한다. 에러 메시지, 경고, 포트 바인딩 실패 같은 것들.

한 번에 하나씩

한 가지 더 중요한 건 동시에 여러 개를 바꾸지 않는 것이다. 포트를 바꾸고, 환경변수도 바꾸고, 이미지도 다시 빌드하면 뭐가 실제로 원인인지 알 수가 없다. 한 번에 하나. 그리고 매번 로그를 본다. 이 습관이 익숙해지면 다음 문제는 훨씬 빨리 푼다.