도커 이미지는 절반으로, 재빌드는 5분의 1로: 의존성 정리와 빌드 캐시

회사에서 bun 모노레포로 앱 여섯 개를 만들고 있습니다. API 서버, 백그라운드 워커 둘, 프론트 셋입니다. GitHub Actions에서 도커 이미지를 빌드해 AWS ECR에 올리고 EKS가 그걸 받아 띄웁니다.

언제부터인가 배포가 느리다는 말이 나왔습니다. 들여다보니 이미지 한 개가 압축해서 250370MB였고 코드 한 줄을 고쳐도 앱 하나 빌드에 23분씩 걸렸습니다. 두 가지를 고쳐서 이미지는 절반으로, 재빌드 시간은 5분의 1로 줄인 이야기입니다.

전 후
이미지 크기 (6개 합계, 압축) 1,755MB 860MB -51%
재빌드 시간 (6개 합계) 767초 160초 -79%
빌드마다 새로 올라가는 용량 536MB 31.6MB -94%

빌드 시간은 의존성을 바꾸지 않고 코드만 고쳐 다시 빌드한 값입니다.

이미지가 무거우면 무엇이 안 좋은가

막연히 “작을수록 좋다”가 아니라 어디서 비용이 나가는지부터 짚어 봤습니다.

  1. 빌드가 오래 걸립니다. 설치하고 복사하고 압축해서 올릴 파일이 많을수록 빌드와 업로드 시간이 늘어납니다.
  2. 이미지 저장소 용량을 많이 씁니다. 빌드할 때마다 이미지가 ECR에 쌓이고 저장한 용량만큼 비용이 나갑니다.
  3. 새 파드가 늦게 뜹니다. 배포하거나 파드를 늘릴 때 노드가 이미지를 먼저 받아야 컨테이너를 시작할 수 있습니다.
  4. 노드 디스크를 많이 씁니다. 받은 이미지는 노드 디스크에 남습니다. 디스크가 차면 이미지 정리가 돌고 더 차면 파드가 축출될 수 있습니다.

이미지 크기를 줄이면 2·3·4가 좋아지고 빌드 캐시를 붙이면 1과 2가 좋아집니다.

먼저: 이미지는 레이어를 쌓아서 만든다

두 가지 개선이 모두 레이어 위에서 돌아가기 때문에 짧게 짚고 갑니다.

# ① 베이스 이미지의 레이어들을 가져온다
FROM oven/bun:slim
# ② 가장 큰 레이어
COPY node_modules ./node_modules
# ③ 작지만 매번 바뀌는 레이어
COPY dist ./dist
# 설정만 바꾸고 레이어는 없음
CMD ["bun", "dist/main.js"]

FROM은 베이스 이미지의 레이어를 가져오고, COPY와 RUN은 바뀐 파일을 레이어 하나로 더합니다. 레이어는 두 군데서 쓸모가 있습니다.

이미지를 받거나 빌드한 뒤 dive로 열어 보면 레이어마다 어떤 파일이 얼마나 들어 있는지 보입니다. 이번 작업도 dive <이미지>로 node_modules 레이어를 들여다보는 데서 시작했습니다.

1. 운영 이미지에 빌드 도구가 들어 있었다

dive로 본 node_modules에는 typescript, biome, NestJS CLI처럼 빌드할 때만 쓰는 패키지가 그대로 들어 있었습니다. 원인은 두 가지였습니다.

운영 의존성만 따로 설치하기

루트와 워크스페이스의 package.json, 그리고 bun.lock만 모아 둔 스테이지에서 운영 의존성을 따로 설치하고 그 node_modules만 운영 이미지로 가져옵니다.

# 발췌. manifests는 WORKDIR /workspace에 package.json들과 bun.lock만 모아 둔 앞 스테이지,
# builder는 전체를 설치해 /workspace/apps/api/dist를 만드는 빌드 스테이지다.
FROM manifests AS runtime-deps
RUN bun install --linker hoisted \
    --filter './apps/api' \
    --production --omit=peer \
    --ignore-scripts

FROM oven/bun:1.4.4-slim
WORKDIR /workspace
COPY --from=runtime-deps /workspace/node_modules ./node_modules
COPY --from=builder /workspace/apps/api/dist ./dist
CMD ["bun", "dist/main.js"]
옵션 하는 일
--filter <앱> 모노레포에서 이 앱이 쓰는 의존성만 설치
--production devDependencies 제외
--omit=peer peer 의존성 자동 설치 생략 (@prisma/client가 peer로 끌어오는 Prisma CLI 등)
--ignore-scripts 설치 스크립트 실행 생략
--linker hoisted 기존과 같은 hoisted 방식으로 설치해 경로가 바뀌지 않게

두 옵션은 조심해서 써야 합니다. --ignore-scripts를 켜면 postinstall에 기대는 패키지(Prisma client 생성 같은 것)가 제대로 동작하는지 확인해야 하고, 루트 node_modules만 복사하는 것도 앱을 bun build로 번들하기 때문에 가능한 일입니다. 번들하지 않는 앱이면 apps/<앱>/node_modules까지 같이 복사해야 할 수 있습니다.

여기에 더해 package.json에서 Capacitor와 Prisma CLI를 devDependencies로 옮겼습니다. 백엔드는 이미 slim 베이스를 쓰고 있었는데 프론트 세 앱은 기본 oven/bun 이미지 그대로였습니다. oven/bun:slim으로 바꾸니 이것만으로 앱당 약 21MB가 빠졌습니다.

결과: 이미지 크기 절반

앱 전 후
API 서버 264MB 143MB -46%
워커 1 253MB 127MB -50%
워커 2 258MB 143MB -45%
프론트 1 367MB 178MB -51%
프론트 2 331MB 133MB -60%
프론트 3 282MB 136MB -52%
합계 1,755MB 860MB -51%

압축 크기, 즉 ECR에 올라가는 크기 기준입니다.

2. 빌드 캐시가 다음 빌드까지 남지 않았다

이미지가 작아져도 빌드는 여전히 느렸는데, 원인은 GitHub 호스팅 러너의 동작 방식에 있었습니다.

GitHub 호스팅 러너의 빌드 캐시 비교. 이전(캐시 없음): 빌드 1이 새 VM에서 돌고, 끝나면 VM이 삭제되며 레이어 캐시도 사라져서 빌드 2는 처음부터 다시 한다. 이후(type=gha 캐시): 빌드 1이 cache-to로 GitHub Actions 캐시(기본 레포당 10GB)에 레이어를 저장하고, 빌드 2는 cache-from으로 그 레이어를 받아 바뀐 것만 다시 만든다.

Jenkins처럼 같은 서버에서 Docker 캐시를 유지하며 빌드하면 겪지 않는 문제입니다. 반대로 셀프호스팅 러너라도 빌드마다 깨끗한 환경을 쓰는 설정이면 똑같이 겪습니다.

GitHub Actions 캐시에 레이어 남기기

buildx의 캐시 내보내기 기능으로 레이어를 VM 밖, GitHub Actions 캐시에 저장합니다. 워크플로에 cache-from과 cache-to 두 줄을 더하면 됩니다. buildx를 아직 안 쓰고 있었다면 setup-buildx-action도 필요합니다.

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    push: true
    tags: ${{ env.IMAGE }}
    cache-from: type=gha,scope=api
    cache-to: type=gha,scope=api,mode=max

scope는 앱마다 다르게 줘서 서로 캐시를 덮어쓰지 않게 했습니다. mode=max는 최종 이미지 레이어만이 아니라 builder 같은 중간 스테이지 레이어까지 저장하라는 뜻입니다. 이게 없으면 bun install 단계는 매번 다시 돕니다. GitHub Actions 캐시는 기본 한도가 레포당 10GB이고 7일 동안 안 쓴 항목은 지워지며 한도가 차면 오래 안 쓴 것부터 밀려나는데, 앱 여섯 개의 중간 레이어까지 넣어도 여유가 있었습니다.

레이어는 순서가 전부

캐시를 붙여도 Dockerfile의 순서가 틀리면 효과가 줄어듭니다. 한 레이어가 바뀌면 그 뒤 레이어는 전부 다시 만들기 때문입니다.

레이어 순서 비교. 순서 바꾸기 전: 베이스 이미지 위에 dist, 그 위에 node_modules. dist가 매번 바뀌니 그 위의 node_modules까지 다시 만든다. 순서 바꾼 후: 베이스 이미지 위에 node_modules, 그 위에 dist. 의존성이 같으면 node_modules는 재사용하고 dist만 다시 만든다.

저희 Dockerfile은 dist를 먼저 복사하고 node_modules를 나중에 복사하고 있었습니다. 코드를 한 줄만 고쳐도 dist가 바뀌니 그 뒤 단계인 node_modules 복사까지 캐시가 깨져 레이어를 매번 다시 만들고 올려야 했습니다. 순서를 바꿔 node_modules를 먼저, dist를 나중에 두면 의존성이 같은 한 node_modules 레이어는 캐시에서 그대로 쓰고 ECR에도 다시 올리지 않습니다.

잘 안 바뀌는 것은 먼저, 자주 바뀌는 것은 나중에 COPY.

같은 이유로 bun install은 소스 전체가 아니라 package.json들과 bun.lock만 복사한 뒤에 실행합니다. 코드가 바뀌어도 lockfile이 그대로면 설치 단계는 캐시에서 그대로 옵니다. 앞에서 manifests 스테이지를 따로 둔 이유가 이것입니다.

결과: 바뀐 것만 다시 빌드

앱 빌드 시간 새로 올라가는 용량
API 서버 119초 → 47초 98.5MB → 4.3MB
워커 1 109초 → 8초 53.2MB → 8.1MB
워커 2 105초 → 6초 69.3MB → 8.0MB
프론트 1 205초 → 85초 136MB → 9.7MB
프론트 2 111초 → 7초 88MB → 0.6MB
프론트 3 118초 → 7초 91MB → 0.9MB
합계 767초 → 160초 (-79%) 536MB → 31.6MB (-94%)

의존성을 바꾸지 않고 코드만 고쳐 다시 빌드한 값입니다. 의존성이 바뀌는 빌드는 node_modules 레이어부터 다시 만들기 때문에 이만큼 빠르지 않고 그 경우는 따로 재지 않았습니다.

API 서버와 프론트 1이 다른 앱보다 오래 걸리는 건 코드 빌드 자체가 무거워서입니다. 캐시는 바뀌지 않은 단계만 건너뛰어 주고 바뀐 코드를 빌드하는 시간은 그대로 남습니다.

API 서버 하나로 보면 이미지는 264MB에서 143MB로, 재빌드 시간은 119초에서 47초로, 빌드마다 새로 올리는 용량은 98.5MB에서 4.3MB로 줄었습니다. 이미지의 97%는 이미 ECR에 있는 레이어를 그대로 씁니다.

점검해 볼 것

프로젝트에 돌아가서 이 넷만 확인해 보면 됩니다.

더 줄일 수 있지만 하지 않은 것

두 가지를 더 검토했는데 효과보다 신경 쓸 게 많아서 이번에는 적용하지 않았습니다.

실제로 쓰는 모듈만 남기기. API 서버는 bun build로 번들되기 때문에 실행 중에 직접 불러오는 패키지는 몇 개뿐입니다. 번들 결과에서 require와 import를 정규식으로 긁어 하위 의존성까지 모으면 약 47개 패키지가 나오고 이것만 복사하면 이미지가 84MB까지 내려갑니다(-68%). 다만 require(변수)처럼 이름이 실행 중에 정해지는 동적 import는 정규식으로 잡히지 않아서 그 기능을 처음 쓸 때 런타임 에러가 납니다. 의존성이 바뀔 때마다 다시 수집하고 동적으로 불러오는 기능을 실제로 실행해 보는 검증까지 붙여야 해서 보류했습니다.

distroless 베이스 이미지. 셸과 apt, 기본 유틸이 없는 베이스입니다. oven/bun:1.4.4 압축 크기 기준으로 기본이 104MB, slim이 84MB, distroless가 58MB입니다. 들어 있는 패키지가 적은 만큼 보안 점검 대상도 줄어듭니다. 대신 sh로 접속할 수 없어서 디버깅은 kubectl debug 임시 컨테이너로 해야 하고 sh로 도는 probe나 entrypoint 스크립트는 전부 바꿔야 합니다. OpenSSL 같은 네이티브 라이브러리를 쓰는 패키지가 있는지도 확인해야 합니다. slim으로 바꾼 것만으로 충분해서 여기까지는 가지 않았습니다.

정리

한 일 효과
의존성 정리 운영 의존성만 따로 설치, 빌드용 패키지는 devDependencies로, 베이스는 slim으로 이미지 -51%
빌드 캐시 GitHub Actions 캐시에 레이어 저장, node_modules를 dist보다 먼저 COPY 재빌드 시간 -79%, 새로 올리는 용량 -94%
점검 목록 위의 넷 다른 프로젝트도 같은 눈으로 본다

고친 건 package.json의 의존성 분류, Dockerfile 몇 줄, 워크플로의 캐시 설정 두 줄이 전부였습니다. 멀티스테이지 빌드를 쓰고 있다고 해서 운영 이미지가 깨끗하다는 보장은 없습니다. dive로 한 번 열어 보세요.