docker run을 했는데 docker ps에는 아무것도 안 보이고, docker ps -a로 보면 Exited (0) 또는 Exited (1)로 이미 꺼져 있는 경우입니다. 컨테이너는 메인 프로세스(PID 1)가 끝나면 곧바로 종료됩니다. 즉 "왜 그 프로세스가 끝났는가"를 찾는 문제입니다.
1단계 — 로그와 종료 코드를 본다
docker ps -a # STATUS의 Exited 코드 확인
docker logs <container> # 마지막에 무엇이 찍혔나
종료 코드와 마지막 로그 한 줄이 원인을 거의 정합니다.
STATUS
Exited (1) 2 seconds ago
2단계 — 종료 코드로 원인 좁히기
| Exit Code | 흔한 의미 |
|---|---|
| 0 | 프로세스가 할 일을 끝내고 정상 종료(상주 프로세스가 아님) |
| 1 | 애플리케이션 에러 — docker logs의 예외 확인 |
| 126 | CMD가 실행 권한 없음 |
| 127 | CMD/명령을 못 찾음(경로·오타) |
| 137 | OOM 또는 외부 SIGKILL |
원인별 해결
① 포그라운드 프로세스가 없다 (Exit 0) — 가장 흔합니다. CMD가 일회성 명령이거나, 서버를 백그라운드(&, daemon off 누락)로 띄워서 PID 1이 즉시 끝나는 경우. 프로세스를 포그라운드로 상주시킵니다.
# 나쁨: nginx가 백그라운드로 떠서 컨테이너가 바로 종료
CMD service nginx start
# 좋음: 포그라운드로 상주
CMD ["nginx", "-g", "daemon off;"]
② 앱이 시작 중 예외로 죽음 (Exit 1) — 환경변수·설정 파일 누락, DB 접속 실패 등. docker logs의 첫 예외를 보고 -e나 마운트로 빠진 값을 주입합니다.
③ 명령을 못 찾거나 권한 없음 (Exit 127/126) — CMD ["./start.sh"]인데 실행 권한이 없거나 경로가 틀린 경우. chmod +x와 절대 경로를 확인합니다.
④ 메모리 초과 (Exit 137) — docker run --memory 제한보다 많이 써서 커널이 죽인 경우. docker inspect <c> --format '{{.State.OOMKilled}}'가 true면 메모리 문제입니다.
디버깅 팁 — 셸로 들어가서 직접 실행
컨테이너가 너무 빨리 죽어 로그가 안 잡히면, 엔트리포인트를 셸로 덮어쓰고 안에서 직접 명령을 돌려봅니다.
docker run -it --entrypoint sh <image>
# 안에서: 실제 CMD를 손으로 실행해 에러 메시지를 직접 확인
체크리스트
docker ps -a # Exited 코드
docker logs <container> # 마지막 출력
docker inspect <c> --format '{{.State.OOMKilled}}' # 137이면 확인
docker run -it --entrypoint sh <image> # 안에서 직접 재현
종료 코드 + 마지막 로그 한 줄이면 위 원인 대부분이 좁혀집니다.
컨테이너의 PID 1과 포그라운드 프로세스 개념을 직접 깨뜨려보고 고치는 실습은 도커 트랙에서 회원가입 없이 무료로 할 수 있습니다.