docker-project-foundations

Docker プロジェクトの基礎

概要

このスキルでは、プロジェクトをゼロから Docker 化する方法を説明します。Docker の初期ファイル一式の作成、適切なレイアウトの選択、ホストへのインストールよりコンテナ化された依存関係を優先することに重点を置いています。

このスキルを使う場合

次の場合に、このスキルを有効にしてください。

• ユーザーがプロジェクトのセットアップ、初期化、または Docker 化を依頼した場合
• プロジェクトに初期の Dockerfile、compose.yaml、または .dockerignore が必要で、まだ存在しない場合
• ユーザーがプロジェクトにサービス依存関係（データベース、キャッシュ、メッセージキュー）を追加したい場合
• ユーザーがプロジェクトをローカルで実行または開発する方法を尋ね、Docker が利用可能な場合

このスキルを使わない場合

次の場合は、このスキルを使わないでください。

• ユーザーが Docker を使わないことを明示的に希望している場合
• プロジェクトに成熟した Docker 構成がすでにあり、小規模な編集だけが必要な場合
• 主なタスクが既存の Dockerfile の最適化である場合
• 主なタスクが既存の Compose スタックの編集またはデバッグである場合

基本的なガイダンス

必ず次の 3 つのファイルを作成する

プロジェクトを Docker 化する場合は、必ず次の 3 つすべてを作成してください。

1. .dockerignore — 初回ビルドのコンテキストを小さく安全に保つため、最初に作成します。参考として assets/dockerignore-example を参照してください。
2. Dockerfile — プロジェクトをビルドして実行できる、動作するスターターイメージ定義を作成します。assets/Dockerfile.simple を参照してください。
3. compose.yaml — アプリケーションサービスと必要な依存関係を含む、ローカル開発用スタックを作成します。assets/compose-dev.yaml を参照してください。

npm レジストリの認証情報

• .dockerignore に **/.npmrc を指定して、すべての階層にある .npmrc を除外してください。そうしないと、広範囲なソースのコピーによって認証情報がイメージレイヤーに残る可能性があります。
• Node.js スターターでは、両方の npm ci 手順で npmrc を BuildKit シークレットとしてマウントします。パブリックパッケージのビルドではシークレットは不要です。プライベートレジストリを使う場合は、設定を明示的に渡してください。

  DOCKER_BUILDKIT=1 docker build --secret id=npmrc,src="$HOME/.npmrc" .
  

  プロジェクトで設定ファイルを別の場所に保存している場合は、実際の設定パスを使用してください。認証情報ファイルをコピーしたり、その値を ARG または ENV 経由で渡したりしないでください。インストール中に実行される依存関係のスクリプトは、マウントされたシークレットにアクセスできます。信頼できる依存関係と、最小限の権限を持つレジストリトークンを使用してください。
• Compose を使ってプライベートレジストリからビルドする場合は、スターターの compose.yaml と同じ場所に、次のオプションのオーバーライドを compose.npm.yaml として追加してください。

  services:
    app:
      build:
        secrets:
          - npmrc
  secrets:
    npmrc:
      file: ${NPMRC_PATH:?Set NPMRC_PATH to your npm config file}
  

  NPMRC_PATH="$HOME/.npmrc" docker compose -f compose.yaml -f compose.npm.yaml build でビルドします。これによりビルド時のみアクセスが許可され、実行時のシークレットにはなりません。パブリックパッケージのビルドでは、認証情報ファイルが不要になるよう、オーバーライドを省略してください。

ホストへのインストールより Docker 化された依存関係を優先する

プロジェクトでデータベース（Postgres、MySQL、MongoDB）、キャッシュ（Redis、Memcached）、キュー（RabbitMQ、Kafka）、その他のインフラストラクチャサービスが必要な場合は、次のようにしてください。

• 必ず compose.yaml のサービスとして定義し、ホストにインストールするようユーザーに指示しないでください。
• 開発用依存関係について、brew install postgres、apt install redis など、ホストへのインストールを提案しないでください。
• これらのサービスには Docker Hub の公式 Docker イメージを使用してください。
• イメージに組み込まれた設定ファイルではなく、環境変数でサービスを構成してください。

ブートストラップのチェックリスト

• 古い Compose ファイル名ではなく、ファイル名を compose.yaml にします。
• docker/ サブディレクトリが妥当なマルチサービス構成を明確に必要とする場合を除き、3 つのファイルすべてをプロジェクトのルートに配置します。
• 初期セットアップを、1 つのコマンドパスでローカルにビルドして起動できるようにします。
• 公開するアプリケーションのポートは、デフォルトでループバックにバインドします。別のデバイスから開発サービスにアクセスする必要がある場合にのみ、ホストアドレスの範囲を広げます。
• 認証のないデータストアは、ポートを公開せずに Compose ネットワーク内に置きます。ローカルのホストツールからデータベースへのアクセスが必要な場合は、ループバックにのみ公開します。
• 開発専用の認証情報フォールバックでワンコマンド起動を可能にする場合は、その旨を明確に示し、.env による上書き方法を記載します。
• ローカルデータベース、キャッシュ、キューには、ホストへのインストールではなく Compose サービスを使用します。
• 最初のひな形はシンプルに保ち、詳細なイメージ最適化や高度な Compose の調整は担当スキルに委ねます。

開発と本番環境

• 開発：ライブリロードにはバインドマウントを使用し、アプリケーションのポートはデフォルトでループバックに公開して、詳細なログ出力を有効にします。認証のないデータストアは Compose ネットワーク内に置きます。ローカルのホストツールからのアクセスが必要な場合に限り、データストアのポートをループバックに公開します。
• 本番環境：マルチステージビルドを使用し、ビルド済みの成果物のみをコピーします。ソースコードはマウントせず、イメージのレイヤーを最小限にし、適切なリソース制限を設定します。
• 可能な場合は、ビルドステージとビルド引数によって両方に対応する単一の Dockerfile を維持します。

ファイルの配置

• Dockerfile はプロジェクトのルートに配置します（複数のサービスがあるプロジェクトの場合は docker/ サブディレクトリに配置します）。
• compose.yaml はプロジェクトのルートに配置します。
• .dockerignore はプロジェクトのルートにある Dockerfile の隣に配置します。

関連スキル

• Dockerfile の最適化、キャッシュ戦略、非 root での実行、イメージの堅牢化には、docker-build-strategies を使用します。
• サービスの依存関係、ヘルスチェック、オーバーライド、ボリューム、ネットワーク、Compose のデバッグには、docker-compose-patterns を使用します。
• 破壊的な Docker CLI コマンド（docker system prune、docker rm -f、イメージ／ネットワーク／ビルダーのプルーニング）と、製品横断の破壊的コマンド向けガードレール一覧には、docker-destructive-guardrails を使用します。

参考資料

• references/project-structure.md — Docker プロジェクトのファイル構成、命名規則、マルチサービス構成に関する詳しいガイダンスです。

アセット

• assets/dockerignore-example — 一般的なプロジェクト向けの包括的な .dockerignore です。
• assets/compose-dev.yaml — Docker 化された依存関係を含む、開発向けの Compose ファイルです。
• assets/Dockerfile.simple — ベストプラクティスに従った基本的なマルチステージ Dockerfile です。

スクリプト

• scripts/verify-setup.sh — 現在のディレクトリに必要なファイルが存在するかを確認し、その compose.yaml を検証します。プロジェクトのルートから、スクリプトのパスをこのスキルのディレクトリ内で解決して実行してください：

  bash "<skill-dir>/scripts/verify-setup.sh" [--help]
  

  <skill-dir> は、この SKILL.md を含むフォルダーの絶対パスに置き換えます。scripts/ のパスはプロジェクトではなく、そのフォルダーを基準とします。スキルのディレクトリに移動してから実行しないでください。スクリプトは現在のディレクトリを確認します。スキルのディレクトリを解決できない場合は、プロジェクトのルートに .dockerignore、Dockerfile、compose.yaml が存在することを確認してから、docker compose config --quiet を実行します。検証に成功した場合、またはヘルプが要求された場合の終了ステータスは 0、必要なファイルがない場合、または Compose の設定が無効な場合は 1、引数が無効な場合は 2 です。

チェック項目

• checks/verification.md — 手動レビュー用の詳しい検証チェックリストです。