Dockerfileを1行ずつ解剖

この設定ファイルは何者か

Dockerfileは、コンテナイメージの組み立て手順を上から順に記した設計書だ。docker buildを実行すると、ビルダー（現行の既定はBuildKit）がこのファイルを読み、FROMで指定した土台に命令を1つずつ適用していく。各命令の結果は読み取り専用の「レイヤー」として積み重なり、イメージの実体は、レイヤーの束に起動時の既定値（実行コマンドや環境変数）のメタデータを添えたものだ。

押さえておきたいのは、Dockerfileがビルド時の設定であって、実行時の設定ではない点だ。ここで決められるのは「何を含み、どう起動するイメージか」まで。ポートの割り当てやボリュームは、docker runやComposeといった実行側の領分だ。この線引きが分かると、後述するEXPOSEの誤解も自然に解ける。コンテナそのものの正体に迫るなら作って学ぶが近道だ。

横にスクロール

1行ずつ解剖

題材は、Node.js製Webサーバーをビルドして動かす次のDockerfileだ。

# ---- ビルドステージ ----
FROM node:22-bookworm-slim AS build
WORKDIR /app

# 依存定義だけを先にコピーしてキャッシュを効かせる
COPY package.json package-lock.json ./
RUN npm ci

# ソース本体をコピーしてビルドし、開発用依存を除去
COPY . .
RUN npm run build && npm prune --omit=dev

# ---- 実行ステージ ----
FROM node:22-bookworm-slim
ENV NODE_ENV=production
WORKDIR /app

COPY --from=build --chown=node:node /app/dist ./dist
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/package.json ./

EXPOSE 3000
USER node
ENTRYPOINT ["node", "dist/server.js"]

以下、命令のグループごとに読み解く。

FROMとマルチステージ——土台をタグとダイジェストで固定する

FROMはベースイメージを指定する。タグを省略するとlatestが補われるが、タグは付け替え可能なラベルにすぎず、同じタグでも取得時期によって中身が変わりうる。再現性を高めるには、バージョンとOS世代まで含むタグ（例では22系とDebian bookwormのslim版）を選び、さらに厳密にはダイジェストで固定する。

# タグとダイジェストを併記した場合はダイジェスト側が優先される
FROM node:22-bookworm-slim@sha256:64桁のダイジェスト値

ダイジェストはイメージの内容から計算される識別子なので、この書き方ならいつビルドしても同一の土台から始まる。タグは人間向けの注記として残る。

サンプルにはFROMが2回登場する。これがマルチステージビルドで、前半のステージにAS buildと名前を付け、後半はまっさらな同じベースからやり直す。出荷されるのは最後のステージだけで、ビルドの道具がどれだけ前半を汚しても最終成果物には影響しない。

RUN——レイヤーとキャッシュを制する

RUNはシェルコマンドを実行し、その結果のファイル変更を新しいレイヤーとして記録する。ビルドキャッシュは命令ごとに判定され、RUNは命令文字列が、COPYは対象ファイルの内容が前回と一致すれば再利用される。重要なのは、ある行のキャッシュが無効になると、それ以降の行がすべて作り直しになることだ。

サンプルの順序はこの性質から逆算している。package.jsonとpackage-lock.jsonだけを先にCOPYしてRUN npm ciを済ませておけば、ソースコードをどれだけ書き換えても依存インストールのレイヤーは再利用され続ける。先にCOPY . .と書いてしまうと、1文字の修正でもnpm ciからやり直しになる。

&&での連結にも理由がある。Debian系でパッケージを追加するなら、1つのRUNへまとめるのが定石だ。

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

apt-get updateを単独のRUNに分けると、その行だけ古いキャッシュが再利用され、後続のinstallが古いパッケージ一覧を参照してしまう。また、レイヤーは追記式なので、前のレイヤーで生まれたファイルを後のRUNで消してもイメージは小さくならない。一時ファイルの掃除は、生んだRUNの中で完結させる。

COPYとADD——.dockerignoreと三点セットで考える

COPYはビルドコンテキスト（docker buildに渡したディレクトリ）からイメージへファイルを写す、それだけの命令だ。ADDはさらにローカルのtarアーカイブの自動展開とURLからの取得もこなすが、多機能なぶん挙動の予測が難しい。公式のベストプラクティスも原則COPYを推し、ADDはtar展開が必要な場面に限るとしている。

マルチステージビルドではCOPY --from=buildのようにコピー元を他のステージへ切り替えられる。実行ステージが持ち込むのはビルド済みのdistと刈り込んだnode_modulesだけで、開発用依存は前半のステージごと捨てられる。

コピーの入口を絞るのが.dockerignoreだ。コンテキスト直下に置けば、node_modules・.git・.envのような不要あるいは危険なファイルを転送前に除外できる。転送が軽くなるうえ、COPY . .で秘密情報が紛れ込む事故や、無関係なファイルの変更によるキャッシュ破壊も防げる。

EXPOSEとUSER——公開しない宣言と、rootをやめる一行

つまりEXPOSEは運用者と周辺ツールへ向けたドキュメントだ。Compose利用時のports設定との対応はdocker-compose.ymlの解剖で扱う。

一方のUSERは実行権限を決める。指定しなければコンテナ内のプロセスはrootで動く。USER node以降はRUNや起動プロセスが非特権ユーザーで実行され、侵入された場合の被害範囲を狭められる。node公式イメージにはnodeユーザーが用意されているが、無いイメージではRUNでユーザーを作ってから切り替える。ファイル所有権はサンプルのようにCOPYの--chownで揃えるのが手早い。

ENTRYPOINTとCMD——起動コマンドとシグナルの行方

両者は起動時のコマンドを分担する。ENTRYPOINTが固定の本体、CMDがその既定引数だ（ENTRYPOINTが無ければCMDが既定コマンドになる）。docker run末尾の引数はCMDだけを置き換えるので、変えない部分をENTRYPOINT、差し替えたい部分をCMDに分けると使い勝手がよい。

もう1つの軸が書式で、JSON配列で書くexec形式と、素の文字列で書くシェル形式がある。

# exec形式：nodeがそのままPID 1になる
ENTRYPOINT ["node", "dist/server.js"]

# シェル形式：/bin/sh -c を介して起動される
CMD node dist/server.js

exec形式では指定したプログラムがPID 1として直接起動し、docker stopが送るSIGTERMを自分で受け取れる。シェル形式ではPID 1が/bin/shになり、shは受け取ったシグナルを子プロセスへ転送しないため、アプリにSIGTERMが届かない。猶予時間（既定10秒）の後はSIGKILLで強制終了され、グレースフルシャットダウンは動かない。本番イメージのENTRYPOINTとCMDはexec形式で書くのが原則だ。

つまずきやすい点

依存インストールより先のCOPY . .。ソースを1行直すだけでキャッシュが崩れ、毎回npm ciが走る。依存定義のCOPY、インストール、ソース全体のCOPYの順へ直すだけでビルド時間は激減する。

latestタグでの運用。今日と来週で違うイメージが落ちてくるため、ビルドの再現も障害時の切り戻しもできない。バージョン付きタグを基本に、必要ならダイジェストまで固定し、更新は差分を確認しながら明示的に行う。

シェル形式CMDとPID 1問題。docker stopのたびに10秒固まってから落ちるコンテナは、まずこれを疑う。exec形式へ改めるか、起動スクリプトを挟む場合はスクリプト末尾のexecで本体プロセスにPID 1を譲る。

RUNの分けすぎによる肥大。生成と削除を別のレイヤーに分けると、消したはずのファイルが下のレイヤーに残り続ける。掃除は生成と同じRUNで完結させる。ただし何でも1行へ繋ぐとキャッシュの粒度が粗くなるので、変更頻度が近い処理どうしで束ねるのが現実解だ。

まとめ

Dockerfileは、レイヤーとキャッシュの都合から逆算して書く設定ファイルだ。順序は「変わりにくいものを上、変わりやすいものを下」、起動は「exec形式が原則」、土台は「タグとダイジェストで固定」、仕上げは「マルチステージとUSERで軽く安全に」。この4点を押さえれば、ビルド時間・イメージサイズ・停止挙動の悩みはあらかた片付く。ビルドをCI/CDへ組み込む先の話はDevOpsから辿ってほしい。