Docker 멀티스테이지 빌드로 Node.js 이미지 크기를 줄이는 방법

용량이 큰 Docker Node.js 이미지의 비효율성과 보안 위험 극복하기

Docker 이미지를 단일 단계로 대충 말아두면 최종 가상 머신 디렉토리 안에 tsc 컴파일러, 웹팩 빌더, 린트 도구 등 오직 개발 시에만 쓰이고 프로덕션 서버 실행 단계에서는 일절 필요 없는 무거운 패키지들이 몽땅 상주합니다. 이는 단순히 AWS 컨테이너 레지스트리(ECR) 저장소 비용을 갉아먹는 것 이상의 트러블을 만듭니다. 이미지가 크면 배포할 때마다 서버가 기가바이트 단위의 파일을 다운받느라 트래픽을 허비하여 오토스케일링 대응 속도가 굼떠집니다. 더욱이, 이미지 내부에 쓸모없는 리눅스 패키지와 라이브러리 찌꺼기가 많아질수록 공인된 보안 취약점 점검(CVE) 스캔에서 지적을 당하는 침입 위험 표면(Attack Surface)도 비대해지는 악영향을 초래합니다.

builder와 runner 스테이지로 격리하는 Docker Node.js 멀티스테이지 설계법

멀티스테이지의 핵심 동작 요령은 하나의 Dockerfile에 여러 개의 FROM 절을 개설해 활용하는 것입니다. 첫 번째 블록인 FROM node:20 AS builder 영역은 소스 코드를 컴파일하고 의존성을 긁어 모으는 공장 역할을 합니다. 무거운 빌드 명령이 마감되면, 그 아래로 두 번째 FROM node:20-alpine AS runner 절을 선언해 새로운 가벼운 가상 컨테이너를 가동시킵니다. 이후 COPY --from=builder 명령 지시어를 기재해, 오직 빌드 공장에서 완성된 순수 아웃풋 디렉토리(/app/dist 등)와 프로덕션 구동용 핵심 패키지들만 정밀 선택 복사해 옵니다. 최종 이미지 파일에는 이 두 번째 runner 환경의 최소 레이어만 남게 되므로, 첫째 공장의 껍데기는 온데간데없이 사라진 순수한 에센셜 패키지만이 컴파일되어 이미지 껍데기를 대폭 줄이게 됩니다.

# 1단계: 빌드 전용 공장 (builder)
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 2단계: 경량 런타임 환경 (runner)
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
# 프로덕션 전용 라이브러리만 선별 설치
RUN npm ci --omit=dev
# 이전 builder 공장에서 나온 dist 결과물만 전송 링킹
COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]

standalone 옵션과 연계하여 Docker Node.js 빌드 최적화하기

Next.js 프레임워크 프로젝트 환경이라면 next.config.ts 파일 내부의 컴파일러 옵션 설정 객체에 output: 'standalone' 옵션을 심어주는 것이 궁극의 치트키입니다. 빌드를 올릴 때 넥스트가 소스 코드를 읽어 들여 런타임 구동에 필요한 핵심 자바스크립트 모듈 파일들을 .next/standalone 이라는 폴더 안으로 안전하게 자생 응축시켜 주기 때문이죠. 이 standalone 폴더 안에는 무거운 넥스트 내부 코어 패키지들까지 컴파일 복사되어 담겨 있으므로, runner 스테이지에서는 호스트 디바이스의 무거운 node_modules를 통째 복사할 것 없이 이 standalone 디렉토리 하나만 쏙 복사하여 서버 구동용 server.js 파일을 실행해 주면 빌드가 초경량으로 끝납니다.

.dockerignore를 통한 Docker 빌드 컨텍스트 전송 시간 절약 요령

멀티스테이지와 별개로, 프로젝트 루트에 .dockerignore 설정 파일을 파서 기입해 두는 것도 컨테이너 이미지 개발 생산성 향상에 막대한 기여를 단행합니다. 이 파일이 없으면 docker build 명령이 작동하는 첫 단계에서 호스트 개발 장비의 무겁디무거운 node_modules 폴더와 로컬 빌드 테스트 찌꺼기(.next, .git 폴더) 전체를 도커 백그라운드 가상 데몬으로 복사 전송하는 'Sending build context to Docker daemon' 지연 시간이 걸려 몇 분간 터미널이 멈춥니다. 무시 목록에 이 3가지를 명확히 엮어두는 것만으로 빌드 시작 대기 시간을 단 1초 미만으로 압축할 수 있습니다.

캐시 마운트 기법을 적용해 Docker Node.js 빌드 속도 향상시키기

매번 도커 빌드가 돌 때마다 아무리 캐싱이 된다 한들 수많은 npm 패키지들을 다운받는 과정은 큰 네트워크 지연을 초래합니다. 이때 Docker BuildKit 엔진이 제공하는 캐시 마운트 명령어 스펙을 차용해 RUN --mount=type=cache,target=/root/.npm npm ci 형태로 구문을 개조해 주면, 빌드 대상 파일이 변경되어 의존성을 다시 깔아야 하는 불행한 상황에서도 도커 로컬 캐시 디스크 영역에 적재되어 있던 백업 패키지를 가져다 부착하므로 빌드 속도가 경이롭게 고속 질주하게 조킵니다.