Docker Composeのbuildとimageの違いとVPS運用
Docker Composeのimageは既存イメージを使い、buildはDockerfileから作成します。VPSでcompose upが変更を無視する理由と、正しく反映する方法を解説します。
Docker Compose の build と image の違い: 要点
Docker Compose ファイルでは、image:で使用するイメージを指定します。ローカルイメージ、タグ、digest 参照を指定できます。build:では、ソースからイメージをビルドする方法を指定します。image:だけを設定すると、Compose は pull_policyに従ってイメージを使用または pull します。build:だけを設定すると、Compose は設定済みの builder でイメージをビルドし、プロジェクト名とサービス名から生成した名前を付けます。両方を設定した場合は、pull_policyで Compose が pull とビルドのどちらを行うかを制御します。ビルドする場合、結果には image:の名前でタグが付けられます。これにより、イメージをビルドし、指定した名前で push できます。builder はローカルで実行することも、リモートの Docker host で実行することもできます。
違いは以上です。以下では、サーバー上の運用でこの違いが何を意味するかを説明します。ここでは、Docker Engine と Compose plugin がすでにインストールされていることを前提とします。この作業については、VPS で Docker を実行する方法で説明しています。
3 つの形式の詳細
公開済みのタグを使用します。デフォルトの pull ポリシーに従い、イメージが存在しない場合は pull します。Dockerfile はどの段階でも使用しません。
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"プロジェクトディレクトリにある Dockerfile からビルドします。Dockerfile に必要なイメージの pull や依存関係のダウンロードも実行できます。
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"ビルド結果に docker compose build のタグを付けます。明示的な pull ポリシーを指定しない場合、up はビルド前にこのイメージの pull を試みます。その後、docker compose push でその正確なタグをレジストリへ送信できます。
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context は builder に送信されるディレクトリです。dockerfile はその context を基準に解決されるため、dockerfile: docker/prod.Dockerfile を指定した context: . は通常の正しい指定です。docker compose images を実行すると、各 service container の背後にあるイメージ名と image ID を確認できます。Compose ファイルを確認し、その service が image:、build:、またはその両方を使用しているかを確かめてください。
Dockerfileを変更した後もdocker compose upで再ビルドされないのはなぜですか?
通常の up は、ビルドを要求するか、ビルドが必要になるポリシーを設定しない限り、既存のイメージを再利用するためです。
Compose は、build: セクションだけを持つサービスを起動するとき、利用可能な既存イメージを使用します。Dockerfileを読み込んだり、ソースファイルを比較したり、タイムスタンプを確認したりはしません。image: と build: の両方があり、明示的な pull_policy がない場合、Compose は最初に pull を試み、レジストリまたはプラットフォームのキャッシュにイメージがなければビルドします。イメージが存在すれば十分と判断されます。
そのため、app.py を編集して docker compose up -d を実行すると、Compose はコンテナが running であると表示するのに、古いコードが提供されます。処理は失敗していないため、警告も表示されません。手掛かりになるのは、Compose がコンテナ名の横に表示するステータスです。Compose が置き換えたコンテナは recreated または started と表示され、Compose がそのままにしたコンテナは running と表示されます。
2 つの確認で判断できます。docker compose images は各コンテナが使用しているイメージ ID を表示するため、デプロイ前に記録して実行後と比較します。docker image ls には CREATED 列がありますが、キャッシュされたビルドや再現可能なタイムスタンプがあるため、その日付だけでは最新のソースがビルドされたかどうかを証明できません。
再ビルドを強制するフラグ
docker compose up -d --buildは最初にビルドし、イメージが変更されたコンテナを再作成します。多くの場合、必要なのはこのフラグです。docker compose build webは 1 つのサービスをビルドするだけで、何も起動しません。続けてdocker compose up --no-deps -d webを実行すると、そのコンテナだけを置き換え、スタックの残りは稼働したままにできます。docker compose build --no-cache webはキャッシュされたレイヤーを使用せず、サービスを再ビルドします。docker compose build --pullはFROMのベースイメージについて、より新しいバージョンの取得を試みます。そのため、node:22のような可変タグは、3 月にダウンロードしたコピーではなく、現在の内容を取得します。docker compose up -d --force-recreateは、設定とイメージが変更されていなくてもコンテナの再作成を強制します。このフラグ自体はビルドを要求しませんが、イメージが存在しない場合や、pull policy により取得が必要な場合はupがビルドすることがあります。--buildのつもりでこのフラグを使うと、解決につながらないことがよくあります。
ファイル内でこの判断を指定することもできます。Compose specification の説明では、pull_policy: build は Compose がイメージをビルドし、すでに存在する場合は再ビルドすることを意味します。up を実行するたびにビルドが発生するため、ノートパソコンでは適していますが、サーバーでは通常適していません。
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: buildもう 1 つ、組み合わせによる動作を把握しておくと役立ちます。docker compose pull は、build セクションも持つサービスのイメージ取得も試みます。その取得に失敗すると、イメージをビルドする必要があると通知します。--ignore-buildable を渡すと、これらのサービスを通知なしでスキップできます。
デプロイ時間をビルドキャッシュが決める仕組み
ビルダーは、命令とその入力に変更がない場合、各 Dockerfile 命令について再利用可能なキャッシュ結果があるかを確認します。COPY の入力にはファイルの内容とメタデータが含まれますが、変更時刻は除外されます。いずれかのレイヤーでキャッシュミスが発生すると、それ以降の、そのレイヤーに依存するステップが再ビルドされます。
この 1 つのルールによって、デプロイに数秒かかるか数分かかるかが決まります。Dockerfile は、変更頻度が低いものから、コミットごとに変更されるものの順に並べます。
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci は COPY . . の上に配置されます。そのため、ソースファイルを編集しても install レイヤーはキャッシュされ、ビルドは copy ステップから再開されます。この 2 行を入れ替えると、1 文字の変更だけで依存関係がすべて再インストールされます。これは、COPY . . が npm ci の基盤となるレイヤーを無効にするためです。同じ構成は pip install -r requirements.txt と go mod download にも当てはまります。
古いレイヤーが修正を隠していると考えられる場合は、--no-cache が適切なツールです。ただし、デフォルトで使うべきではありません。Dockerfile の順序付けによって得られるキャッシュの再利用を破棄するためです。
イメージが設定する項目の 1 つは Compose で上書きできます。Dockerfile の CMD がイメージのデフォルト実行内容を指定し、サービス内の command: キーがそれを置き換えます。ここでは command と entrypoint の連携方法 が重要です。Compose による上書きによって、新しくビルドしたイメージが以前のイメージとまったく同じ動作をする場合があるためです。
ビルドコンテキストと.dockerignore
context: .はプロジェクトディレクトリをビルダーから利用できるようにします。除外設定がなければ、.gitや、ソースの隣に置いているデータディレクトリも含まれます。ただし、BuildKit は使用されていないファイルをスキップし、変更分を差分転送します。変更していないプロジェクトで、コンテキストの転送処理が一時停止するビルドは、コンテキストが大きすぎることを示しています。
コンテキストのルートに置いた.dockerignoreファイルを使うと、転送対象からパスを除外できます。構文は.gitignoreに近い形式です。
.git
node_modules
*.log
data/
.env効果は2つあります。転送量が減り、それらのファイルの送信にかかる時間を短縮できます。また、COPY . .が.envをイメージへコピーできなくなるため、そのイメージを取得できる人が内容を読み出すこともできません。
時間の経過とともにビルドが遅くなる原因として、bind mount が挙げられます。named volume はプロジェクトディレクトリの外部にあります。一方、./data:/var/lib/postgresql/dataのような bind mount はビルドコンテキスト内にあるため、データベースが大きくなるにつれて、毎週ビルドが遅くなります。.dockerignoreに1行追加すれば解決できます。より広いトレードオフについては、named volume に対する bind mountで説明しています。
ビルド引数にも、同じリスクを小さくした形で伴います。args:で渡した値は、イメージ履歴や provenance メタデータに残る可能性があります。そのため、ここにはバージョン番号を指定し、トークンは絶対に指定しないでください。事前定義されたプロキシ引数は、Dockerfile で明示的に参照しない限り、デフォルトでビルドキャッシュとdocker historyから除外されます。認証情報を置く場所については、Compose の環境ファイルと Secretで説明しています。
VPS 上でビルドするか、別の場所でビルドして pull するか
トラフィックを処理するサーバー上でビルドする方法がデフォルトです。最短経路だからです。git pull、続いて docker compose up -d --build を実行します。まだ誰も依存していない小規模なサーバーなら問題ありません。ただし、測定できる2つの理由と、障害発生時にだけ現れる1つの理由から、適切でなくなります。
メモリ。 ビルドでは、稼働中のアプリケーションと同じ場所でコンパイラーやバンドラーを実行します。多くの構成では、これらが最も多くのメモリを消費します。JavaScript bundler や Rust のコンパイルによって、1 GB VPS で利用可能なメモリを使い果たすことがあります。メモリが枯渇すると、kernel はメモリ使用量、割り当てコンテキスト、oom_score_adj に基づく badness score を使って OOM の対象を選びます。単純に最大のプロセスを終了するわけではありません。ビルドが Killed と終了ステータス 137 で停止することもあれば、代わりにデータベースが終了して、デプロイ途中にサイトが停止することもあります。dmesg -T | grep -i oom は kernel log で OOM メッセージを検索します。このログの読み取りには権限が必要です。
ディスク。 ビルドを実行すると、イメージレイヤーとビルドキャッシュが残ります。docker system df でディスク使用量を確認できます。BuildKit は、設定されたポリシーに従って定期的なガベージコレクションを実行し、キャッシュを回収します。dangling image は docker image prune、キャッシュされたレイヤーは docker builder prune で回収します。ディスクが満杯になると、ビルド以外も停止します。データベースも書き込みを停止し、低速なデプロイよりはるかに大きな障害になります。
再現性。 イメージを push または export しない限り、サーバー上でビルドしたイメージはそのサーバーにしか存在しません。古いイメージを利用できなくなると、ロールバックには古い commit を checkout して再度ビルドする必要があります。しかし、そのビルドが以前と同じ成果物を生成する保証はありません。base tag が更新され、パッケージミラーも変わっている可能性があるためです。別の場所でビルドして tag を push すれば、ロールバックは編集作業になります。image: を以前の tag に変更し、docker compose up -d を実行します。
安定する構成は単純です。継続的インテグレーションでビルドを実行して registry.example.com/acme/web:<git-sha> を push し、VPS 上の Compose ファイルには image: を記述します。build: key は一切記述しません。これでデプロイに必要なコマンドは、ほとんどメモリを消費しない2つだけになります。
docker compose pull
docker compose up -dprivate tag を pull するための認証情報を保存するには、サーバー上で docker login registry.example.com を実行します。
ビルド用の section は削除せず、自分で決めた名前のファイルに残します。
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildそのファイルには compose.dev.yaml という名前を付け、compose.override.yaml にはしません。Compose は override file が存在すると自動的に読み込むため、誤ってコピーした override file がサーバー上でのビルドを再び開始する可能性があります。複数の Compose ファイルを重ねる方法では、merge によって各 key がどのように解決されるかを説明しています。
別の環境でビルドする場合に起きるアーキテクチャの落とし穴
単一プラットフォームのイメージには、ビルド時の CPU アーキテクチャが含まれます。Apple Silicon のラップトップで ARM イメージをビルドして push し、そのイメージを x86_64 VPS で使用すると、明示的な platform 指定がないまま互換性のないキャッシュ済みイメージが使われた場合、Docker はコンテナ作成時に警告します。エミュレーションがない場合、プロセスは exec format error で失敗します。これは破損したバイナリのように見えますが、実際にはそうではありません。対象環境向けに明示的にビルドします。
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .ラップトップが x86 で、x86 ではなく ARM の VPS を実行する場合も、同じ不一致が起きます。デプロイ先と同じアーキテクチャ上で CI にビルドさせれば、この問題をなくせます。マルチプラットフォームイメージでも解決できます。Docker は pull 時に一致するバリアントを選択します。
デプロイ後に確認すること
docker compose imagesは、実行中の各コンテナで使用されているイメージとタグを表示します。イメージ ID が変わっていれば、新しいビルドが稼働している証拠です。docker compose configは、変数を置換した後の結合済みファイルを表示します。何かを実行する前に、Compose が使用する最終的なイメージ名を確認できます。docker compose logs -f webは、切り替え後の最初の 30 秒間実行します。起動と終了を繰り返すコンテナが再起動するのは、restart policy で指定されている場合だけです。原因をログで確認してください。docker image lsには CREATED 列が表示されます。作成時刻だけでは再ビルドが実行されたかどうかを判断できないため、ビルド出力とデプロイされたイメージ ID も確認してください。
これらの確認対象となるファイルをまだ作成中であれば、VPS 上の Compose ファイルの基本で関連するキーを確認できます。また、Compose コマンドのチートシートには、その他のサブコマンドがまとめられています。
FAQ
build と image を同じサービスで使用できますか?
はい。自分でビルドするプロジェクトでは、通常この構成にします。Compose は build: セクションからビルドすると、その結果に image: の値でタグを付けます。明示的な pull_policy がない場合、up は最初に pull を試みます。このタグは、docker compose push がレジストリへ送信するときに使用され、別のマシンが pull するときにも使用されます。image: キーがなくても Compose はビルドしますが、プロジェクト名とサービス名を組み合わせた名前を image に付けます。また、属性がないため image を push できないという警告を表示します。
docker compose up で Dockerfile の変更が反映されないのはなぜですか?
通常の up は、ビルドを要求するか、ビルドが必要になるポリシーを設定しない限り、既存の image を再利用するためです。Dockerfile やソースファイルと既存の image を比較して、再ビルドが必要かどうかを判断することはありません。docker compose up -d --build を実行するか、docker compose build web に続けて docker compose up --no-deps -d web を実行して、1 つのサービスを置き換えます。サービスに pull_policy: build を設定すると、すべての up で再ビルドされます。開発用マシンに適した設定です。
--build と --force-recreate の違いは何ですか?
--build は image を再度ビルドし、image が変更されたコンテナを再作成します。--force-recreate は、設定と image に変更がなくてもコンテナの再作成を強制します。これ自体はビルドを要求しません。変更箇所がソースまたは Dockerfile である場合は、--build を使用します。--force-recreate は、同じ image を維持したまま書き込み可能レイヤーを消去するなど、コンテナ自体を初期化するときに使用します。
Docker image は VPS 上でビルドすべきですか、それとも別の場所でビルドすべきですか?
VPS がネットワークトラフィックも処理するようになったら、別の場所でビルドしてからタグを pull してください。ビルドはアプリケーションとメモリを奪い合います。メモリが枯渇すると、カーネルは調整可能な OOM スコアに基づいて終了対象を選ぶため、ビルドプロセスやデータベースが対象になる可能性があります。ビルドによってディスク上にキャッシュも残ります。ただし、BuildKit はガベージコレクションポリシーに従ってキャッシュを自動的に回収します。ユーザーがいない小規模なプロジェクトであれば、サーバー上でビルドしても問題ありません。build: セクションを開発専用の Compose ファイルに残しておけば、後で移行する際の負担も小さくなります。
Docker のビルドキャッシュによるディスク容量の圧迫を防ぐにはどうすればよいですか?
docker system df を実行すると、image とビルドキャッシュがそれぞれ使用している容量を確認できます。docker builder prune はキャッシュされたレイヤーを削除し、docker image prune は以前のビルドで残った dangling image を削除します。-a を追加すると、未使用のビルドキャッシュをすべて削除するか、コンテナから参照されていない image をすべて削除します。ただし、次回のビルドが完全にキャッシュのない状態になるとは限りません。サーバー上で docker system prune -af --volumes をスケジュール実行しないでください。停止済みコンテナと未使用の anonymous volume も削除されるため、メンテナンス中に anonymous volume 内のデータベースデータが失われる危険があります。