docker

Docker

セキュリティを最優先したデフォルト設定による、本番環境に対応した Docker コンテナ化です。

---

リソースの検出と適応

Dockerfile／Compose を生成する前に、環境を検出します：

# Detect host machine memory
sysctl -n hw.memsize 2>/dev/null | awk '{print $0/1024/1024/1024 " GB"}' || \
  grep MemTotal /proc/meminfo | awk '{print $2/1024/1024 " GB"}'

# Detect Docker allocated resources
docker info --format 'Memory: {{.MemTotal}}, CPUs: {{.NCPU}}'

# Detect available disk space
docker system df

検出結果に基づいて設定を適応させます：

検出された Docker メモリ	プロファイル	ビルドメモリ	コンテナの制限
< 4GB	制約あり	1GB	256Mi
4-8GB	最小	2GB	512Mi
8-12GB	標準	4GB	1Gi
> 12GB	拡張	8GB	2Gi

エージェントの動作

1. compose.yaml の生成前に Docker リソースを検出します
2. 利用可能なメモリに合わせてリソース制限を調整します
3. リソース不足でビルドに失敗する可能性がある場合は警告します
4. 安全な制限を計算します：docker_memory * 0.6 / container_count

適応型 Compose テンプレート

制約あり（Docker が 4GB 未満）：

services:
  app:
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.25'
    build:
      args:
        - BUILDKIT_STEP_LOG_MAX_SIZE=10000000

⚠️ エージェントは次のように警告する必要があります：「Docker のメモリが不足しています。マルチステージビルドが失敗する可能性があります。」

標準（Docker が 4-8GB）：

services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 256M

拡張（Docker が 8GB 超）：

services:
  app:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
        reservations:
          memory: 512M

ビルド前の検証

docker build を実行する前に、エージェントは次を確認する必要があります：

# Check available memory
docker info --format '{{.MemTotal}}' | awk '{if ($1 < 4000000000) print "WARNING: Low memory"}'

制約がある場合は、--memory フラグを使用し、ビルドに失敗する可能性があることをユーザーに警告します。

---

このスキルでできること

分析と検出：

• ランタイム、フレームワーク、バージョン、エントリーポイントを自動検出します（質問はしません）
• .env ファイルをスキャンし、シークレット、ビルド引数、ランタイム設定に分類します
• ネイティブ依存関係を検出し、適切なビルド依存関係を生成します
• 不足している設定（Next.js の standalone 設定、ヘルスエンドポイントなど）を特定します

生成：

• プロジェクトの構成に合わせたマルチステージ Dockerfile を作成します
• セキュリティのデフォルト設定（非 root、読み取り専用、リソース制限）を備えた compose.yaml を生成します
• 不足している場合はヘルスエンドポイントを追加します
• 設定の問題を修正します（Next.js に output: 'standalone' を追加するなど）

検証：

• 提供前に開発用と本番用の両方のターゲットをビルドします
• ヘルスエンドポイントが動作することを検証します
• 本番環境で非 root ユーザーが使用されていることを確認します
• イメージに漏えいする可能性のあるシークレットについて警告します
• イメージサイズを報告します

セキュリティ：

• シークレットをイメージに埋め込むことはありません
• デフォルトで非 root ユーザーを使用します
• 攻撃対象領域を最小化します（マルチステージビルド）
• バージョンを固定します（:latest は使用しません）
• セキュリティスキャンコマンドを含みます

このスキルでできないこと

• Kubernetes マニフェストの生成（専用の k8s スキルを使用してください）
• Helm チャートの作成（専用の helm スキルを使用してください）
• Bun／Deno への対応（専用のスキルを使用してください）
• テンプレートをカスタマイズせずにそのままコピーすること

---

実装前

実装を確実に成功させるため、コンテキストを収集します：

ソース	収集する情報
コードベース	パッケージファイル、既存の Dockerfile、.env のパターン
会話	開発用か本番用か、ベースイメージの希望
スキルの参照情報	フレームワークのパターン、マルチステージビルド、セキュリティ
ユーザーのガイドライン	レジストリの規約、命名規則

---

必要な確認事項

自動検出できない場合は質問します：

質問	質問するタイミング
対象環境	「開発用と本番用のどちらをビルドしますか？」
ベースイメージの希望	「標準の slim イメージと、エンタープライズ向けに強化されたイメージのどちらを使用しますか？」
既存の Docker ファイル	「既存の Dockerfile を拡張しますか、それとも新規作成しますか？」
対象レジストリ	「ローカルでのみ使用しますか、それともレジストリにプッシュしますか？」

---

ランタイムの検出

ファイルの有無	ランタイム	パッケージマネージャー
requirements.txt、pyproject.toml、uv.lock	Python	pip/uv
pnpm-lock.yaml	Node.js	pnpm
yarn.lock	Node.js	yarn
package-lock.json	Node.js	npm

---

自動検出（質問せず、ファイルから検出してください）

Python

対象	検出元
Python のバージョン	pyproject.toml（requires-python）、.python-version、runtime.txt
フレームワーク	コード内のインポート（from fastapi、from flask、import django）
パッケージマネージャー	uv.lock → uv、poetry.lock → poetry、それ以外は pip
ネイティブ依存関係	requirements をスキャン：psycopg2、cryptography、numpy、pillow
アプリのエントリーポイント	app = FastAPI()、app = Flask()、または manage.py を検索

Node.js

対象	検出元
Node のバージョン	.nvmrc、.node-version、package.json（engines.node）
フレームワーク	package.json の依存関係（next、express、@nestjs/core）
パッケージマネージャー	pnpm-lock.yaml → pnpm、yarn.lock → yarn、それ以外は npm
出力タイプ	Next.js：next.config.js で output: 'standalone' を確認

問題の自動修正

問題	対応
Next.js に output: 'standalone' がない	next.config.js に追加する
ヘルスエンドポイントが見つからない	/health/live と /health/ready を作成する
uv を使用しているが uv.lock がない	まず uv lock を実行する
pyproject.toml があるがビルドシステムがない	uv pip install -r pyproject.toml を使用する

---

ワークフロー

1. SCAN PROJECT
   - Detect runtime, framework, version, entrypoint
   - Find dependency files, native deps
   - Locate existing Docker files (don't blindly overwrite)
         ↓
2. ANALYZE ENVIRONMENT
   - Scan all .env* files
   - Classify: SECRET (never bake) / BUILD_ARG / RUNTIME
   - Flag security issues
         ↓
3. FIX CONFIGURATION
   - Add Next.js `output: 'standalone'` if missing
   - Create health endpoints if missing
   - Generate .env.example with safe placeholders
         ↓
4. GENERATE FILES
   - Dockerfile (customized CMD, paths, build deps)
   - .dockerignore (excludes .env, secrets)
   - compose.yaml (with security defaults)
         ↓
5. VALIDATE & TEST
   - docker build --target dev -t app:dev .
   - docker build --target production -t app:prod .
   - Test health endpoints
   - Verify non-root user
   - Report image size
         ↓
6. DELIVER WITH CONTEXT
   - All files with explanations
   - Security scan command
   - Any warnings about secrets
   - Rollback instructions if replacing existing

本当に曖昧な場合にのみ確認してください（例：モノレポ内に複数のアプリがある場合、設定が競合している場合）

---

ベースイメージの選択基準

選択肢	使用する場面	トレードオフ
Slim {runtime}:X-slim	一般的な本番環境（デフォルト）	どこでも動作し、認証不要
DHI dhi.io/{runtime}:X	SOC2/HIPAA、エンタープライズ	docker login dhi.io が必要
Alpine {runtime}:X-alpine	最小サイズ	ネイティブ依存関係で musl の問題が発生する可能性

デフォルト：Slim（認証なしでどこでも動作）

---

ステージ構成

deps/base  → Install dependencies (cached layer)
    ↓
builder    → Build/compile application
    ↓
dev        → Hot-reload, volume mounts (--target dev)
    ↓
production → Minimal DHI runtime (--target production)

ビルドコマンド

docker build --target dev -t myapp:dev .
docker build --target production -t myapp:prod .

---

Python のパターン

フレームワークの CMD

フレームワーク	開発	本番
FastAPI	uvicorn app.main:app --reload	uvicorn app.main:app --workers 4
Flask	flask run --debug	gunicorn -w 4 app:app
Django	python manage.py runserver	gunicorn -w 4 project.wsgi

キャッシュマウント（uv/pip）

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=cache,target=/root/.cache/pip \
    uv pip install -r requirements.txt

グレースフルシャットダウン（FastAPI）

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield  # startup
    # shutdown logic here

---

Node.js のパターン

フレームワークのビルド

フレームワーク	ビルド	出力
Next.js	next build	.next/standalone
Express	tsc	dist/
NestJS	nest build	dist/

キャッシュマウント

# pnpm
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile

# npm
RUN --mount=type=cache,target=/root/.npm npm ci

# yarn
RUN --mount=type=cache,target=/usr/local/share/.cache/yarn \
    yarn install --frozen-lockfile

グレースフルシャットダウン（Node.js）

process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

---

セキュリティチェックリスト

提出前に、次の項目を確認してください。

• 本番ステージで root 以外の USER を使用している
• Dockerfile またはイメージレイヤーにシークレットがない
• .dockerignore で .env、.git、シークレットを除外している
• マルチステージビルドでビルドツールとランタイムを分離している
• DHI または強化されたベースイメージを使用している
• HEALTHCHECK 命令が定義されている
• 本番ステージでパッケージをインストールしていない
• シークレットを実行時の環境変数またはマウントされたファイルで渡している

---

出力ファイル

ファイル	用途
Dockerfile	マルチステージ、マルチターゲットのビルド
.dockerignore	機密ファイルや不要なファイルを除外
compose.yaml	ローカル開発スタック
health.py / ヘルスエンドポイント	フレームワーク固有のヘルスチェック

---

参考ファイル

必ず最初に読む

ファイル	用途
references/env-analysis.md	重要：シークレットの検出、.env の分類
references/production-checklist.md	重要：提出前の検証

フレームワーク固有

ファイル	読むタイミング
references/python/fastapi.md	FastAPI：uvicorn、lifespan
references/python/flask.md	Flask：gunicorn、blueprints
references/python/django.md	Django：gunicorn、middleware
references/python/native-deps.md	psycopg2、cryptography などの検出
references/node/nextjs.md	Next.js：standalone、ISR
references/node/package-managers.md	npm/yarn/pnpm のキャッシュ

任意

ファイル	読むタイミング
references/docker-hardened-images.md	エンタープライズ向けのセキュリティ（DHI）が必要な場合
references/multi-stage-builds.md	複雑なビルドパターン

テンプレート（参照パターン）

templates/ 内のテンプレートは、コピーしてそのまま使うファイルではなく、参照パターンです。

エージェントは次のことを行う必要があります：

1. 構造を理解するためにテンプレートを読む
2. 実際のプロジェクトに合わせてパス、CMD、ステージをカスタマイズする
3. 正しいエントリーポイント（例：src.app.main:app）を含む Dockerfile を生成する
4. 「# フレームワークに合わせて変更」のようなプレースホルダーコメントを絶対に出力しない

カスタマイズ例：

# Template says:
CMD ["uvicorn", "app.main:app", ...]

# Agent detects app at src/api/main.py, generates:
CMD ["uvicorn", "src.api.main:app", ...]