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

この記事のポイント

・マルチステージビルド＋distrolessで本番イメージを1/10以下に軽量化できる
・Dockerfile設計の鉄則はCOPY --from でビルド成果物だけを本番に持ち込むこと
・GoはCGO_ENABLED=0＋distroless/staticでバイナリ1本分のイメージを作れる
・コンテナをroot以外のユーザーで動かすことがセキュリティの最低ライン
・.envファイルは自動読み込みされるがGitに含めてはいけない——認証情報はファイルで分離する
・Composeのoverride構成とprofilesで開発・本番・CI環境を1ファイル体系で管理できる

# 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 /app

COPY requirements.txt .
# venvをビルドステージで作成してpip install
RUN python -m venv /opt/venv \
    && /opt/venv/bin/pip install --upgrade pip \
    && /opt/venv/bin/pip install --no-cache-dir -r requirements.txt

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

# builderステージのvenvディレクトリだけをコピー（gccなどは含まれない）
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

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

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

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

# ステージ名で参照する方法（推奨: Dockerfileを編集しても壊れない）
COPY --from=builder /opt/venv /opt/venv

# ステージ番号で参照する方法（0始まり: 行順変更で壊れやすいため非推奨）
COPY --from=0 /opt/venv /opt/venv

# 外部イメージから直接コピーする方法（設定ファイルの取り込みなどに使う）
COPY --from=nginx:1.25 /etc/nginx/nginx.conf /etc/nginx/nginx.conf

$ 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"]

# イメージサイズの比較（Flaskアプリ・同一requirements.txt）
$ docker images | grep flaskapp
REPOSITORY   TAG          IMAGE ID       CREATED         SIZE
flaskapp     ubuntu       a1b2c3d4e5f6   2 minutes ago   354MB
flaskapp     slim         b2c3d4e5f6a7   3 minutes ago   112MB
flaskapp     alpine       c3d4e5f6a7b8   4 minutes ago    58MB
flaskapp     distroless   d4e5f6a7b8c9   5 minutes ago    38MB

# trivyによるHIGH+CRITICAL脆弱性スキャン結果
$ trivy image --severity HIGH,CRITICAL flaskapp:ubuntu 2>&1 | tail -3
Total: 48 (HIGH: 35, CRITICAL: 13)

$ trivy image --severity HIGH,CRITICAL flaskapp:slim 2>&1 | tail -3
Total: 12 (HIGH: 9, CRITICAL: 3)

$ trivy image --severity HIGH,CRITICAL flaskapp:alpine 2>&1 | tail -3
Total: 3 (HIGH: 2, CRITICAL: 1)

$ trivy image --severity HIGH,CRITICAL flaskapp:distroless 2>&1 | tail -3
Total: 0 (HIGH: 0, CRITICAL: 0)

# Stage 1: ビルドステージ（slim で pip install を実行）
FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install --upgrade pip
COPY requirements.txt .
# --target でインストール先ディレクトリを指定
RUN pip install --no-cache-dir --target /app/packages -r requirements.txt

# Stage 2: 実行ステージ（distroless: シェルなし・最小構成）
FROM gcr.io/distroless/python3-debian12
WORKDIR /app
# builderからインストール済みパッケージだけをコピー
COPY --from=builder /app/packages /app/packages
COPY . .
# PYTHONPATHでパッケージの場所を指示
ENV PYTHONPATH=/app/packages
# distrolessはシェルがないのでexec形式（JSON配列）で書く
CMD ["/usr/bin/python3", "/app/app.py"]

FROM golang:1.22-alpine AS builder

WORKDIR /app
# モジュールキャッシュを先に取得（Dockerfileのキャッシュ効率化）
COPY go.mod go.sum ./
RUN go mod download

COPY . .
# CGO_ENABLED=0: スタティックリンク（外部ライブラリ依存なし）
# -ldflags="-w -s": デバッグ情報を削除してバイナリを最小化
RUN CGO_ENABLED=0 GOOS=linux go build \
    -ldflags="-w -s" \
    -o /app/bin/server ./cmd/server

# distroless/static: シェルもlibcも含まない・CA証明書のみ内包
FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/bin/server /server
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/server"]

# ビルド結果の確認（Rocky Linux 9.4 / Docker 25.0.5）
$ docker build -t myapp-go:prod .
$ docker images myapp-go:prod
REPOSITORY   TAG    IMAGE ID       CREATED         SIZE
myapp-go     prod   a3f912d8c401   30 seconds ago  22.3MB

# .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 . .                              # ソースは最後

# Go: go.mod / go.sum を先にコピーしてキャッシュを効かせる
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./    # 依存定義ファイルを先にコピー
RUN go mod download      # ここまでのキャッシュはソース変更では壊れない
COPY . .                 # ソースコードはあとに COPY
RUN CGO_ENABLED=0 GOOS=linux go build -o /app/bin/server .

# 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

# Go製アプリのscratch構成（静的バイナリを使う例・CA証明書不要な場合）
FROM golang:1.22-alpine AS builder
WORKDIR /build
COPY . .
# CGO_ENABLED=0で完全静的バイナリ（glibc依存なし）を生成
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o app .

# scratchに静的バイナリだけをコピー
FROM scratch
COPY --from=builder /build/app /app
ENTRYPOINT ["/app"]

# docker-compose.yml — 可読性は高いがパスワードを書いてはいけない
services:
  web:
    image: nginx:alpine
    environment:
      - APP_ENV=development
      - LOG_LEVEL=debug
      - APP_PORT=8080

services:
  app:
    image: myapp:latest
    env_file:
      - .env.common       # 全環境共通の設定
      - .env.development  # 開発環境固有の設定（上書き）

# ディレクトリ構成
.
├── docker-compose.yml
├── .env.example          # リポジトリに含める（値は空またはダミー）
├── .env.development      # ローカル開発用（.gitignore対象）
└── .env.production       # 本番用（.gitignore対象・サーバー上にのみ置く）

# .gitignore に追加（要注意: 追加しないとGit経由で認証情報が漏洩する）
.env
.env.development
.env.production
.env.staging

# .env.example（値はダミーまたは空。リポジトリに含める）
DB_HOST=
DB_PORT=5432
DB_NAME=
DB_USER=
DB_PASSWORD=
APP_ENV=
SECRET_KEY=
DATABASE_URL=

# 開発環境での起動
docker compose --env-file .env.development up -d

# 本番環境での起動
docker compose --env-file .env.production up -d

# 展開後の設定を本番デプロイ前に必ず確認する
docker compose --env-file .env.production config | grep -A5 environment

# Dockerfile: ARGはビルド時のみ有効、ENVは実行時も有効
ARG APP_VERSION=latest     # ビルド時のみ参照可能
ENV APP_ENV=production     # コンテナ実行時も参照できる

# docker-compose.ymlでARGに値を渡す（buildセクション）
services:
  app:
    build:
      context: .
      args:
        APP_VERSION: ${APP_VERSION}  # .envから取得

# ディレクトリ構成
project/
├── Dockerfile
├── docker-compose.yml          # 共通設定
├── docker-compose.override.yml # 開発環境用（自動適用）
├── docker-compose.ci.yml       # CI環境用（明示指定）
└── 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"        # 開発時はホストから直接接続できるようにする

  phpmyadmin:
    image: phpmyadmin:latest
    ports:
      - "8081:80"
    environment:
      - PMA_HOST=db

# docker-compose.ci.yml（CI環境用オーバーライド）
services:
  app:
    environment:
      - APP_ENV=test
      - DATABASE_URL=postgresql://root:test@db/testdb

  db:
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: test
      POSTGRES_DB: testdb
    tmpfs:
      - /var/lib/postgresql/data  # CI はtmpfsで高速化（永続化不要）

# ローカル開発（docker-compose.override.yml が自動マージ）
docker compose up -d

# 本番（-f で明示指定）
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# CI（-f で明示指定）
docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d

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

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

services:
  app:
    image: myapp:latest
    ports:
      - "8080:80"
    # profiles を指定しないサービスは常時起動

  db:
    image: postgres:16
    # profiles を指定しないので常時起動

  phpmyadmin:
    image: phpmyadmin:latest
    ports:
      - "8081:80"
    profiles:
      - dev              # dev プロファイル指定時のみ起動

  mailhog:
    image: mailhog/mailhog
    ports:
      - "8025:8025"
    profiles:
      - dev              # dev プロファイル指定時のみ起動

# 通常起動（--profile なし）: app と db だけ起動
$ docker compose up -d
[+] Running 2/2
 ✔ Container myapp-db-1   Started
 ✔ Container myapp-app-1  Started

# dev プロファイルを有効にして起動: phpmyadmin と mailhog も起動
$ docker compose --profile dev up -d
[+] Running 4/4
 ✔ Container myapp-db-1           Started
 ✔ Container myapp-app-1          Started
 ✔ Container myapp-phpmyadmin-1   Started
 ✔ Container myapp-mailhog-1      Started

# 環境変数で指定（.env ファイルに書いても有効）
export COMPOSE_PROFILES=dev
docker compose up -d

# 複数プロファイルをカンマ区切りで指定
export COMPOSE_PROFILES=dev,monitoring
docker compose 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"]

# venvパターン（ネイティブ拡張が不要なPythonアプリ向け）

# === Stage 1: venvで依存をインストール ===
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN python -m venv /opt/venv \
    && /opt/venv/bin/pip install --upgrade pip \
    && /opt/venv/bin/pip install --no-cache-dir -r requirements.txt

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

# venvディレクトリだけをコピー（gccなどは一切含まれない）
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

WORKDIR /app
COPY --chown=appuser:appuser app/ ./app/

RUN groupadd --gid 1001 appuser && \
    useradd --uid 1001 --gid 1001 --no-create-home appuser
USER appuser

EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

$ 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

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

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

# NG: ステージ名の大文字・小文字が不一致
FROM python:3.12-slim AS Builder
...
COPY --from=builder /install /usr/local   # 小文字b でエラー

# OK: 大文字・小文字を完全一致させる（ステージ名は小文字に統一推奨）
FROM python:3.12-slim AS builder
...
COPY --from=builder /install /usr/local

# エラー例
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

# エラー例
WARN[0000] The "DB_PASSWORD" variable is not set. Defaulting to a blank string.

# 確認1: .envファイルが存在するか
ls -la .env

# 確認2: docker compose configで変数展開を確認
docker compose config

# 対処: デフォルト値を設定する（変数未設定時に使われる）
# docker-compose.yml内での記法
environment:
  - DB_HOST=${DB_HOST:-localhost}

# glibcリンクのバイナリがalpine（musl）で動かない場合のエラー例
standard_init_linux.go:228: exec user process caused: no such file or directory

# 動的リンクの依存関係を確認する
$ ldd /usr/local/bin/myapp
        linux-vdso.so.1 (0x00007fff...)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f...)

# シェル形式のCMDがdistrolessで失敗するエラー例
Error response from daemon: failed to create task for container:
exec: "sh": executable file not found in $PATH

# NG: シェル形式（distrolessでは使えない）
CMD python app.py

# OK: exec形式（JSON配列形式）で書く
CMD ["/usr/bin/python3", "/app/app.py"]

# デバッグが必要な場合は:debugバリアントを使う
# FROM gcr.io/distroless/python3-debian12:debug
# → busyboxシェルが含まれており、docker exec でshが使える
$ docker exec -it myapp sh

# NG: -f を使うと override.yml が読まれない
docker compose -f docker-compose.prod.yml up -d

# OK: 共通ファイルを先頭に明示する
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# docker-compose.yml
services:
  app:
    ports:
      - "8080:80"

# compose.override.yml に追加した場合
services:
  app:
    ports:
      - "9090:80"    # 上書きではなく追加になる

# 実際のポートマッピング（docker compose config で確認）
# ports:
#   - "8080:80"      # 共通ファイルのポート
#   - "9090:80"      # override.yml のポート（両方が公開される）

# マージ後の完全な設定を出力
$ docker compose config

# 本番用ファイルを指定した場合のマージ結果を確認
$ docker compose -f docker-compose.yml -f docker-compose.prod.yml config

# 起動対象のサービス一覧だけを確認
$ docker compose config --services
app
db

次に読む記事

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