Docker Compose 배포에서 orphan 컨테이너를 지우기 전 확인한 체크리스트

경고 한 줄이지만 데이터까지 건드릴 수 있다

Compose 파일에서 web 서비스를 frontend로 바꾼 뒤 배포 명령에 orphan 컨테이너 경고가 나왔다. --remove-orphans를 붙이면 끝날 것 같았지만, 같은 프로젝트 이름 아래에 임시 작업 컨테이너가 남아 있을 가능성도 있었다. 어떤 컨테이너가 더 이상 정의되지 않았는지 확인하기 전에는 삭제하지 않기로 했다.

현재 Compose 프로젝트를 식별한다

docker compose ps -a
docker compose config --services
docker compose ls

docker compose ps -a의 이름과 상태를 보고, config --services 결과에 없는 서비스만 후보로 표시했다. 디렉터리가 다르더라도 COMPOSE_PROJECT_NAME이 같으면 같은 프로젝트로 묶일 수 있다는 점이 특히 헷갈렸다.

삭제 전에는 데이터 연결을 본다

docker inspect <container-name> --format '{{json .Mounts}}'
docker inspect <container-name> --format '{{json .Config.Labels}}'
docker volume ls

삭제 대상이 named volume을 쓰는 DB인지, 단순한 이전 애플리케이션인지 구분했다. 컨테이너 삭제는 볼륨 삭제와 다르지만, 명령을 이어 쓰다가 docker volume prune까지 실행하는 사고가 더 위험하다. 운영 서버에서는 prune을 정기 배포 명령에 넣지 않았다.

확인한 뒤에만 정리한다

새 서비스가 healthcheck를 통과하고 로그가 정상인 것을 확인한 뒤 실행했다.

docker compose up -d --remove-orphans
docker compose ps
docker compose logs --tail=50 frontend

down -v는 named volume도 지울 수 있으므로 롤백이나 데이터베이스가 있는 스택에는 사용하지 않았다. 단순한 경고를 없애는 것보다, 삭제 범위를 이해하는 것이 먼저다.

배포 체크리스트

• Compose 프로젝트 이름이 의도한 값인가
• orphan 후보가 현재 config의 서비스 목록에 정말 없는가
• 후보 컨테이너의 volume mount와 재시작 정책을 확인했는가
• 새 컨테이너의 상태와 최근 로그를 확인했는가
• 삭제 명령에 volume 제거 옵션이 섞이지 않았는가

이후에는 서비스 이름을 바꾸는 PR에 이전 이름과 정리 시점을 같이 적는다. 경고를 조용하게 만드는 작업도 배포 변경의 일부로 다루는 편이 안전했다.