dockerfile-optimise

Dockerfile 最適化のベストプラクティス

Docker の公式ドキュメントのみを情報源とする、包括的な Dockerfile 最適化ガイドです。8 つのカテゴリにわたる 48 のルールを含み、自動リファクタリングとコード生成の指針となるよう、影響度の高い順に優先順位を付けています。

適用するタイミング

次のような場合に、これらのガイドラインを参照してください。

• 新しい Dockerfile を作成するとき、または既存のものを変更するとき
• Docker のビルド時間を最適化するとき（レイヤーキャッシュ、キャッシュマウント、コンテキスト管理）
• Docker イメージのサイズを削減するとき（マルチステージビルド、最小限のベースイメージ）
• コンテナのセキュリティを強化するとき（シークレットマウント、非 root ユーザー、アテステーション）
• Docker ビルドを含む CI/CD パイプラインを設定するとき
• Dockerfile のアンチパターンをレビューするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	レイヤーキャッシュと順序	CRITICAL	cache-
2	マルチステージビルド	CRITICAL	stage-
3	ベースイメージの選択	HIGH	base-
4	ビルドコンテキストの管理	HIGH	ctx-
5	セキュリティとシークレット	HIGH	sec-
6	依存関係の管理	MEDIUM-HIGH	dep-
7	命令パターン	MEDIUM	inst-
8	品質と検証	MEDIUM	lint-

クイックリファレンス

1. レイヤーキャッシュと順序（CRITICAL）

• cache-layer-order - 変更頻度に応じてレイヤーを並べる
• cache-copy-deps-first - ソースコードより先に依存関係ファイルをコピーする
• cache-copy-link - キャッシュ効率の高いレイヤーコピーに COPY --link を使用する
• cache-mount-package - パッケージマネージャーにキャッシュマウントを使用する
• cache-apt-combine - apt-get update と install をまとめる
• cache-external - CI/CD ビルドに外部キャッシュを使用する
• cache-invalidation - 不要なキャッシュ無効化を避ける
• cache-minimize-layers - 関連する RUN 命令をまとめる

2. マルチステージビルド（CRITICAL）

• stage-separate-build-runtime - ビルドステージと実行ステージを分ける
• stage-named-stages - 名前付きビルドステージを使用する
• stage-parallel-branches - ステージの並列実行を活用する
• stage-target-builds - 開発環境／本番環境向けにターゲットビルドを使用する
• stage-copy-artifacts-only - ステージ間では最終成果物のみをコピーする
• stage-reusable-base - 再利用可能なベースステージを作成する

3. ベースイメージの選択（HIGH）

• base-minimal-image - 最小限のベースイメージを使用する
• base-official-images - Docker Official Images を使用する
• base-pin-versions - ダイジェストを使ってベースイメージのバージョンを固定する
• base-arg-version - ベースイメージをパラメーター化するため、FROM より前に ARG を使用する
• base-rebuild-regularly - --pull を使ってイメージを定期的に再ビルドする
• base-distroless - 本番環境では distroless イメージまたは scratch イメージを使用する

4. ビルドコンテキストの管理（HIGH）

• ctx-dockerignore - 不要なファイルを除外するために .dockerignore を使用する
• ctx-bind-mounts - ビルド時のみ必要なファイルには COPY の代わりにバインドマウントを使用する
• ctx-minimize-context - ビルドコンテキストを小さく保つ
• ctx-syntax-directive - 最新の BuildKit 機能を利用するために構文ディレクティブを使用する（キャッシュマウント、シークレットマウント、heredoc、COPY --link の前提条件）

5. セキュリティとシークレット（高）

• sec-secret-mounts - 機密データにはシークレットマウントを使用する
• sec-non-root-user - root 以外のユーザーとして実行する
• sec-no-secrets-in-args - ARG や ENV でシークレットを渡さない
• sec-ssh-mounts - プライベートリポジトリへのアクセスには SSH マウントを使用する
• sec-attestations - SBOM と来歴証明のアテステーションを有効にする
• sec-no-unnecessary-packages - 不要なパッケージのインストールを避ける
• sec-ephemeral-containers - エフェメラルでステートレスなコンテナを設計する

6. 依存関係の管理（中〜高）

• dep-cache-mount-apt - apt パッケージマネージャーにキャッシュマウントを使用する
• dep-cache-mount-npm - npm、yarn、pnpm にキャッシュマウントを使用する
• dep-cache-mount-pip - pip にキャッシュマウントを使用する
• dep-version-pin - 再現性を確保するためにパッケージのバージョンを固定する
• dep-cleanup-caches - 同じレイヤー内でパッケージマネージャーのキャッシュを削除する

7. 命令のパターン（中）

• inst-json-cmd - CMD と ENTRYPOINT には JSON 形式を使用する
• inst-healthcheck - コンテナオーケストレーション用に HEALTHCHECK を定義する
• inst-heredoc-scripts - 複数行のスクリプトには heredoc を使用する
• inst-entrypoint-exec - entrypoint スクリプトでは exec を使用する
• inst-workdir-absolute - WORKDIR では絶対パスを使用する
• inst-copy-over-add - ADD より COPY を優先する

8. 品質と検証（中）

• lint-build-checks - Docker のビルドチェックを有効にする
• lint-pipefail - パイプを使う RUN コマンドでは pipefail を使用する
• lint-labels - イメージのメタデータには標準ラベルを使用する
• lint-sort-arguments - 複数行の引数をアルファベット順に並べる
• lint-single-concern - 1 つのコンテナにつき 1 つの関心事にする

使用方法

詳しい説明とコード例については、個別のリファレンスファイルを参照してください。

• セクションの定義 - カテゴリーの構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報