Dockerでローカル開発環境を統一する — Docker Composeの実践

「自分のMacでは動くのに、サーバーで動かない」——この問題を減らす有力な手段が Docker です。補助金案件では複数のベンダーや担当者が開発に関わるケースもあり、環境差異によるトラブルは納期・検収・実績報告に影響しやすい論点です。本記事では PHP（Laravel）+ MySQL + Redis を例に、現行の Docker Compose V2（docker compose）に沿った書き方を解説します。

compose.yaml（または docker-compose.yml）の実践的な書き方

Docker は「コンテナ」という軽量な仮想環境でアプリを動かす技術です。開発・テスト・本番で同じコンテナイメージを使うことで、OS やミドルウェアの差異を大きく減らせます。ただし、環境変数・外部サービス・ネットワーク・権限設定などは別途管理が必要です。なお、現行の Compose Specification では compose.yaml が標準ファイル名で、docker-compose.yml も後方互換で読まれます。

# Compose V2 では トップレベル version は obsolete。書かない
services:
  app:
    build:
      context: .
      dockerfile: docker/php/Dockerfile
    volumes:
      - .:/var/www/html
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    environment:
      DB_HOST: db
      REDIS_HOST: redis

  web:
    image: nginx:1.25-alpine
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on: [app]

  db:
    image: mysql:8.0
    # 認証情報は .env で渡す（コミット禁止）。値はリポジトリに直書きしない
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-secret}
      MYSQL_DATABASE: ${MYSQL_DATABASE:-myapp}
      MYSQL_USER: ${MYSQL_USER:-appuser}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-apppass}
    volumes:
      - db_data:/var/lib/mysql
    # ローカルから直接 SQL クライアントで繋ぐ場合のみ override.yaml で公開
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    # 同様にローカルから直接接続する場合のみ override.yaml で公開

volumes:
  db_data:

ポイントは大きく 3 つあります。第一に、Compose V2 では トップレベルの version 指定は obsolete で、書くと警告が出ます。第二に、認証情報はリポジトリに直書きせず .env で渡し、コミット禁止にします（Compose の secrets 機能 も利用できます）。第三に、depends_on 単独ではコンテナ起動を待つだけで MySQL の準備完了は待ちません。service_healthy 条件と healthcheck をセットで使うことで、アプリ起動時の競合を抑えられます。

PHP Dockerfile の最小構成（実案件では必要拡張を追加）

FROM php:8.3-fpm-alpine

RUN apk add --no-cache git curl \
    && docker-php-ext-install pdo pdo_mysql \
    && pecl install redis \
    && docker-php-ext-enable redis

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html

nginx の最小設定

server {
    listen 80;
    root /var/www/html/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass   app:9000;
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include        fastcgi_params;
    }
}

Laravel 開発では zip / unzip / libzip-dev / intl / opcache など、Composer 依存パッケージに合わせて拡張を追加することが多い構成です。必要に応じて apk add、docker-php-ext-install を増やしてください。

よくある落とし穴と対処法

• パーミッション問題：Mac と Linux でユーザー ID が違う → user: "1000:1000" を services に指定するか、.env で UID を渡す
• DB 起動待ち：depends_on はコンテナ起動を待つだけで MySQL の準備完了を待たない → 上記サンプルのように healthcheck ＋ service_healthy を設定するか、wait-for-it.sh を使う
• Apple Silicon Mac の platform 問題：一部イメージが ARM 非対応の場合がある → まず multi-arch 対応イメージを選び、必要な場合のみ platform: linux/amd64 を指定する（エミュレーションで速度低下する点に注意）
• ボリュームのパフォーマンス：Mac でのバインドマウントは遅くなる場合がある → Docker Desktop（macOS 12.5 以降）でデフォルト有効の VirtioFS を前提に、大規模リポジトリでは Compose Watch、Synchronized File Shares、mutagen をプロジェクト規模に応じて併用する（:cached / :delegated は VirtioFS 環境では効果が限定的）

チーム開発と補助金案件での活用ポイント

Docker の大きな価値は、手順を整備すれば誰でも近い環境を短時間で再現しやすくなることです。補助金案件では開発期間中に担当者が変わるケースもあり、環境セットアップの属人化を防ぐことは事業継続性の担保にもなります。チーム合意事項の整理については「プロジェクトのキックオフミーティングで決めるべきこと」もあわせて参照してください。

README に書くべき起動手順（Laravel 構成例。実案件ではプロジェクトに応じて調整）

# 初回セットアップ
git clone https://github.com/yourorg/yourapp
cd yourapp
cp .env.example .env

docker compose up -d
docker compose exec app composer install
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate --seed

# 起動確認
open http://localhost:8080

# 日常操作
docker compose up -d          # 起動
docker compose down            # 停止
docker compose logs -f app     # ログ確認
docker compose exec app sh     # コンテナに入る（Alpine ベースのため bash ではなく sh）

本番との差分を管理する（compose.override.yaml）

ローカルと CI・本番の設定を分けるには 複数 Compose ファイルのマージ機能 を使います。個人差分は .gitignore、チーム共通のローカル設定はリポジトリ管理、という整理が現実的です。

# ローカル開発専用の上書き設定。version は書かない（V2 では obsolete）
services:
  app:
    environment:
      APP_ENV: local
      APP_DEBUG: "true"
      XDEBUG_MODE: debug    # VSCode でブレークポイントを使う場合
  db:
    # ベースでは公開せず、ローカルで直接接続したい時だけここで公開
    ports:
      - "3306:3306"
  redis:
    ports:
      - "6379:6379"

補助金実績報告での活用

補助金の実績報告では、システムの完成・動作・支払を確認できる証拠書類が必要になります。スクリーンショット、公開 URL、管理画面、納品書、検収書、請求書、支払証憑など、制度・経費区分に応じた資料を整理します。Docker 環境であればステージング環境を複製しやすく、事務局確認や社内検収のために成果物を再現しやすくなります。

よくある質問（FAQ）

docker-compose.yml と compose.yaml の違いは？

Compose Specification では compose.yaml が標準ファイル名です。docker-compose.yml も後方互換で読み込まれるため誤りではありませんが、新規プロジェクトでは compose.yaml を選んでおくと現行仕様に沿った構成になります。Compose V2 では docker compose（スペース区切り）コマンドが標準です。

depends_on だけで MySQL の起動待ちはできますか？

できません。depends_on はコンテナの起動順を制御するだけで、MySQL のプロセス準備完了までは待ちません。MySQL 側に healthcheck を設定し、依存側で condition: service_healthy を指定することで、ヘルスチェック通過まで待たせられます。

補助金実績報告で Docker 環境は何に役立ちますか？

実績報告の中心は事務局への成果物確認・支払証憑提出ですが、Docker 環境を整備しておくと、検収日や報告期限のタイミングで画面キャプチャ・動作確認資料を再現しやすくなります。また、開発担当者の交代時にもセットアップ手順を README に集約できるため、補助対象期間中の開発・修正対応の属人化リスクを下げられます。補助金案件のキックオフ論点については「プロジェクトのキックオフミーティングで決めるべきこと」も参考にしてください。

※ 本記事は執筆時点の情報をもとに作成しています。Docker・Docker Compose・各ミドルウェアの仕様やベストプラクティスは変更されることがあります。最新情報は Docker 公式ドキュメント および各ミドルウェアの一次情報をご確認ください。補助金の実績報告に必要な書類は制度・公募回ごとに異なるため、必ず公募要領・手引きで確認してください。