Docker Composeのビルド設計｜buildセクションのcontext・args・キャッシュでイメージ更新を制御する

この記事のポイント

・docker compose buildのbuildセクションでコンテキスト・Dockerfile・引数を一元管理できる
・argsとDockerfileのARGを対応させることでビルド時にcompose.ymlから値を注入できる
・cache_from/cache_toでCI/CDのビルドキャッシュをレジストリに保存・再利用し高速化できる
・--no-cacheフラグとtargetでビルドの再実行と対象ステージを明示的に制御できる

# buildとimageを併用する例
# docker compose buildでビルドしたイメージにタグが自動的に付く
services:
  app:
    build:
      context: .
    image: ghcr.io/example/myapp:latest

# ショートフォーム：compose.ymlと同じディレクトリのDockerfileを使う
services:
  app:
    build: .

# フルフォーム：各パラメータを明示する（推奨）
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile

# ディレクトリ構成例（モノレポ）
myproject/
├── compose.yml
├── frontend/
│   └── Dockerfile
└── backend/
    └── Dockerfile

# モノレポ向けcompose.yml
services:
  frontend:
    build:
      context: ./frontend    # frontendディレクトリ内のファイルがコンテキストになる
      dockerfile: Dockerfile  # contextからの相対パスで指定
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile

# .dockerignoreの例（node_modulesや.gitを除外する）
node_modules
.git
*.log
.env
__pycache__

# ビルド前のコンテキストサイズを--progress=plainで確認する
$ docker compose build --progress=plain 2>&1 | grep "build context"
#1 [internal] load build context
#1 transferring context: 1.23kB done

# .dockerignore適用後は転送サイズが大幅に減る

# Dockerfile側：ARGで受け取る変数名と型を定義する
# デフォルト値を設定しておくとcompose.ymlからの指定がない場合のフォールバックになる
ARG APP_VERSION=0.0.1
ARG BUILD_ENV=development

RUN echo "Building version: ${APP_VERSION} for ${BUILD_ENV}"

# compose.yml側：Dockerfileと同じ変数名でargsに値を設定する
services:
  app:
    build:
      context: .
      args:
        APP_VERSION: "1.2.3"
        BUILD_ENV: production

$ docker compose build --progress=plain
#8 [3/5] RUN echo "Building version: 1.2.3 for production"
#8 0.342 Building version: 1.2.3 for production
#8 DONE 0.4s

# .envファイル（リポジトリにはコミットしないこと）
APP_VERSION=1.2.3
BUILD_ENV=production

# compose.yml：.envの変数を${}で参照する
services:
  app:
    build:
      context: .
      args:
        APP_VERSION: ${APP_VERSION}
        BUILD_ENV: ${BUILD_ENV}

# シンプルなimage参照形式（BuildKitが自動的にキャッシュを取り出す）
services:
  app:
    build:
      context: .
      cache_from:
        - ghcr.io/example/myapp:latest

# ビルドログでキャッシュが使われているかを確認する
$ docker compose build --progress=plain 2>&1 | grep -E "CACHED|RUN "
#5 CACHED [2/5] RUN apt-get update && apt-get install -y build-essential
#6 [3/5] RUN pip install -r requirements.txt

# CAECHEDと表示された命令はスキップされ、RUNのみの命令は再実行されている

# cache_fromとcache_toを組み合わせたCI/CD向け設計
services:
  app:
    build:
      context: .
      image: ghcr.io/example/myapp:latest
      cache_from:
        - type=registry,ref=ghcr.io/example/myapp:buildcache
      cache_to:
        - type=registry,ref=ghcr.io/example/myapp:buildcache,mode=max

# Dockerfileのマルチステージ構成例
FROM python:3.12-slim AS base
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM base AS dev
# 開発用ツールを追加
RUN pip install debugpy pytest

FROM base AS prod
# 本番はbaseから引き継ぎ、追加ツールなしでコンパクトに
COPY . .
CMD ["python", "app.py"]

# compose.yml（開発用）：devステージまでビルドする
services:
  app:
    build:
      context: .
      target: dev
    volumes:
      - .:/app

# compose.prod.yml（本番用）：prodステージでビルドする
services:
  app:
    build:
      context: .
      target: prod

# 本番用設定を重ね合わせて起動する
$ docker compose -f compose.yml -f compose.prod.yml up --build -d

# 全サービスのキャッシュを無視して再ビルドする
$ docker compose build --no-cache

# 特定サービスだけ強制再ビルドする
$ docker compose build --no-cache app

# ビルド後にそのまま起動する場合（--buildは毎回リビルドを強制）
$ docker compose up --build --no-cache -d

# 複数サービスを並列でビルドする
$ docker compose build --parallel

# 並列ビルドのログは--progress=plainで各ステージを追いやすくなる
$ docker compose build --parallel --progress=plain

# NG: FROM以降でARGを再宣言していないため値が空になる
ARG BASE_IMAGE=python:3.12-slim
FROM ${BASE_IMAGE}
RUN echo ${APP_VERSION}   # → ARGがないので空になる

# OK: FROM後にARGを再宣言する（compose.ymlのargsが受け取れる）
ARG BASE_IMAGE=python:3.12-slim
FROM ${BASE_IMAGE}
ARG APP_VERSION           # ← FROM後に再宣言する
RUN echo ${APP_VERSION}   # → compose.ymlのargsの値が入る

# キャッシュを活かす命令順序の設計（依存ファイルを先にCOPYする）
FROM python:3.12-slim
WORKDIR /app
# requirements.txtだけを先にCOPYしてインストール（キャッシュが効く）
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# ソースコードは最後にCOPY（変更頻度が高いので最後に配置）
COPY . .
CMD ["python", "app.py"]