specsfy-specialist-docker

Docker

使用するタイミング

• Dockerfile、docker-compose.yml、.dockerignore、タグ／レジストリのポリシーを記述またはレビューするとき、あるいはコンテナーがビルドできない、起動しない、ヘルスチェックに応答しない問題をデバッグするときに使用します。
• イメージサイズの縮小、レイヤーに漏えいしたシークレットの除去、SIGTERM を正しく受信しないプロセスの修正にも使用します。
• マルチノードのオーケストレーション、レプリカを使ったロールアウト、クラスターシークレット、オーバーレイネットワークには使用せず、その場合は $specsfy-specialist-docker-swarm を使用します。ここでの Docker Compose はローカル／CI 環境向けであり、マルチホストの本番トポロジー向けではありません。
• サプライチェーン（SBOM、来歴、脆弱な依存関係）のレビューでは $specsfy-specialist-application-security と、ビルド内容そのものについてはプロジェクトの言語／フレームワークのスキルと組み合わせます。

手順

1. 変更を提案する前に、対象アーキテクチャ（amd64／arm64）、ベースランタイム（言語、バージョン）、実際のビルドコンテキスト、想定される実行契約（変数、ポート、ボリューム）を確認します。
2. Dockerfile、.dockerignore、docker-compose.yml、プロジェクトで現在使用されているイメージ／タグのポリシーを調査します。
3. イメージがリリースまたはデプロイに含まれる場合は、この手順を $specsfy-specialist-deploy のもとで実施します。$specsfy-specialist-versioning から提供されたバージョンを使用し、docker-tag で参照を生成して、verify-docker-tag が差異を指摘した場合は拒否します。
4. ステージを明確にしてビルド依存関係とランタイム依存関係を分離します（multi-stage build）。最終イメージには、本番環境で実行されないコンパイラー、パッケージキャッシュ、ソースを含めないでください。
5. アーティファクトを再現可能な方法で固定し（ロックファイル、固定バージョンまたはダイジェストによるベースイメージ）、ビルドコンテキストと変更可能なレイヤーを減らします。
6. root 以外のユーザーでプロセスを実行し、権限を制限し（cap_drop、--privileged を使わない）、イメージにシークレットを埋め込まないでください。
7. ヘルスチェック、シグナル処理（SIGTERM、SIGINT）、ボリューム、ネットワーク、外部設定（env、マウントされたファイル）を明示的に定義します。
8. イメージをビルドして脆弱性をスキャンし、本番環境での実行方法とまったく同じ条件（同じユーザー、同じ変数）でテストします。

ベストプラクティス

• ネイティブ拡張を含むアプリケーションでは、コンパイルをファミリーごとに独立したステージに分割します。Redis、メディア、アプリケーションサーバーの変更によって、ツールチェーン全体を無効にする必要はありません。
• 複数のサービスで同じコードを使う場合は、単一のイメージを作成し、エントリーポイントで HTTP、スケジューラー、キュー、WebSocket などのプロセスモードを選択します。各モードには、その役割に適したヘルスチェック、シグナル処理、書き込み方法を設定します。
• SemVer とコミットの不変な参照を公開し、どちらもまだ存在しないことを確認して、デプロイで使用したダイジェストを記録します。Git タグの公開は、イメージがレジストリで利用可能になってから行います。
• フレームワークのキャッシュがランタイムで提供される設定に依存する場合は、エントリーポイントで生成します。異なる値を使う環境に、ビルド中に作成した設定キャッシュを持ち込まないでください。
• 互換性のある最小限のベースイメージを優先します（スタックが対応していれば slim／alpine）。バイト単位での再現性が自動的なパッチ更新より重要な場合は、ダイジェスト（@sha256:...）で固定します。
• キャッシュを最大限活用できるように命令を並べます（ソースコードより先に依存関係）。ただし、依存関係の更新を妨げないようにします。COPY package*.json の後に RUN install を実行してから COPY . . を行うと、コード変更時にもインストールをキャッシュしつつ、インストールされるバージョンを固定せずに済みます。
• ビルド時の認証情報やパッケージマネージャーのキャッシュには、BuildKit のシークレットおよびキャッシュマウント（RUN --mount=type=secret、--mount=type=cache）を使います。シークレットに ARG／ENV は決して使わないでください。どちらも最終イメージのレイヤー履歴に残ります。
• .dockerignore を使わずにリポジトリ全体をコピーしないでください。.git、node_modules、ローカルのビルド成果物、.env がビルドコンテキストに漏れ、イメージのサイズやビルド時間が増加します。
• メインプロセスを PID 1 として扱うことを意識します。シグナルを正しく受け取るには、exec 形式の ENTRYPOINT（シェル形式の CMD cmd args ではなく ["cmd"]）を使うか、プロセスがゾンビを回収しない場合は最小限の init（--init／tini）を使います。
• 永続データはコンテナの書き込み可能レイヤーの外に保持します（名前付きボリュームまたはバインドマウント）。コンテナのレイヤー内のデータは、コンテナとともに失われます。
• ワークロードが対応する場合は、リソース制限と読み取り専用のルートファイルシステム（--read-only と、書き込みが必要な箇所への明示的なボリューム）を設定し、ランタイムの攻撃対象領域を縮小します。

アンチパターン

• 本番環境で唯一のタグとして latest を使うこと。再現性がなく、コンテナを調べないと実行中のコードを特定できません。
• ローカルファイルのコピーに COPY ではなく ADD を使うこと。ADD はファイルの展開や URL の取得も行うため、暗黙の動作となり、後から Dockerfile を読む人を戸惑わせます。
• トラフィックを処理するイメージで、USER を指定せず暗黙に USER root のままにすること。コンテナ内で侵害されたプロセスがコンテナの root 権限を持ち、アプリケーションの脆弱性による影響が拡大します。
• マルチステージビルドを使わず、コンパイラーやヘッダーなどのビルド依存関係を最終レイヤーにインストールすること。ランタイムでメリットがないままイメージが肥大化し、スキャン対象となる脆弱性の範囲も広がります。
• クリティカルな依存関係（データベース、キュー）を確認せず、「プロセスがポートで待ち受けている」ことだけを調べるヘルスチェック。実際にはリクエストを処理できなくても、オーケストレーターはコンテナを正常と判断します。

検証

• キャッシュなしのクリーンビルド（--no-cache）と、キャッシュを使った増分ビルドの両方で、機能的に同等のイメージが生成されることを確認します。
• 開発用のデフォルト設定だけでなく、対象環境で実際に使用するユーザー、アーキテクチャ、環境変数でイメージを実行します。
• ヘルスチェック、docker stop（設定した猶予時間内での正常なシャットダウン）、公開ポート、ボリューム、内部 DNS 解決、宣言された依存関係が利用できない場合の挙動を検証します。
• SBOM を生成し、プロジェクトで利用可能な脆弱性スキャナーを実行して、最終イメージのサイズとレイヤー数を確認します。
• スキャナーを実行していないのにイメージを「安全」と宣言したり、同じコミットからのビルドを繰り返して機能的に同じ結果が得られていないのに「再現可能」と宣言したりしないでください。

関連するスキル

• $specsfy-specialist-server-report は、Ansible による読み取り専用の収集で、ホストごとのレポートにログ、サービス、ディスク使用量をまとめます。

• $specsfy-specialist-deploy は完全なデリバリーを調整します。このスキルが扱うのはイメージと開発用 Compose のみです。

• $specsfy-specialist-versioning は SEMVER を準備し、公開前にイメージの識別情報を確認します。

• $specsfy-specialist-docker-swarm は、マルチノードオーケストレーション、クラスターシークレット、オーバーレイネットワーク、サービスのロールアウトを扱います。このスペシャリストが対象とするのはイメージとローカル Compose であり、本番クラスターではありません。

• $specsfy-specialist-application-security は、サプライチェーン（SBOM、来歴、依存関係の CVE）と、コンテナ以外のセキュリティ強化を扱います。

• $specsfy-specialist-observability は、コンテナ内のプロセスのログ、メトリクス、トレーシングを扱います。

• $specsfy-specialist-postgres、$specsfy-specialist-redis は、イメージ／サービス内で動作するもの（スキーマ設計、データ構造、永続化）を扱います。このスキルが扱うのはパッケージング（公式イメージ、ボリューム、ヘルスチェック）であり、データベース／キャッシュ内部の設計判断ではありません。

• プロジェクトのローカル環境が Docker 上の Supabase CLI によってオーケストレーションされている場合は、$specsfy-specialist-supabase を使用します。

• $specsfy-specialist-laravel は、パッケージ化されたアプリケーションの実行時の契約（キューワーカー、スケジューラー、想定される環境変数）を扱います。

• $specsfy-specialist-debian-server は、イメージを実行するホストのカーネル、ファイルシステム、systemd、APT、Docker Engine を扱います。

ビルド、Compose、セキュリティ、サプライチェーン、運用については、references/standards.md をお読みください。