Dockerfile は、コンテナイメージの作り方を上から順に書いた手順書です。
同じアプリでも、命令の並べ方や書き分け方しだいで、イメージの大きさとビルドのたびに待つ時間が大きく変わります。
前の記事では、サーバーを直さずにイメージごと作り直すイミュータブルインフラの考え方を整理しました。
作り直す前提に立つと、イメージは小さく、何度でも速く作り直せる形にしておく必要が出てきます。
Docker の公式ドキュメント「Building best practices」と関連ページを読み、効き目の大きい書き方を 5 つ選んで、手元で実際にビルドして差を確かめました。
検証は Windows 11 上の Docker Desktop 4.92.0(Docker Engine 29.8.0・Buildx v0.37.1)で行い、ビルドはすべて既定の BuildKit で動かしています。
変わりにくい命令を上に、変わりやすい命令を下に置く
Docker は Dockerfile の命令を上から順に実行し、命令ごとに前回のビルド結果を使い回せるかを調べます。
使い回せるのは、命令とその命令が読むファイルが前回から変わっていない場合だけです。
そして、ある命令のキャッシュが無効になると、その下にある命令はすべて実行し直しになります。
そのため、依存パッケージの導入のように重くて変わりにくい手順を上に、頻繁に変わるソースコードのコピーを下に置くのが基本の形です。
次の 2 つは、Python の小さなアプリを python:3.13-slim の上で動かす Dockerfile です。
1 つ目では、ソースを全部コピーしてから依存を入れます。
# syntax=docker/dockerfile:1
FROM python:3.13-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["python", "app.py"]
2 つ目は、依存の定義ファイルだけを先にコピーして入れ、ソースはあとからコピーする書き方です。
# syntax=docker/dockerfile:1
FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]
両方を一度ビルドしたあと、app.py の表示する文字列を 1 か所だけ変えて、docker build --progress=plain でもう一度ビルドしました。
1 つ目では COPY . . のキャッシュが外れ、その下の pip install が走り直しています。
#9 [3/4] COPY . .
#9 DONE 0.0s
#10 [4/4] RUN pip install --no-cache-dir -r requirements.txt
#10 1.314 Collecting requests==2.32.3 (from -r requirements.txt (line 1))
(略)
#10 DONE 2.2s
2 つ目では、requirements.txt が変わっていないので pip install までがキャッシュで済み、コピーし直したのは最後のソースだけでした。
#9 [3/5] COPY requirements.txt .
#9 CACHED
#10 [4/5] RUN pip install --no-cache-dir -r requirements.txt
#10 CACHED
#11 [5/5] COPY . .
#11 DONE 0.1s
今回は依存が requests の 1 つだけなので差は 2 秒ほどでしたが、依存が多いアプリほど、ソースを直すたびに待つ時間の差として効いてきます。
同じ理由で、公式ドキュメントは apt-get update と apt-get install を同じ RUN にまとめるよう勧めています。
分けて書くと apt-get update の層がキャッシュから使い回され、あとでパッケージを足したときに古い一覧のまま入れようとしてしまうからです。
ビルドの道具を最終イメージに残さない
コンパイラやビルドツールは、ビルドには要っても、動かすときには要りません。
マルチステージビルドは、1 つの Dockerfile に FROM を複数書き、前の段で作った成果物だけを次の段へコピーする書き方です。
公式ドキュメントにある Go の例を、ソースを別ファイルに分ける形に変えて動かしました。
# syntax=docker/dockerfile:1
FROM golang:1.26 AS build
WORKDIR /src
COPY main.go .
RUN go build -o /bin/hello ./main.go
FROM scratch
COPY --from=build /bin/hello /bin/hello
CMD ["/bin/hello"]
比べるために、golang:1.26 の上でビルドしてそのまま動かす、1 段だけの Dockerfile も用意しました。
どちらも「hello, world」と表示するだけのプログラムです。
$ docker image ls --filter 'reference=hello-*'
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
hello-multi:latest 61cb5c1e08a8 3.84MB 1.43MB
hello-single:latest ea8416d3a33a 1.33GB 322MB
DISK USAGE で見ると 1.33GB と 3.84MB で、350 倍近い差が出ています。
1 段だけの場合は Go の開発環境がまるごとイメージに入りますが、マルチステージでは最後の段に明示してコピーした実行ファイルしか残りません。
段に AS build のような名前を付けておけば、あとで命令を並べ替えても COPY --from の参照が崩れずに済みます。
Go のように 1 つの実行ファイルにまとまらない言語でも、ベースイメージの選び方で大きさは変わります。
手元で取り直した公式の Python イメージでは、DISK USAGE が python:3.13 で 1.62GB、python:3.13-slim で 178MB でした。
公式ドキュメントも、ビルドとテスト用のイメージと、本番用のより小さなイメージを分けることを勧めています。
小さいイメージは取得が速いだけでなく、入っているパッケージが少ないぶん、依存から入り込む脆弱性も減らせます。
送らなくてよいファイルを .dockerignore で外す
docker build . の最後の . はビルドコンテキストと呼ばれ、ビルダーに送るファイルの範囲を決めます。
コンテキストの直下に .dockerignore を置くと、書いたパターンに合うファイルが送る前に取り除かれます。
これを試すため、さきほどの 2 つ目のディレクトリに 100MB のログファイルと、ダミーの値を入れた .env を足しました。
.dockerignore が無い場合と、次の 2 行を書いた場合を、それぞれ新しいディレクトリでビルドして比べています。
logs/
.env
結果は次のとおりです。
| 項目 | .dockerignore なし | .dockerignore あり |
|---|---|---|
| コンテキストの転送 | 104.88MB・5.8 秒 | 421B・0.0 秒 |
| イメージの DISK USAGE | 404MB | 194MB |
| /app に入った .env | あり | なし |
転送の時間とイメージの大きさに加えて、3 行目の差も見逃せません。
COPY . . はコンテキストにあるものを全部コピーするので、.dockerignore が無いと .env の中身がそのままイメージに入っていました。
$ docker run --rm ctx-noignore cat /app/.env
API_KEY=dummy
イメージは配布や共有をされるものなので、秘密の値が入ったファイルは、コンテキストの段階で外しておくことが大切です。
なお、Dockerfile ごとに除外の設定を変えたいときは、build.Dockerfile.dockerignore のように Dockerfile の名前を頭に付けたファイルを同じ場所に置けば、そちらが優先されます。
秘密の値は ARG ではなくシークレットマウントで渡す
非公開のパッケージ置き場に入るトークンのように、ビルドの途中でだけ秘密の値が要る場面があります。
ARG や ENV で渡すと値がイメージに残るため、公式ドキュメントはシークレットマウントを使うよう勧めています。
手元で ARG API_TOKEN を宣言し、--build-arg API_TOKEN=dummy-123 を渡してビルドすると、Docker 自身が警告を出しました。
1 warning found (use docker --debug to expand):
- SecretsUsedInArgOrEnv: Do not use ARG or ENV instructions for sensitive data (ARG "API_TOKEN") (line 3)
できたイメージの履歴を docker history --no-trunc で見ると、渡した値がそのまま読めます。
RUN |1 API_TOKEN=dummy-123 /bin/sh -c test -n "$API_TOKEN" && echo "token received" # buildkit
ARG API_TOKEN=dummy-123
シークレットマウントを使うと、値はその RUN の間だけ見え、イメージには残りません。
# syntax=docker/dockerfile:1
FROM alpine:3.22
RUN --mount=type=secret,id=api_token,env=API_TOKEN \
test -n "$API_TOKEN" && echo "token received"
ビルドするときは、--secret で渡す値の出どころを指定します。
$ API_TOKEN=dummy-123 docker build --progress=plain -f mount.Dockerfile --secret id=api_token,env=API_TOKEN -t sec-mount .
この形で作ったイメージの履歴には RUN の命令だけが残り、値は出てきませんでした。
ビルドのログでも、該当の箇所は test -n "****" と伏せて表示されています。
env= で環境変数として受け取る書き方は、Dockerfile の構文の v1.10.0 から使えるようになったものです。
秘密の値そのものをどこに置くか、漏れたときに何から手を付けるかは、別の記事で整理しました。
作り直しやすさを保つための決めごと
イメージは作った時点のベースイメージやライブラリを固めたものなので、放っておくと中身が古くなります。
公式ドキュメントは、依存を新しくしたうえで定期的に作り直すことを勧めていました。
docker build --pull はベースイメージの新しい版を確かめて取りに行き、--no-cache はキャッシュを使わずに全部の手順をやり直します。
2 つは役割が違うので、まとめて付けることもできます。
一方で、python:3.13-slim のようなタグは発行元が付け替えられるため、同じ Dockerfile でも時期によって中身が変わります。
ダイジェストで固定すれば毎回同じベースイメージになりますが、セキュリティ修正も自動では入りません。
その間を取る方法として、公式ドキュメントは Dependabot がタグとダイジェストの更新をプルリクエストで出す運用を紹介していました。
いつ何を上げたかが履歴に残るので、固定と更新を両立できます。
時刻や依存を固めて同じ成果物を作る話は、ビルドの再現性として別にまとめています。
もう 1 つ、さきほどの pip のログには、root ユーザーで pip を動かしていることへの警告が出ていました。
公式ドキュメントは、特権の要らないサービスなら USER で root 以外のユーザーに切り替えるよう勧めています。
参考にした公式ドキュメントは、次の 3 ページです。
Building best practices
Optimize cache usage in builds
Build secrets
最後に
小さく作り直しやすいイメージは、変わりにくいものを上に置く順番、ビルドの道具を残さないマルチステージ、送るファイルを絞る .dockerignore の 3 つで大部分が決まると分かりました。
秘密の値はシークレットマウントで渡し、ベースイメージは更新の仕組みとセットで固定すると、作り直すたびの不安も減らせます。
Dockerfile は、何をイメージに残して何を残さないかを決める設計図として読むと、ひとつひとつの書き方の理由がつながって見えてきます。
以上です。











コメントを残す