Docker compose 빌드가 느릴 때 확인할 것

Docker compose로 로컬 개발 환경을 구성하다 보면 어느 순간부터 빌드가 느려진다. 처음엔 10초면 끝나던 빌드가 어느새 몇 분이 걸리곤 한다. 원인을 찾기 위해 가장 먼저 해야 할 일은 현재 상태를 명확히 파악하는 것이다.

컨테이너 상태 확인

빌드 전에 먼저 현재 실행 중인 컨테이너들을 살펴봐야 한다:

docker ps

정상일 때의 상태와 비교해보면 어떤 서비스가 문제인지 알 수 있다. 혹시 같은 이름의 컨테이너가 여러 개 띄워져 있지 않은지, 모두 정상적인 상태('Up')인지 확인하자.

로그 확인

가장 최근 100줄의 로그를 보면서 에러나 경고를 찾아보자:

docker logs --tail=100 service-name

로그에 Pulling image, Building, Downloading 같은 문구가 있다면 네트워크 작업이 진행 중이거나 이미지 업데이트가 일어나고 있다는 뜻이다. 또는 헬스 체크 실패로 컨테이너가 계속 재시작되고 있을 수도 있다.

이미지 태그와 캐시

Docker 이미지 빌드의 느림은 대부분 캐시 문제다. 이미지 태그를 확인해보자:

docker images

같은 이미지의 여러 버전이 남아있거나, <none>이라는 이름의 이미지들이 쌓여있다면 정리가 필요하다:

docker image prune -a

이 명령은 사용하지 않는 이미지를 모두 삭제한다. 하지만 정말 필요없는 이미지만 삭제되는지 확인하고 실행하자.

환경 변수 점검

compose 파일에서 환경 변수가 제대로 설정되어 있는지 확인해야 한다. 특히 빌드 타임 변수(build.args)가 정의되어 있다면, 그 값이 매번 변경되면 캐시가 무효화된다.

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NODE_ENV: development

포트 매핑도 다시 한 번 확인하자. 로컬에서는 3000:3000으로 하나의 포트만 써야 하는데 실수로 여러 포트를 열고 있지는 않은지 본다.

실제 빌드 재시작

캐시를 완전히 무시하고 새로 빌드해보자:

docker compose build --no-cache

이 작업은 시간이 좀 걸리겠지만, 캐시 레이어 때문에 생기는 문제를 명확히 구분할 수 있다. 만약 --no-cache로 빌드하면 빠르다면 캐시 무효화 문제고, 여전히 느리다면 실제 빌드 과정이 느린 것이다.

최종 확인

1. 로그와 응답에서 바뀐 부분을 명확히 파악한다.
2. 정상적으로 컨테이너가 재시작되고 정상 상태('Up')를 유지하는지 확인한다.
3. 브라우저에서 실제로 서비스가 응답하는지 본다.

가끔 빌드는 빠르지만 헬스 체크 실패로 자꾸 재시작되는 경우도 있다. 그럴 때는 환경 변수나 의존성 서비스(DB, Redis 등) 상태를 점검해야 한다.