Docker 이미지가 로컬에서는 잘되는데 서버에서 안 될 때

로컬 Docker Compose로는 완벽하게 돌아가던 이미지가 운영 서버에서는 계속 재시작된다. 이럴 때는 여러 곳을 봐야 하는데, 하나씩 체계적으로 좁혀가야 한다.

먼저 컨테이너가 정말 실행 중인지 확인

컨테이너가 실제로 돌고 있는지 죽었는지부터 봐야 한다. 같은 이름의 컨테이너가 여러 개 있거나, 다른 버전의 이미지가 떴을 수도 있다.

docker ps

현재 실행 중인 컨테이너 목록을 본다. 서비스 이름, 상태, 포트 매핑을 확인한다. 컨테이너가 보이지 않으면:

docker ps -a

종료된 컨테이너도 함께 본다. 그 컨테이너의 Exit Code를 보면 어디서 실패했는지 힌트를 얻을 수 있다.

로그에서 실제 에러 찾기

Exit Code가 0이 아니면 컨테이너 안에서 뭔가 터졌다는 뜻이다. 로그를 보면 무엇이 잘못되었는지 알 수 있다.

docker logs --tail=100 service-name

최근 100줄의 로그를 본다. 권한 에러, 포트 이미 사용 중, 파일을 못 찾은 경우 등이 명확하게 나타난다.

로컬에서는 없던 에러가 나타날 수 있다. 예를 들어:

• 환경변수가 설정되지 않음
• 마운트 볼륨 경로가 다름
• 포트가 이미 사용 중임

컨테이너 상세 설정 확인

때론 로그보다 컨테이너 자체의 설정이 문제일 수 있다. 어떤 환경변수로 실행되었고, 어떤 볼륨이 마운트되었는지 확인한다.

docker inspect service-name

JSON 형식의 대량 정보가 나온다. 여기서 봐야 할 것은:

• Env: 환경변수 목록
• PortBindings: 포트 매핑
• Volumes: 마운트 경로
• RestartPolicy: 자동 재시작 설정

로컬과 서버 환경 비교

실제로 로컬과 서버의 다른 점을 정리해보자.

항목	로컬	서버
Docker 버전	?	docker --version
이미지 태그	latest	무엇인가?
환경변수	docker-compose.yml	.env 파일?
포트	3000:3000	80:3000? 443?
볼륨	./data:/data	/var/data:/data?

이 표를 채우면서 차이를 찾는다.

배포 후 검증 순서

1. 컨테이너가 실행 중인지 확인한다 (docker ps).
2. 최근 로그를 본다 (마지막 30줄).
3. 컨테이너 설정과 로컬 설정을 비교한다.
4. 필요하면 컨테이너 내부로 접속해서 직접 확인한다.

Docker 문제는 90%가 환경 설정이다. 로그를 읽고 한 가지씩 고쳐가면 대부분 해결된다.