docker-compose 환경에서 컨테이너가 자꾸 재시작되는 원인 찾기

Docker Compose로 구성한 서비스가 로컬에서는 멀쩡한데 배포하면 자꾸 재시작된다. 보통 환경 변수가 빠졌거나 다르기 때문이다.

상태 확인하기

# 현재 실행 중인 서비스 상태
docker ps

# 재시작 로그 보기
docker logs --tail=100 service-name

# 컨테이너의 실제 환경 변수 확인
docker inspect service-name | grep -A 20 'Env'

이 세 명령어로 대부분의 단서를 찾을 수 있다.

환경 변수 불일치

로컬 .env에는 있지만 운영 환경에는 없는 변수가 있으면 컨테이너는 시작 조차 못 한다. 예를 들어:

# docker-compose.yml
services:
  api:
    environment:
      - DATABASE_URL=${DATABASE_URL}  # 이게 없으면 모든 쿼리가 실패
      - PORT=3000

Compose 파일에는 변수 레퍼런스만 있고, 실제 값은 .env 파일에 있어야 한다. 배포 환경에 .env.production이 제대로 배치됐는지 확인하자.

포트 매핑 확인

# 포트가 실제로 열려 있는지
netstat -tulpn | grep 3000

로컬에서는 localhost:3000으로 접근하지만, Docker 환경에서 외부 포트와 내부 포트가 다를 수 있다. Compose 파일의 ports 섹션을 다시 보자.

작은 체크리스트

1. 로그 메시지 맨 첫 줄이 에러인지 확인
2. 필수 환경 변수가 정의돼 있는지 확인
3. 이미지 태그와 버전이 일치하는지 확인
4. 로컬에서 재현 가능한지 테스트

컨테이너가 반복 재시작되는 건 보통 이 중 하나를 빠뜨린 거다.