"컨테이너는 떠 있는데 접속이 안 될 때" 배포 전 점검표

Docker 컨테이너가 running 상태인데 외부에서 접속이 안 되는 경우가 있다. 이럴 때는 순서대로 확인하면 된다.

우선순위: 환경 변수부터

# 컨테이너 내 환경 변수 확인
docker inspect container-id | jq '.[] | .Config.Env'

애플리케이션이 틀린 포트에서 대기 중일 수 있다. 예: 컨테이너는 3000에서 대기하는데 포트 매핑은 5000:3000으로 설정된 경우.

포트 매핑 이해하기

# 포트 매핑 확인
docker ps | grep container-name
# 출력: 0.0.0.0:5000->3000/tcp

This means: 외부에서는 5000으로, 내부에서는 3000으로 대기한다는 뜻이다. 접속 주소는 host:5000이어야 한다.

볼륨 마운트 문제

# 마운트된 경로 확인
docker inspect container-id | jq '.[] | .Mounts'

Application 코드나 설정 파일이 잘못된 경로로 마운트됐으면, 컨테이너는 올라오지만 정상 동작하지 않는다.

네트워크 모드 확인

# 네트워크 설정
docker inspect container-id | jq '.[] | .NetworkSettings'

host 네트워크 모드를 쓰는 경우가 아니라면, 컨테이너는 격리된 네트워크에 있다. Compose 환경에서 다른 컨테이너끼리는 서비스 이름으로 통신한다.

배포 전 체크리스트

1. docker ps 실행 후 포트 매핑이 예상과 일치하는가
2. 실제 요청을 보내면 응답이 오는가 (curl 테스트)
3. 로그에 에러나 경고가 없는가
4. 여러 번 재시작해도 같은 상태가 유지되는가

이 네 가지만 확인하면 배포 후 문제가 대부분 방지된다.