DockerfileのマルチステージビルドとCompose設計｜本番イメージの軽量化・セキュリティ・環境分離の実践手順

この記事のポイント

・マルチステージビルドで本番イメージを1/10以下に軽量化できる
・Dockerfile設計の鉄則はCOPY --from でビルド成果物だけを本番に持ち込むこと
・コンテナをroot以外のユーザーで動かすことがセキュリティの最低ライン
・Docker Composeのoverride構成で開発・本番の環境差分をコードで管理する

# NG例: ビルドツールが本番イメージに残る
FROM python:3.12
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "app.py"]

# Stage 1: ビルドステージ（builder）
FROM python:3.12-slim AS builder
WORKDIR /build
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# Stage 2: 実行ステージ（本番用）
FROM python:3.12-slim
WORKDIR /app

# builderステージの成果物だけをコピー
COPY --from=builder /install /usr/local

# アプリケーションのソースコードをコピー
COPY app.py .

# rootで動かさない
RUN groupadd -r appuser && useradd -r -g appuser appuser
USER appuser

CMD ["python", "app.py"]

$ docker build -t myapp:prod .
$ docker images myapp
REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
myapp        prod      a3f1b2c4d5e6   2 minutes ago   189MB

# Stage 1: 依存関係の解決
FROM maven:3.9-eclipse-temurin-21 AS deps
WORKDIR /build
COPY pom.xml .
RUN mvn dependency:go-offline

# Stage 2: コンパイル・テスト
FROM deps AS builder
COPY src ./src
RUN mvn package -DskipTests=false

# Stage 3: 実行（JREのみ）
FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /build/target/app.jar .
RUN groupadd -r javauser && useradd -r -g javauser javauser
USER javauser
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

# .dockerignore の例
.git
.env
.env.*
*.log
__pycache__
.pytest_cache
node_modules
README.md

# NG: ソースを先にコピーするとキャッシュが効かない
FROM python:3.12-slim
WORKDIR /app
COPY . .                              # ソース変更のたびにRUNが走る
RUN pip install -r requirements.txt

# OK: 依存関係ファイルを先にコピーしてキャッシュを活用
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .               # requirements.txtが変わらない限りキャッシュ有効
RUN pip install --no-cache-dir -r requirements.txt
COPY . .                              # ソースは最後

# NG: RUNを分けるとレイヤーが3つ増える
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# OK: &&でまとめてレイヤーを1つに
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

# ユーザーとグループを作成
RUN groupadd --gid 1001 appuser && \
    useradd --uid 1001 --gid 1001 --no-create-home appuser

# ファイルの所有者をappuserに変更
RUN chown -R appuser:appuser /app

# 以降の命令はappuserとして実行
USER appuser

# ディレクトリ構成
project/
├── Dockerfile
├── docker-compose.yml          # 共通設定
├── docker-compose.override.yml # 開発環境用（自動適用）
└── docker-compose.prod.yml     # 本番環境用（明示指定）

# docker-compose.yml（共通）
services:
  app:
    image: myapp
    ports:
      - "8080:8080"
    networks:
      - app-net

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: mydb
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - app-net

networks:
  app-net:

volumes:
  db-data:

# docker-compose.override.yml（開発環境・自動適用）
services:
  app:
    build:
      context: .
      target: builder      # マルチステージのbuilderステージで起動
    volumes:
      - .:/app             # ホットリロード用のボリュームマウント
    environment:
      - DEBUG=true
      - DATABASE_URL=postgresql://dev:devpass@db:5432/mydb
    command: ["python", "-m", "uvicorn", "app:app", "--reload"]

  db:
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
    ports:
      - "5432:5432"        # 開発時はホストから直接接続できるようにする

# docker-compose.prod.yml（本番環境・明示指定）
services:
  app:
    build:
      context: .
      target: production   # 本番ステージのみビルド
    environment:
      - DEBUG=false
      - DATABASE_URL=${DATABASE_URL}   # 環境変数から取得（ファイルに書かない）
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M

  db:
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    # 本番ではポートを外に公開しない（appコンテナからのみアクセス）

# 開発環境での起動（docker-compose.override.yml が自動適用）
docker compose up -d

# 本番環境での起動（共通設定＋本番設定を明示）
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-dev}"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    depends_on:
      db:
        condition: service_healthy   # dbがhealthyになるまで待機

# syntax=docker/dockerfile:1

# === Stage 1: 依存関係のインストール ===
FROM python:3.12-slim AS builder

WORKDIR /build

# 依存関係ファイルをコピー（ソースより先）
COPY requirements.txt .

# ビルド用ツールをインストール（builderステージのみ）
RUN apt-get update && \
    apt-get install -y --no-install-recommends gcc libpq-dev && \
    rm -rf /var/lib/apt/lists/* && \
    pip install --no-cache-dir --prefix=/install -r requirements.txt

# === Stage 2: 本番イメージ ===
FROM python:3.12-slim AS production

WORKDIR /app

# ランタイム依存のみインストール
RUN apt-get update && \
    apt-get install -y --no-install-recommends libpq5 && \
    rm -rf /var/lib/apt/lists/*

# builderステージの成果物をコピー（ビルドツールは含まれない）
COPY --from=builder /install /usr/local

# 非rootユーザーを作成
RUN groupadd --gid 1001 appuser && \
    useradd --uid 1001 --gid 1001 --no-create-home appuser

# アプリをコピーして所有者を変更
COPY --chown=appuser:appuser app/ ./app/

# 非rootで実行
USER appuser

# ヘルスチェック
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"

EXPOSE 8080
CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

$ docker build --target production -t myapp:prod .

# サイズを確認
$ docker images myapp:prod
REPOSITORY   TAG    IMAGE ID       CREATED         SIZE
myapp        prod   d4e7f8a9b0c1   30 seconds ago  203MB

# 本番ステージのみビルドしているため、builderステージのgcc等は含まれない
$ docker history myapp:prod | head -10
IMAGE          CREATED         CREATED BY                                      SIZE
d4e7f8a9b0c1   30 seconds ago   CMD ["python" "-m" "uvicorn" "app.main:app"…   0B
      30 seconds ago   EXPOSE 8080                                    0B
      30 seconds ago   HEALTHCHECK ...                                0B
      30 seconds ago   USER appuser                                   0B

# エラー例
failed to solve: failed to read dockerfile: COPY --from requires --from to be a stage name

# 原因: AS で名前をつけていない
FROM python:3.12-slim   # NGの例（AS builderが抜けている）

# 修正: AS で必ずステージ名をつける
FROM python:3.12-slim AS builder

# エラー例
PermissionError: [Errno 13] Permission denied: '/app/logs/app.log'

# 原因: ログディレクトリの所有者がrootのまま

# 修正: USER切替前にchownしておく
RUN mkdir -p /app/logs && \
    chown -R appuser:appuser /app/logs
USER appuser

# 原因: depends_onにconditionを指定していない
depends_on:
  - db             # コンテナ起動を待つだけで、DB接続受付は待たない

# 修正: service_healthyを使う（dbにhealthcheckを設定した上で）
depends_on:
  db:
    condition: service_healthy

次に読む記事

・コンテナとは何か｜Dockerで理解する仮想マシンとの違いと利点
・Docker Compose入門｜複数コンテナでWordPress環境を構築するハンズオン
・Linux ポート確認の全コマンド｜ss・lsof・netstatの使い分け