docker-best-practices

Docker のベストプラクティス

マルチステージビルド

FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine AS runtime
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001 -G appgroup
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/healthz || exit 1
CMD ["node", "dist/server.js"]

依存関係のインストールとビルド手順を分離します。最終ステージには実行時に必要な成果物のみを含めます。

Python のマルチステージビルド

FROM python:3.12-slim AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
RUN useradd --create-home appuser
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY . .
USER appuser
CMD ["gunicorn", "app:create_app()", "-b", "0.0.0.0:8000", "-w", "4"]

Docker Compose

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: runtime
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/app
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d app"]
      interval: 5s
      timeout: 3s
      retries: 5

  cache:
    image: redis:7-alpine
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru

volumes:
  pgdata:

.dockerignore

node_modules
.git
.env*
*.md
docker-compose*.yml
.github
coverage
dist

ビルドコンテキストのサイズを小さくし、シークレットの漏えいを防ぐため、必ず .dockerignore を含めてください。

イメージ最適化のヒント

# Check image size breakdown
docker history --human --no-trunc <image>

# Use dive for layer analysis
dive <image>

# Multi-arch build
docker buildx build --platform linux/amd64,linux/arm64 -t registry/app:1.0 --push .

レイヤー数を減らすため、RUN コマンドをまとめます。キャッシュ効率を高めるため、変更頻度の低い命令から高い命令へと順に記述します。

避けるべきパターン

• コンテナ内で root として実行する
• COPY で十分な場合に ADD を使用する（ADD は tarball を自動展開し、URL から取得します）
• Dockerfile の環境変数にシークレットを保存する
• ベースイメージのバージョンを固定しない（FROM node:latest）
• .dockerignore がなく、ビルドコンテキストが大きくなる
• 本番用イメージに開発用の依存関係をインストールする

チェックリスト

• マルチステージビルドでビルドステージと実行ステージを分離している
• 非 root ユーザーを作成し、USER ディレクティブで使用している
• ベースイメージのバージョンを特定のバージョンに固定している（例：node:22-alpine）
• .dockerignore で .git、node_modules、.env を除外している
• HEALTHCHECK 命令を定義している
• 本番用イメージにビルドツールや開発用の依存関係が含まれていない
• docker-compose でヘルスチェック条件付きの depends_on を使用している
• シークレットを Dockerfile の ENV ではなく、ビルドシークレットまたは実行時のマウント経由で渡している