Docker 컨테이너가 자꾸 재시작될 때

배포한 컨테이너가 몇 초씩 반복해서 재시작된다. 정상적으로 올라왔다가 금방 다시 시작되는 걸 보면 명백히 뭔가 에러가 있다는 뜻이다.

어떤 컨테이너인지 확인

먼저 실행 중인 컨테이너를 확인하자:

docker ps

모든 컨테이너를 보려면 -a 플래그를 붙인다:

docker ps -a

STATUS 칼럼에서 "Exited", "Restarting" 같은 상태를 확인할 수 있다.

컨테이너 로그 확인

가장 중요한 건 로그다:

docker logs --tail=100 service-name

--tail=100: 최근 100줄 -f: 실시간으로 따라가기 --timestamps: 타임스탬프 함께 표시

에러 메시지, 예외, 초기화 실패 같은 내용이 있을 것이다.

컨테이너 상세 정보

docker inspect service-name

이 명령으로 알 수 있는 것:

• 환경 변수가 제대로 설정되었는가?
• 마운트 볼륨이 제대로 연결되었는가?
• 포트 매핑이 정확한가?
• 재시작 정책은 어떻게 되어 있는가?

환경 변수 다시 확인

로컬에서는 되는데 컨테이너에서는 안 될 때 대부분 환경 변수 차이다:

docker exec service-name env | grep DATABASE

또는 docker-compose를 쓴다면:

docker-compose config  # 설정 확인

이미지 태그 확인

혹시 빌드한 이미지가 최신이 아닐 수도 있다:

docker images | grep service-name

예상한 태그가 맞는지, 크기가 이상하지 않은지 확인하자. 필요하면 이미지를 다시 빌드해야 할 수도 있다.

포트 매핑

컨테이너의 포트와 호스트의 포트가 제대로 매핑되어 있는지:

docker inspect service-name | grep -A5 PortBindings

또는 더 간단하게:

docker port service-name

자주 있는 재시작 이유

1. 잘못된 명령어: Dockerfile의 CMD가 존재하지 않는 명령어라서 즉시 종료
2. 환경 변수 부족: DATABASE_URL이 없어서 시작 직후 에러 나고 재시작
3. 포트 충돌: 컨테이너 내부에서 다른 프로세스가 포트를 써서 실패
4. 디스크 부족: 로그나 임시 파일로 디스크가 가득 참
5. 헬스체크 실패: 헬스체크가 설정되어 있는데 계속 실패

디버깅 팁

restart policy를 임시로 no로 바꿔서 컨테이너가 재시작되지 않게 하고 로그를 천천히 분석할 수 있다.

일관된 순서(로그 → 환경 변수 → 포트 → 이미지)로 확인하면 대부분의 컨테이너 문제를 빠르게 해결할 수 있다.