docker

Docker

概要

Docker は、環境を問わず一貫して実行できる、分離されたコンテナにアプリケーションをパッケージ化します。Dockerfile でイメージのビルド手順を定義し、Compose で複数コンテナのサービスをオーケストレーションします。また、本番環境向けのパターンを使うことで、小さく、安全で、高性能なイメージを実現できます。

使用する場面： アプリケーションのコンテナ化、再現可能な開発環境の作成、複数サービスから成るスタックのオーケストレーション、コンテナプラットフォーム（ECS、Kubernetes、Fly.io、Railway、Coolify）へのデプロイ。

使用しない場面： バックエンドのないシンプルな静的サイト（CDN デプロイを使用）、単一バイナリの CLI ツール（バイナリを配布）、または対象プラットフォームにネイティブのビルドパック（Heroku、Vercel）があり、コンテナを制御する必要がない場合。

クイックリファレンス

パターン	アプローチ	ポイント
マルチステージビルド	builder と production のステージを分離	イメージサイズを 80% 以上削減し、本番環境に開発用依存関係を含めない
レイヤーキャッシュ	最初にロックファイルをコピーしてインストールし、その後ソースをコピー	ビルド間で依存関係のレイヤーをキャッシュ
非 root ユーザー	最終ステージで RUN adduser + USER	本番用コンテナを root で実行しない
ヘルスチェック	HEALTHCHECK CMD curl または node/python のチェック	障害時にオーケストレーターが再起動できる
.dockerignore	node_modules、.git、.env を除外	ビルドコンテキストを小さくし、ビルドを高速化
Compose サービス	サービス定義を含む compose.yaml	1 つのコマンドで開発環境を構築
Compose オーバーライド	本番設定を記述した compose.prod.yaml	重複を避けながら環境ごとの設定を管理
名前付きボリューム	Compose で永続データ用の volumes: を指定	コンテナを再作成してもデータを保持
ビルドキャッシュのマウント	RUN --mount=type=cache,target=/root/.npm	ビルド間でキャッシュを保持
ビルド時のシークレット	RUN --mount=type=secret,id=token	イメージのレイヤーにシークレットを含めない
イメージのバージョン固定	メジャー・マイナーバージョンまたはダイジェストを指定	再現可能なビルドを実現し、予期しない破損を防止
コンテナネットワーク	サービスディスカバリーにカスタムブリッジネットワークを使用	コンテナ同士がサービス名で名前解決できる
Compose watch	同期／再ビルドのアクションを使った develop.watch	ボリュームマウントなしでライブリロード
初期化プロセス	--init フラグまたは tini エントリーポイント	シグナルを適切に処理し、ゾンビプロセスを回収
マルチプラットフォーム	docker buildx build --platform	ARM（Apple Silicon、Graviton）と x86 を 1 つのイメージで対応
モノレポのプルーニング	turbo prune app --docker	ワークスペースの依存関係からビルドコンテキストを最小化
CI のレイヤーキャッシュ	GHA またはレジストリで cache-from/cache-to を使用	CI パイプラインでのフルビルドを回避
コンテナのデバッグ	docker exec、docker logs、dive	実行中のコンテナとイメージのレイヤーを調査

よくある間違い

間違い	正しいパターン
本番用イメージに開発用依存関係をインストールする	マルチステージビルドを使用します。ビルダーでインストールし、成果物を実行時用ステージにコピーします
依存関係をインストールする前にソースをコピーする	まずロックファイルをコピーし、npm ciを実行してからソースをコピーし、キャッシュを再利用します
本番環境でrootとして実行する	非rootユーザーを作成し、最終ステージでUSERディレクティブを指定します
DockerfileやENVにシークレットをハードコーディングする	ビルドシークレット（--mount=type=secret）または実行時の環境変数を使用します
ベースイメージにlatestタグを使用する	特定のバージョン（node:24-alpine）を指定します
.dockerignoreファイルがない	node_modules、.git、.env、ビルド成果物を除外します
npm ciではなくnpm installを使用する	再現性のあるロックファイルベースのインストールにはnpm ciを使用します
HEALTHCHECKがない	オーケストレーターとの連携のためにヘルスチェックを追加します
ベースイメージのサイズが大きい（node:24）	イメージを小さくするためにAlpineバリアント（node:24-alpine）を使用します
Composeでの.envファイルの優先順位を考慮しない	Composeのenvironment:は.envファイルの値を上書きします
1つのサービスのためにモノレポ全体をビルドする	ビルドコンテキストを最小限にするためにturbo prune --dockerを使用します
CIでレイヤーキャッシュを使用しない	GHAまたはレジストリバックエンドでcache-from/cache-toを使用します
ARMへのデプロイ時にx86用のみビルドする	--platform linux/amd64,linux/arm64を指定してdocker buildxを使用します

委任

• Dockerfileのレビュー：Taskエージェントを使用して、Dockerfileのサイズ、セキュリティ、キャッシュを監査します
• Composeの調査：Exploreエージェントを使用して、既存のDocker構成を確認します
• アーキテクチャの決定：コンテナオーケストレーション戦略にはPlanエージェントを使用します

ci-cd-architectureスキルが利用可能な場合は、CI/CDパイプラインとデプロイ戦略を委任してください。 application-securityスキルが利用可能な場合は、コンテナのセキュリティスキャンと強化レビューを委任してください。

参考資料

• Dockerfileのパターン：マルチステージビルド、レイヤーキャッシュ、イメージの最適化
• Compose：サービス、ネットワーク、ボリューム、環境の管理
• セキュリティ：非rootユーザー、シークレット、スキャン、本番環境向けの強化
• Buildx：ARMおよびx86向けのマルチプラットフォームビルド
• CI：GitHub Actionsのキャッシュ、レジストリへのプッシュ、自動ビルド
• モノレポ：Turborepo prune、pnpmワークスペース、選択的ビルド
• デバッグ：ログ、exec、inspect、レイヤー分析、ネットワークのトラブルシューティング