Standalone 출력으로 Docker 이미지 줄이기

실행에 필요한 파일만 추적해

next.config.ts에 output: 'standalone'을 설정하면 next build가 실행 시점에 필요한 파일을 추려 최소 server.js와 함께 내보내. 전체 저장소와 모든 개발 의존성을 넣지 않아도 되는 자체 완결 디렉터리가 생기며 보통 100MB 아래의 작은 컨테이너를 만들 수 있어.

다단계 빌드로 도구와 실행물을 나눠

deps 단계는 의존성을 설치하고, builder 단계는 next build를 실행하고, runner 단계는 standalone 결과만 복사해. 각 단계가 깨끗한 이미지에서 시작하므로 최종 이미지에는 컴파일러와 소스 캐시가 남지 않아.

정적 자산은 따로 복사해야 해

Standalone 출력은 애플리케이션 실행 코드를 묶지만 .next/static과 public/을 runner에 자동 포함하지 않아. 두 경로를 명시적으로 복사하지 않으면 서버는 떠도 CSS, 클라이언트 chunk, 공개 이미지가 404가 될 수 있어.

컨테이너 안에서도 권한과 health를 확인해

root가 아닌 사용자로 실행하고, 실제 HTTP 응답을 보는 health check를 둬. 이미지 빌드 성공만으로 서버의 환경 변수와 정적 파일이 맞다는 보장은 없어.

Docker 빌드에서 lockfile 고정, non-root 실행, signal 종료, health check, 정적 자산 복사를 검증해. dependency 파일이 안 바뀌면 npm ci layer가 재사용되고, 소스만 바뀔 때 builder 이후만 다시 도는지 확인해. 최종 이미지에 비밀 .env와 개발 도구가 없는지도 검사해. 이미지 크기만 줄이다 필요한 native library와 인증서를 빼면 production에서만 실패해. 100MB라는 숫자보다 cold start, 취약점 수, 디버그 가능성, 재현 가능한 빌드가 더 중요할 수 있어. 작은 base image를 쓰되 실제 실행 경로를 끝까지 시험해.

다단계 이미지를 두 번 build해 dependency cache 적중과 최종 크기를 비교하고, 컨테이너 안에 source·비밀·개발 도구가 남았는지 검사해. .next/static과 public을 일부러 빼 404를 재현한 뒤 health와 핵심 브라우저 흐름이 이를 잡는지 확인해.

Code

standalone 출력 활성화하기·ts

// next.config.ts
import type { NextConfig } from 'next';
const config: NextConfig = {
  output: 'standalone',
};
export default config;

다단계 Dockerfile·text

FROM node:20-alpine AS base

FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
CMD ["node", "server.js"]

빌드하고 실행하기·bash

docker build -t my-nextjs-app .
docker run -p 3000:3000 \
  -e DATABASE_URL=postgresql://host/db \
  -e AUTH_SECRET=mysecret \
  my-nextjs-app

실행에 필요한 파일만 추적해

다단계 빌드로 도구와 실행물을 나눠

정적 자산은 따로 복사해야 해

컨테이너 안에서도 권한과 health를 확인해

Code

External links

Exercise

Progress

댓글 0