Docker 멀티스테이지 빌드 — 이미지 크기 최소화 패턴

Summary#

Docker 멀티스테이지 빌드는 빌드 도구·소스를 최종 이미지에서 분리해 이미지 크기를 1/5~1/10로 줄인다. 핵심은 COPY --from=builder로 결과물만 추출하고, BuildKit --mount=type=cache로 레이어 캐시를 극대화하는 것이다.

Outcome#

Python 멀티스테이지 (1.2GB → 120MB):

# syntax=docker/dockerfile:1
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip     pip install --prefix=/install -r requirements.txt

FROM python:3.12-slim AS runtime
COPY --from=builder /install /usr/local
COPY src/ /app/src/
USER nonroot:nonroot
CMD ["python", "-m", "app"]

Node.js (distroless, 800MB → 80MB):

FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json .
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev

FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY dist/ ./dist/
CMD ["node", "dist/index.js"]

Key Points#

--mount=type=cache: 레이어 캐시 유지 — CI에서 재빌드 시 pip install 스킵
--prefix=/install: 파이썬 패키지를 별도 경로에 설치 후 COPY로 추출
USER nonroot: 루트 권한 컨테이너는 보안 취약 — 비루트 실행 필수
불필요한 빌드 도구(gcc·make·git)는 최종 스테이지에 포함 금지

Caveats#

distroless(no shell)는 디버깅 어려움 — 개발용은 -debug 태그 사용. 멀티아키텍처(amd64/arm64) 빌드는 docker buildx build --platform. COPY --from=builder에서 경로 정확성 주의 — 오타 시 런타임에서야 발견됨.

Sagwan Revalidation 2026-04-15T14:55:43Z#

verdict: ok
note: LLM unavailable: [CLI 오류 1]

Sagwan Revalidation 2026-04-16T15:24:21Z#

verdict: ok
note: 멀티스테이지/BuildKit 캐시/보안(nonroot) 모두 2026년 현재 표준 practice이며 코드 정확함.