docker-development

Docker 開発

基本原則

1. 最小限 — Alpine/distroless、マルチステージ
2. セキュア — 非 root の USER、レイヤーにシークレットを含めない、バージョンを固定
3. テスト可能 — エントリーポイントのバイパス、DNS のモック
4. キャッシュ効率 — 依存関係を先に処理し、同じレイヤー内でクリーンアップ

クイックリファレンス

マルチステージビルド（Node.js）

FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM node:24-alpine
RUN addgroup -g 1001 app && adduser -u 1001 -G app -D app
USER app
COPY --from=builder /app .
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

マルチステージビルド（Go — scratch/distroless）

FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server .

FROM gcr.io/distroless/static:nonroot
COPY --from=builder /app/server /server
CMD ["/server"]

レイヤーの最適化

RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

ビルドキャッシュ：依存関係のファイルを先にコピー

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

マニフェストをソースより先にコピーすると、インストールレイヤーのキャッシュが保持されます。

BuildKit シークレット

RUN --mount=type=secret,id=ssh_key,dst=/root/.ssh/id_rsa git clone [email protected]:org/repo.git

ARG は docker history と SLSA provenance に漏えいします — references/build-secret-leaks.md

Docker Bake（マルチプラットフォーム）

target "app" {
  platforms = ["linux/amd64", "linux/arm64"]
}

CI ビルドは Bake と netresearch/.github/.github/workflows/build-container-bake.yml@main を経由します。イメージは 1 つでも複数でも構いません。再利用可能なワークフローがターゲットごとに GHA キャッシュを追加するため、HCL ではキャッシュを宣言しません。定期的な再ビルドでは cache: false を渡します — references/bake-ci-cache.md

セキュリティ上のアンチパターン

アンチパターン	修正方法
FROM image:latest	バージョンを固定します：image:1.2.3-alpine
USER ディレクティブがない	adduser + USER appuser
chmod 777	特定の権限を指定します：chmod 550
compose の privileged: true	削除するか、特定の cap_add を使用します
volumes: [/:/host]	必要なパスのみをマウントします
ports: ["0.0.0.0:3000:3000"]	127.0.0.1:3000:3000 にバインドします
ENV DB_PASSWORD=secret	--mount=type=secret または compose のシークレットを使用します

CI テストでの注意点

1. エントリーポイントをバイパスする：docker run --rm --entrypoint php myimage -v
2. 上流 DNS をモックする：docker run --rm --add-host backend:127.0.0.1 nginx-image nginx -t
3. Compose の検証：docker compose config の前に cp .env.example .env を実行します
4. シークレットスキャン：.env.example、README、ドキュメントを除外します
5. root 所有のアーティファクト：ディレクトリをバインドマウントします（EACCES）— references/bind-mount-ownership.md

.dockerignore

除外対象：.git、node_modules／vendor、.env*、*.pem、*.key

Compose の基本事項

• 起動順序：depends_on.condition: service_healthy + healthcheck の start_period
• networks.internal: true でデータベースを隔離します
• profiles: [debug]：--profile debug を指定した場合のみ起動します。down と --remove-orphans は無効なプロファイルのコンテナーを対象にしないため、停止対象のまま有効化をやめたサービスは動作し続けます — docker compose --profile '*' down、または docker compose down <service>（references/compose-runtime-lifecycle.md）
• ログドライバーはデフォルトでブロッキング動作です：リモートエンドポイント（awslogs など）が停止すると、アプリの書き込みも停止します。mode: non-blocking + max-buffer-size を指定すると、代わりにログ行を破棄します。これで保護されるのは実行中のコンテナーのみです（references/compose-runtime-lifecycle.md）
• イメージ参照の共有：ファイルごとに、トップレベルの拡張フィールドとアンカーで一度だけ定義します — x-app-image: &app-image registry/app:${APP_IMAGE_VERSION:-85}。サービスでは image: *app-image を使用します。このフィールドは services: より上に置く必要があります — エイリアスが有効なのは、ドキュメント内でアンカーの後にある場合のみです。:- のデフォルト値は、未設定の変数と空の変数の両方に適用されます（タグを省略すると、何も通知されないまま :latest に解決されます）。アンカーはファイル内でのみ有効です。オーバーレイファイルごとに、それぞれアンカーを定義する必要があります。両方の方法で確認します：APP_IMAGE_VERSION= docker compose config と、オーバーライドを指定した場合

参考資料

• references/bake-ci-cache.md -- 共通の Bake 再利用可能ワークフロー、Compose ファイルと同じ場所にある -f docker-bake.hcl、ターゲットごとの GHA キャッシュスコープ、キャッシュを使わずに定期的に再ビルドしながらキャッシュには書き込む方法、bake-action のディレクトリにあるヘルパーステップ
• references/ci-testing.md -- Docker イメージの CI テストパターン、-c 文字列での busybox の sh と bash の違い、docker compose run を timeout で囲むと PID 1 がシグナルを無視した場合にコンテナが実行中のままになること
• references/dind-testing-patterns.md -- Docker-in-Docker のテストパターン
• references/bind-mount-ownership.md -- bind mount の成果物が root 所有になる問題、親パスにある tmpfs がその下のボリュームを隠す問題
• references/gpg-verification.md -- gpgv のパターン、古い keybox ロック
• references/registry-catalogue-and-pin-rot.md -- カタログのプローブ、ピンの陳腐化
• references/build-secret-leaks.md -- provenance 内の ARG
• references/php-fpm-worker-starvation.md -- keepalive が php-fpm を占有する問題
• references/engine-and-image-upgrades.md -- MinAPIVersion によってソケット読み取りサイドカーが遮断される問題、プローブコンテナによるアップグレードチェック、ベースイメージの USER の変更、PHP 8.5 で OPcache がコアに組み込まれたこと
• references/database-container-readiness.md -- シード済み DB イメージが ready for connections を2回ログに出すこと、ログではなくシードデータを検証すること
• references/compose-runtime-lifecycle.md -- 無効なプロファイルのコンテナが down と up --remove-orphans の後も残ること、ブロッキングとノンブロッキングのログ配信、およびノンブロッキングでは防げないこと
• references/image-ca-trust.md -- CA が侵害された後に、公開イメージの ca-certificates のバージョンとルート証明書のサブジェクトを確認すること、バンドル内の CA 名を grep しても必ず0が返ること