🚨 重要ガイドライン

Windows ファイルパスの要件

必須: Windows でのファイルパスには常にバックスラッシュを使用

Windows で Edit ツールや Write ツールを使用する場合、ファイルパスには必ずバックスラッシュ (\) を使用し、フォワードスラッシュ (/) は使用しないでください。

例:

• ❌ 誤り: D:/repos/project/file.tsx
• ✅ 正解: D:\repos\project\file.tsx

以下に適用されます:

• Edit ツールの file_path パラメータ
• Write ツールの file_path パラメータ
• Windows システムでのすべてのファイル操作

ドキュメンテーションガイドライン

ユーザーが明示的に依頼しない限り、新しいドキュメンテーション ファイルを作成しないでください。

• 優先順位: 新しいドキュメント作成ではなく、既存の README.md ファイルを更新する
• リポジトリの整理: リポジトリのルートを整理状態に保つ - ユーザーが別途リクエストしない限り README.md のみ
• スタイル: ドキュメントは簡潔で直接的かつプロフェッショナルに - AI生成的なトーンは避ける
• ユーザーの好み: ユーザーが明確にドキュメント作成をリクエストした場合のみ追加の .md ファイルを作成

---

Docker ベストプラクティス

このスキルは、コンテナ開発、デプロイメント、運用のあらゆる側面を通じて、現在の Docker ベストプラクティスを提供します。

イメージ ベストプラクティス

ベースイメージの選択

2025年推奨階層:

1. Wolfi/Chainguard (cgr.dev/chainguard/*) - CVE ゼロを目指し、SBOM 込み
2. Alpine (alpine:3.19) - 約 7MB、最小限の攻撃面
3. Distroless (gcr.io/distroless/*) - 約 2MB、シェルなし
4. Slim バリアント (node:20-slim) - 約 70MB、バランス型

重要なルール:

• 常に正確なバージョンタグを指定: node:20.11.0-alpine3.19
• latest は絶対に使用しない (予測不可能で再現性を損なう)
• 信頼できるレジストリの公式イメージを使用
• ベースイメージを実際のニーズに合わせる

Dockerfile の構造

最適なレイヤーの順序 (最小から最頻度の変更順):

1. ベースイメージとシステム依存関係
2. アプリケーション依存関係 (package.json, requirements.txt など)
3. アプリケーションコード
4. 設定とメタデータ

理由: Docker はレイヤーをキャッシュします。コードは変わるが依存関係が変わらない場合、キャッシュされた依存関係レイヤーが再利用され、ビルドが高速化されます。

例:

FROM python:3.12-slim

# 1. システムパッケージ (ほぼ変わらない)
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# 2. 依存関係 (時々変わる)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 3. アプリケーションコード (頻繁に変わる)
COPY . /app
WORKDIR /app

CMD ["python", "app.py"]

マルチステージビルド

マルチステージビルドを使用して、ビルド依存関係とランタイムを分離します:

# ビルドステージ
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 本番ステージ
FROM node:20-alpine AS runtime
WORKDIR /app
# ランタイムに必要なものだけをコピー
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER node
CMD ["node", "dist/server.js"]

メリット:

• より小さな最終イメージ (ビルドツールなし)
• より優れたセキュリティ (攻撃面が少ない)
• より高速なデプロイメント (アップロード/ダウンロードが小さい)

レイヤーの最適化

コマンドを組み合わせて レイヤー数とイメージサイズを削減:

# 悪い例 - 3レイヤー、クリーンアップがサイズを削減しない
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# 良い例 - 1レイヤー、クリーンアップが有効
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

.dockerignore

常に .dockerignore を作成して不要なファイルを除外:

# バージョン管理
.git
.gitignore

# 依存関係
node_modules
__pycache__
*.pyc

# IDE
.vscode
.idea

# OS
.DS_Store
Thumbs.db

# ログ
*.log
logs/

# テスト
coverage/
.nyc_output
*.test.js

# ドキュメント
README.md
docs/

# 環境
.env
.env.local
*.local

コンテナランタイム ベストプラクティス

セキュリティ

docker run \
  # 非 root ユーザーで実行
  --user 1000:1000 \
  # すべてのケーパビリティを削除し、必要なものだけを追加
  --cap-drop=ALL \
  --cap-add=NET_BIND_SERVICE \
  # 読み取り専用ファイルシステム
  --read-only \
  # 一時的に書き込み可能なファイルシステム
  --tmpfs /tmp:noexec,nosuid \
  # 新しい特権なし
  --security-opt="no-new-privileges:true" \
  # リソース制限
  --memory="512m" \
  --cpus="1.0" \
  my-image

リソース管理

本番環境では常にリソース制限を設定:

# docker-compose.yml
services:
  app:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '1.0'
          memory: 512M

ヘルスチェック

長時間実行されるすべてのコンテナにヘルスチェックを実装:

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

または Compose での設定:

services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 40s

ログ

ディスク満杯を防ぐため、適切なログ記録を設定:

services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

または /etc/docker/daemon.json でシステム全体に設定:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

再起動ポリシー

services:
  app:
    # 開発用
    restart: "no"

    # 本番用
    restart: unless-stopped

    # または細かく制御 (Swarm モード)
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

Docker Compose ベストプラクティス

ファイル構造

# バージョンフィールド不要 (Compose v2.40.3+)

services:
  # サービス定義
  web:
    # ...
  api:
    # ...
  database:
    # ...

networks:
  # カスタムネットワーク (推奨)
  frontend:
  backend:
    internal: true

volumes:
  # 名前付きボリューム (永続化に推奨)
  db-data:
  app-data:

configs:
  # 設定ファイル (Swarm モード)
  app-config:
    file: ./config/app.conf

secrets:
  # シークレット (Swarm モード)
  db-password:
    file: ./secrets/db_pass.txt

ネットワーク分離

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # 外部アクセスなし

services:
  web:
    networks:
      - frontend

  api:
    networks:
      - frontend
      - backend

  database:
    networks:
      - backend  # frontend からアクセス不可

環境変数

services:
  app:
    # ファイルから読み込み (非シークレット用推奨)
    env_file:
      - .env

    # サービス固有の変数用インライン
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info

    # Swarm モードシークレット用
    secrets:
      - db_password

重要:

• .env を .gitignore に追加
• テンプレートとして .env.example を提供
• シークレットをバージョン管理にコミットしない

依存関係管理

services:
  api:
    depends_on:
      database:
        condition: service_healthy  # ヘルスチェックを待機
      redis:
        condition: service_started   # 起動を待機

本番環境ベストプラクティス

イメージタグ戦略

# セマンティックバージョニングを使用
my-app:1.2.3
my-app:1.2
my-app:1
my-app:latest

# トレーサビリティのため git commit を含める
my-app:1.2.3-abc123f

# 環境タグ
my-app:1.2.3-production
my-app:1.2.3-staging

シークレット管理

これはしないでください:

# 悪い例 - シークレットがレイヤー履歴に残る
ENV API_KEY=secret123
RUN echo "password" > /app/config

これをしてください:

# Docker シークレット (Swarm) または外部シークレット管理を使用
docker secret create db_password ./password.txt

# またはランタイムにシークレットをマウント
docker run -v /secure/secrets:/run/secrets:ro my-app

# または環境ファイルを使用 (イメージに含めない)
docker run --env-file /secure/.env my-app

監視と可視性

services:
  app:
    # ヘルスチェック
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s

    # 監視ツール用ラベル
    labels:
      - "prometheus.io/scrape=true"
      - "prometheus.io/port=9090"
      - "com.company.team=backend"
      - "com.company.version=1.2.3"

    # ログ
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

バックアップ戦略

# 名前付きボリュームをバックアップ
docker run --rm \
  -v VOLUME_NAME:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/backup-$(date +%Y%m%d).tar.gz -C /data .

# ボリュームを復元
docker run --rm \
  -v VOLUME_NAME:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/backup.tar.gz -C /data

更新戦略

services:
  app:
    # Swarm モード用 - ローリングアップデート
    deploy:
      replicas: 3
      update_config:
        parallelism: 1        # 1 つずつ更新
        delay: 10s            # 更新間に 10秒待機
        failure_action: rollback
        monitor: 60s
      rollback_config:
        parallelism: 1
        delay: 5s

プラットフォーム固有のベストプラクティス

Linux

• ユーザー名前空間リマッピングで追加セキュリティを実現
• ネイティブパフォーマンス上の利点を活用
• 最小限のイメージには Alpine を使用
• SELinux/AppArmor プロファイルを設定
• systemd を Docker デーモン管理に使用

// /etc/docker/daemon.json
{
  "userns-remap": "default",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "live-restore": true
}

macOS

• Docker Desktop で十分なリソースを割り当て
• バインドマウントに :delegated または :cached を使用
• ARM (M1/M2) 用のマルチプラットフォームビルドを検討
• ファイル共有を必要なディレクトリのみに制限

# macOS でのボリュームパフォーマンス向上
volumes:
  - ./src:/app/src:delegated  # ホスト書き込みは遅延
  - ./build:/app/build:cached  # コンテナ書き込みがキャッシュされる

Windows

• コンテナタイプを選択: Windows または Linux
• パスではフォワードスラッシュを使用
• Docker Desktop でドライブが共有されていることを確認
• 行末の違い (CRLF vs LF) に注意
• パフォーマンスのため WSL2 バックエンドを検討

# Windows 互換パス
volumes:
  - C:/Users/name/app:/app  # フォワードスラッシュが動作
  # または
  - C:\Users\name\app:/app  # バックスラッシュは YAML でエスケープが必要

パフォーマンス ベストプラクティス

ビルドパフォーマンス

# BuildKit を使用 (より高速、キャッシュの改善)
export DOCKER_BUILDKIT=1

# キャッシュマウントを使用
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# 依存関係にバインドマウントを使用
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci

イメージサイズ

• マルチステージビルドを使用
• 最小限のベースイメージを選択
• 同じレイヤーでクリーンアップ
• .dockerignore を使用
• ビルド依存関係を削除

# インストールとクリーンアップを 1 レイヤーで
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    package1 \
    package2 && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

ランタイムパフォーマンス

# exec フォーム (シェルオーバーヘッドなし)
CMD ["node", "server.js"]  # 良い
# vs
CMD node server.js         # 悪い - シェルが起動される

# シグナルを最適化
STOPSIGNAL SIGTERM

# 非 root ユーザーで実行 (やや高速化、セキュリティも向上)
USER appuser

セキュリティベストプラクティスまとめ

イメージセキュリティ:

• 公式で最小限のベースイメージを使用
• 脆弱性をスキャン (Docker Scout, Trivy)
• レイヤーにシークレットを含めない
• 非 root ユーザーで実行
• イメージを最新に保つ

ランタイムセキュリティ:

• ケーパビリティを削除
• 読み取り専用ファイルシステムを使用
• リソース制限を設定
• セキュリティオプションを有効化
• ネットワークを分離
• シークレット管理を使用

コンプライアンス:

• CIS Docker Benchmark に従う
• CI/CD でコンテナスキャンを実装
• 署名済みイメージを使用 (Docker Content Trust)
• 監査ログを保持
• 定期的なセキュリティレビュー

避けるべき一般的なアンチパターン

❌ しないでください:

• root で実行
• --privileged を使用
• Docker ソケットをマウント
• latest タグを使用
• シークレットをハードコード
• ヘルスチェックをスキップ
• リソース制限を無視
• 巨大なベースイメージを使用
• 脆弱性スキャンをスキップ
• 不要なポートを公開
• 非効率なレイヤーキャッシュ
• シークレットを Git にコミット

✅ してください:

• 非 root で実行
• 最小限のケーパビリティを使用
• コンテナを分離
• バージョンでタグ付け
• シークレット管理を使用
• ヘルスチェックを実装
• リソース制限を設定
• 最小限のイメージを使用
• 定期的にスキャン
• 最小特権の原則を適用
• ビルドキャッシュを最適化
• .env.example テンプレートを使用

本番対応イメージのチェックリスト

• 公式で、バージョン指定された、最小限のイメージをベース化
• マルチステージビルド (該当する場合)
• 非 root ユーザーで実行
• レイヤーにシークレットなし
• .dockerignore を設定
• 脆弱性スキャンに合格
• ヘルスチェックを実装
• 適切なラベリング (バージョン、説明など)
• 効率的なレイヤーキャッシング
• リソース制限を定義
• ログを設定
• シグナル処理を正しく実装
• セキュリティオプションを設定
• ドキュメントが完成
• ターゲットプラットフォーム上でテスト

このスキルは現在の Docker ベストプラクティスを表します。最新の推奨事項については常に公式ドキュメントを確認してください。Docker は継続的に進化しています。