실전 Dockerfile 작성 패턴: 프레임워크별 베스트 프랙티스

Dockerfile 작성 기본 원칙

1. 멀티스테이지 빌드 사용

빌드 도구와 런타임을 분리해서 최종 이미지 크기를 대폭 줄입니다.

Before (Single Stage):

FROM node:18
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
CMD ["npm", "start"]

After (Multi-Stage):

# Build stage
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY package*.json ./
RUN npm ci --only=production
CMD ["node", "dist/index.js"]

멀티스테이지 빌드를 사용하면:

빌드 도구(컴파일러, 개발 의존성)가 최종 이미지에 포함되지 않음
Alpine 베이스 이미지로 경량화
보안: 공격 표면 감소

2. 레이어 캐싱 최적화

❌ 나쁜 예:

COPY . .
RUN npm install

package.json이 바뀌지 않아도 소스 코드만 바뀌면 npm install 재실행

✅ 좋은 예:

COPY package*.json ./
RUN npm install
COPY . .

package.json이 바뀌지 않으면 캐시된 레이어 재사용

3. 보안 강화

non-root 유저 사용
Alpine 또는 Distroless 베이스 이미지
취약점 스캔 (Trivy, Snyk)

4. .dockerignore 필수

node_modules
npm-debug.log
.env
.git
.vscode
*.md
.DS_Store
dist
build
coverage

Next.js (App Router)

최적화된 Dockerfile

Next.js 공식 예제를 기반으로 한 프로덕션 최적화 버전입니다.

# ===========================
# Dependencies Stage
# ===========================
FROM node:18-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

# package.json과 lock 파일만 먼저 복사
COPY package.json package-lock.json* ./
RUN npm ci

# ===========================
# Builder Stage
# ===========================
FROM node:18-alpine AS builder
WORKDIR /app

# deps에서 node_modules 복사
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# 환경 변수 (빌드 시점에 필요한 경우)
# ARG NEXT_PUBLIC_API_URL
# ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL

# Next.js 텔레메트리 비활성화
ENV NEXT_TELEMETRY_DISABLED 1

# 빌드 실행
RUN npm run build

# ===========================
# Runner Stage
# ===========================
FROM node:18-alpine AS runner
WORKDIR /app

ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

# non-root 유저 생성
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# 필요한 파일만 복사
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

# 유저 권한 설정
USER nextjs

EXPOSE 3000
ENV PORT 3000

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

next.config.js 설정 필수

// next.config.js
module.exports = {
  output: 'standalone',
};

output: 'standalone'이 중요한 이유:

Next.js는 기본적으로 node_modules 전체를 필요로 함
standalone 모드는 실제로 사용되는 파일만 .next/standalone에 복사
불필요한 의존성 제외로 이미지 크기 대폭 감소
server.js 파일이 자동 생성되어 독립 실행 가능

Docker Compose 예시

version: '3.8'

services:
  nextjs:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_API_URL=https://api.example.com
    restart: unless-stopped

React + Vite

최적화된 Dockerfile

# ===========================
# Build Stage
# ===========================
FROM node:18-alpine AS builder
WORKDIR /app

# 의존성 설치
COPY package.json package-lock.json* ./
RUN npm ci

# 소스 코드 복사 및 빌드
COPY . .
RUN npm run build

# ===========================
# Production Stage (nginx)
# ===========================
FROM nginx:alpine AS runner

# nginx 설정 복사
COPY nginx.conf /etc/nginx/conf.d/default.conf

# 빌드된 파일 복사
COPY --from=builder /app/dist /usr/share/nginx/html

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

nginx.conf

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    # SPA routing 처리
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 정적 파일 캐싱
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # gzip 압축
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

.dockerignore

node_modules
dist
.env
.env.local
.git
.vscode
*.md

Docker Compose 예시

version: '3.8'

services:
  react-app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - VITE_API_URL=https://api.example.com
    ports:
      - '80:80'
    restart: unless-stopped

환경 변수 빌드 시 주입

# Build Stage에 추가
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL

Express.js

최적화된 Dockerfile

# ===========================
# Build Stage (TypeScript 사용 시)
# ===========================
FROM node:18-alpine AS builder
WORKDIR /app

# 의존성 설치
COPY package.json package-lock.json* ./
RUN npm ci

# 소스 복사 및 빌드
COPY . .
RUN npm run build

# ===========================
# Production Stage
# ===========================
FROM node:18-alpine AS runner
WORKDIR /app

# non-root 유저
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nodejs -u 1001

# 프로덕션 의존성만 설치
COPY package.json package-lock.json* ./
RUN npm ci --only=production && npm cache clean --force

# 빌드된 파일 복사 (TypeScript인 경우)
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist

# 또는 JavaScript 프로젝트인 경우
# COPY --chown=nodejs:nodejs ./src ./src

USER nodejs

EXPOSE 3000

# 헬스체크
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

CMD ["node", "dist/index.js"]

JavaScript 프로젝트용 (빌드 불필요)

FROM node:18-alpine
WORKDIR /app

RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

COPY package.json package-lock.json* ./
RUN npm ci --only=production && npm cache clean --force

COPY --chown=nodejs:nodejs . .

USER nodejs

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

CMD ["node", "src/index.js"]

Docker Compose (DB 포함)

version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_NAME=myapp
      - DB_USER=postgres
      - DB_PASSWORD=password
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

NestJS

최적화된 Dockerfile

# ===========================
# Development Dependencies
# ===========================
FROM node:18-alpine AS development
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

COPY . .

# ===========================
# Build Stage
# ===========================
FROM node:18-alpine AS builder
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

COPY . .
RUN npm run build

# ===========================
# Production Stage
# ===========================
FROM node:18-alpine AS production
WORKDIR /app

# non-root 유저
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nestjs -u 1001

# 프로덕션 의존성만 설치
COPY package.json package-lock.json* ./
RUN npm ci --only=production && npm cache clean --force

# 빌드된 파일 복사
COPY --from=builder --chown=nestjs:nodejs /app/dist ./dist

USER nestjs

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

CMD ["node", "dist/main.js"]

Docker Compose (Redis + PostgreSQL)

version: '3.8'

services:
  nestjs:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://postgres:password@postgres:5432/nestdb
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=nestdb
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 5
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

개발 환경용 docker-compose.dev.yml

version: '3.8'

services:
  nestjs-dev:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    ports:
      - '3000:3000'
      - '9229:9229' # Debug port
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@postgres:5432/nestdb
    command: npm run start:dev
    depends_on:
      - postgres

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=nestdb
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    ports:
      - '5432:5432'
    volumes:
      - postgres_dev_data:/var/lib/postgresql/data

volumes:
  postgres_dev_data:

FastAPI (Python)

최적화된 Dockerfile

# ===========================
# Build Stage
# ===========================
FROM python:3.11-slim AS builder

WORKDIR /app

# 시스템 의존성
RUN apt-get update && \
    apt-get install -y --no-install-recommends gcc && \
    rm -rf /var/lib/apt/lists/*

# Python 의존성 설치
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# ===========================
# Production Stage
# ===========================
FROM python:3.11-slim AS runner

WORKDIR /app

# non-root 유저
RUN groupadd -r appuser && useradd -r -g appuser appuser

# builder에서 설치된 패키지 복사
COPY --from=builder /root/.local /home/appuser/.local

# PATH에 추가
ENV PATH=/home/appuser/.local/bin:$PATH

# 소스 코드 복사
COPY --chown=appuser:appuser . .

USER appuser

EXPOSE 8000

# 헬스체크
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Poetry 사용 시

# ===========================
# Build Stage
# ===========================
FROM python:3.11-slim AS builder

WORKDIR /app

# Poetry 설치
RUN pip install --no-cache-dir poetry

# pyproject.toml과 poetry.lock 복사
COPY pyproject.toml poetry.lock ./

# 의존성을 requirements.txt로 export
RUN poetry export -f requirements.txt --output requirements.txt --without-hashes

# 의존성 설치
RUN pip install --user --no-cache-dir -r requirements.txt

# ===========================
# Production Stage
# ===========================
FROM python:3.11-slim AS runner

WORKDIR /app

RUN groupadd -r appuser && useradd -r -g appuser appuser

COPY --from=builder /root/.local /home/appuser/.local
ENV PATH=/home/appuser/.local/bin:$PATH

COPY --chown=appuser:appuser ./app ./app

USER appuser

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

requirements.txt 예시

fastapi==0.104.1
uvicorn[standard]==0.24.0
pydantic==2.5.0
sqlalchemy==2.0.23
alembic==1.12.1
asyncpg==0.29.0
redis==5.0.1
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.6

Docker Compose (PostgreSQL + Redis)

version: '3.8'

services:
  fastapi:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '8000:8000'
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:password@postgres:5432/fastapi
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=fastapi
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 5
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

개발 환경용 설정

version: '3.8'

services:
  fastapi-dev:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '8000:8000'
    volumes:
      - ./app:/app/app
    environment:
      - ENVIRONMENT=development
      - DATABASE_URL=postgresql+asyncpg://postgres:password@postgres:5432/fastapi
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
    depends_on:
      - postgres

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=fastapi
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    ports:
      - '5432:5432'
    volumes:
      - postgres_dev_data:/var/lib/postgresql/data

volumes:
  postgres_dev_data:

공통 최적화 팁

1. 빌드 시간 단축

병렬 빌드 활성화:

# Docker BuildKit 사용
DOCKER_BUILDKIT=1 docker build -t myapp .

# 또는 환경 변수로 설정
export DOCKER_BUILDKIT=1

멀티 플랫폼 빌드:

# arm64, amd64 동시 빌드
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

2. 이미지 스캔 (보안)

Trivy 사용:

# 이미지 스캔
trivy image myapp:latest

# 심각도 HIGH 이상만 표시
trivy image --severity HIGH,CRITICAL myapp:latest

Docker Scout (Docker Desktop 포함):

docker scout cves myapp:latest

3. 레이어 확인

# 레이어별 크기 확인
docker history myapp:latest

# 상세 정보
docker inspect myapp:latest

4. 불필요한 파일 제거

# 캐시 삭제
RUN apt-get update && \
    apt-get install -y package && \
    rm -rf /var/lib/apt/lists/*

# npm 캐시 삭제
RUN npm ci && npm cache clean --force

5. 환경별 빌드

# 개발 환경
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# 프로덕션 환경
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up

주의사항

1. Secrets 관리

❌ 절대 하지 말 것:

# 이미지에 secrets 포함
COPY .env .

✅ 올바른 방법:

# 런타임에 환경 변수로 주입
docker run -e DB_PASSWORD=secret myapp

또는 Docker Secrets 사용:

# docker-compose.yml
services:
  app:
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

2. 헬스체크 필수

모든 프로덕션 컨테이너에 헬스체크 추가:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

3. 로그 관리

stdout/stderr로 로그 출력:

// Express.js
console.log('Server started');
console.error('Error occurred');

컨테이너 로그 확인:

docker logs -f container-name

실전 배포 워크플로우

1. 로컬 빌드 & 테스트

# 빌드
docker build -t myapp:latest .

# 실행
docker run -p 3000:3000 myapp:latest

# 헬스체크 확인
curl http://localhost:3000/health

2. CI/CD (GitHub Actions 예시)

name: Docker Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: username/myapp:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Scan image
        run: |
          docker run --rm \
            -v /var/run/docker.sock:/var/run/docker.sock \
            aquasec/trivy image username/myapp:latest

3. 배포 (Kubernetes 예시)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: username/myapp:latest
          ports:
            - containerPort: 3000
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 5
          resources:
            requests:
              memory: '256Mi'
              cpu: '250m'
            limits:
              memory: '512Mi'
              cpu: '500m'

마치며

체크리스트

✅ 멀티스테이지 빌드 사용 ✅ 레이어 캐싱 최적화 ✅ non-root 유저 실행 ✅ .dockerignore 작성 ✅ 헬스체크 설정 ✅ 보안 스캔 실행 ✅ 이미지 크기 확인

추가 학습 자료

작성일: 2025-11-17 마지막 수정: 2025-11-17

목차

Dockerfile 작성 기본 원칙

1. 멀티스테이지 빌드 사용

2. 레이어 캐싱 최적화

3. 보안 강화

4. .dockerignore 필수

Next.js (App Router)

최적화된 Dockerfile

next.config.js 설정 필수

Docker Compose 예시

React + Vite

최적화된 Dockerfile

nginx.conf

.dockerignore

Docker Compose 예시

환경 변수 빌드 시 주입

Express.js

최적화된 Dockerfile

JavaScript 프로젝트용 (빌드 불필요)

Docker Compose (DB 포함)

NestJS

최적화된 Dockerfile

Docker Compose (Redis + PostgreSQL)

개발 환경용 docker-compose.dev.yml

FastAPI (Python)

최적화된 Dockerfile

Poetry 사용 시

requirements.txt 예시

Docker Compose (PostgreSQL + Redis)

개발 환경용 설정

공통 최적화 팁

1. 빌드 시간 단축

2. 이미지 스캔 (보안)

3. 레이어 확인

4. 불필요한 파일 제거

5. 환경별 빌드

주의사항

1. Secrets 관리

2. 헬스체크 필수

3. 로그 관리

실전 배포 워크플로우

1. 로컬 빌드 & 테스트

2. CI/CD (GitHub Actions 예시)

3. 배포 (Kubernetes 예시)

마치며

체크리스트

추가 학습 자료