Docker Patterns

コンテナ化された開発のための Docker と Docker Compose のベストプラクティス。

使用するタイミング

• ローカル開発用に Docker Compose をセットアップしている
• マルチコンテナアーキテクチャを設計している
• コンテナネットワーキングまたはボリュームの問題をトラブルシューティングしている
• セキュリティとサイズについて Dockerfile をレビューしている
• ローカル開発からコンテナ化されたワークフローに移行している

ローカル開発用 Docker Compose

標準的な Web アプリケーションスタック

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: dev                     # Use dev stage of multi-stage Dockerfile
    ports:
      - "3000:3000"
    volumes:
      - .:/app                        # Bind mount for hot reload
      - /app/node_modules             # Anonymous volume -- preserves container deps
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
      - REDIS_URL=redis://redis:6379/0
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_dev
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data

  mailpit:                            # Local email testing
    image: axllent/mailpit
    ports:
      - "8025:8025"                   # Web UI
      - "1025:1025"                   # SMTP

volumes:
  pgdata:
  redisdata:

開発環境と本番環境の Dockerfile

# Stage: dependencies
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Stage: dev (hot reload, debug tools)
FROM node:22-alpine AS dev
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]

# Stage: build
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm prune --production

# Stage: production (minimal image)
FROM node:22-alpine AS production
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser
COPY --from=build --chown=appuser:appgroup /app/dist ./dist
COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]

オーバーライドファイル

# docker-compose.override.yml (自動ロード、開発専用設定)
services:
  app:
    environment:
      - DEBUG=app:*
      - LOG_LEVEL=debug
    ports:
      - "9229:9229"                   # Node.js debugger

# docker-compose.prod.yml (本番環境用、明示的に指定)
services:
  app:
    build:
      target: production
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

# 開発環境（オーバーライドを自動ロード）
docker compose up

# 本番環境
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

ネットワーキング

サービスディスカバリー

同じ Compose ネットワーク内のサービスはサービス名で解決できます：

# 「app」コンテナから：
postgres://postgres:postgres@db:5432/app_dev    # 「db」は db コンテナに解決
redis://redis:6379/0                             # 「redis」は redis コンテナに解決

カスタムネットワーク

services:
  frontend:
    networks:
      - frontend-net

  api:
    networks:
      - frontend-net
      - backend-net

  db:
    networks:
      - backend-net              # Only reachable from api, not frontend

networks:
  frontend-net:
  backend-net:

必要な部分だけを公開

services:
  db:
    ports:
      - "127.0.0.1:5432:5432"   # ホストからのみアクセス可能、ネットワークからはアクセス不可
    # 本番環境ではポートを省略 -- Docker ネットワーク内からのみアクセス可能

ボリュームの戦略

volumes:
  # Named volume: コンテナの再起動時に永続化、Docker で管理
  pgdata:

  # Bind mount: ホストディレクトリをコンテナにマッピング（開発用）
  # - ./src:/app/src

  # Anonymous volume: bind mount オーバーライドからのコンテナ生成コンテンツを保護
  # - /app/node_modules

一般的なパターン

services:
  app:
    volumes:
      - .:/app                   # ソースコード（hot reload 用 bind mount）
      - /app/node_modules        # コンテナの node_modules をホストから保護
      - /app/.next               # ビルドキャッシュを保護

  db:
    volumes:
      - pgdata:/var/lib/postgresql/data          # 永続データ
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql  # 初期化スクリプト

コンテナセキュリティ

Dockerfile 強化

# 1. 特定のタグを使用（:latest は絶対に使用しない）
FROM node:22.12-alpine3.20

# 2. root 以外で実行
RUN addgroup -g 1001 -S app && adduser -S app -u 1001
USER app

# 3. ケーパビリティをドロップ（compose で）
# 4. 可能な限りルートファイルシステムを読み取り専用に
# 5. イメージレイヤーにシークレットを含めない

Compose セキュリティ

services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
      - /app/.cache
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE          # Only if binding to ports < 1024

シークレット管理

# 良い例：環境変数を使用（実行時に注入）
services:
  app:
    env_file:
      - .env                     # .env を git にコミットしないこと
    environment:
      - API_KEY                  # ホスト環境から継承

# 良い例：Docker シークレット（Swarm モード）
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  db:
    secrets:
      - db_password

# 悪い例：イメージにハードコード
# ENV API_KEY=sk-proj-xxxxx      # 絶対にこれをしないこと

.dockerignore

node_modules
.git
.env
.env.*
dist
coverage
*.log
.next
.cache
docker-compose*.yml
Dockerfile*
README.md
tests/

デバッグ

よく使うコマンド

# ログを表示
docker compose logs -f app           # app のログをフォロー
docker compose logs --tail=50 db     # db の最後 50 行

# 実行中のコンテナでコマンドを実行
docker compose exec app sh           # app にシェルでアクセス
docker compose exec db psql -U postgres  # postgres に接続

# 検査
docker compose ps                     # 実行中のサービス
docker compose top                    # 各コンテナ内のプロセス
docker stats                          # リソース使用状況

# リビルド
docker compose up --build             # イメージをリビルド
docker compose build --no-cache app   # 完全リビルドを強制

# クリーンアップ
docker compose down                   # コンテナを停止・削除
docker compose down -v                # ボリュームも削除（破壊的）
docker system prune                   # 未使用のイメージ/コンテナを削除

ネットワークの問題をデバッグ

# コンテナ内の DNS 解決を確認
docker compose exec app nslookup db

# 接続性を確認
docker compose exec app wget -qO- http://api:3000/health

# ネットワークを検査
docker network ls
docker network inspect <project>_default

アンチパターン

# 悪い例：本番環境でオーケストレーションなしで docker compose を使用
# 本番環境のマルチコンテナワークロードには Kubernetes、ECS、Docker Swarm を使用

# 悪い例：ボリュームなしでコンテナにデータを保存
# コンテナはエフェメラル -- ボリュームなしで再起動するとすべてのデータが失われる

# 悪い例：root で実行
# 常に非root ユーザーを作成して使用

# 悪い例：:latest タグを使用
# 再現可能なビルドのため特定のバージョンにピン留めする

# 悪い例：すべてのサービスを 1 つの巨大なコンテナに詰め込む
# 関心の分離：1 つのコンテナに 1 つのプロセス

# 悪い例：docker-compose.yml にシークレットを入れる
# .env ファイル（gitignored）または Docker シークレットを使用

このスキルを使用するタイミング

• ローカル開発用に Docker Compose をセットアップしている
• マルチコンテナアーキテクチャを設計している
• コンテナの問題をトラブルシューティングしている
• セキュリティについて Dockerfile をレビューしている
• コンテナベストプラクティスを実装している