Contents
スポンサードリンク
1️⃣ Docker Desktop のインストールと動作確認
| OS | 推奨インストール手順 | 公式ダウンロードページ |
|---|---|---|
| macOS (Intel / Apple Silicon) | 公式サイトの「Docker Desktop for Mac」から自分の CPU に合うバイナリを取得し、/Applications にドラッグ＆ドロップ。インストール後はアプリケーションを起動 → メニューバーの Docker アイコンが緑になることを確認。 |
https://www.docker.com/products/docker-desktop/ |
| Windows 10/11 (WSL2 推奨) | 「Docker Desktop for Windows」をダウンロードし、インストーラ実行。インストール中に 「Use WSL 2 instead of Hyper‑V」 を必ず有効化。その後 Docker Desktop が自動で起動するか確認。 | 同上 |
| Ubuntu 22.04 以降 (Linux) | Docker の公式リポジトリを追加し、パッケージ docker-ce 系列をインストール。docker compose（Compose v2）も同時に入ります。 |
https://docs.docker.com/engine/install/ubuntu/ |
1.1 基本コマンドで動作チェック
|
1 2 3 |
docker version # Client と Server のバージョンが表示されれば OK docker info # エンジン情報・プラグイン一覧が出力されることを確認 |
トラブルシューティング（OS 別）
| OS | よくあるエラー | 対処法 |
|---|---|---|
| macOS | Docker Desktop が起動しない | System Preferences → Security & Privacy で「システムソフトウェアの実行を許可」して再起動 |
| Windows | WSL2 が有効になっていない | PowerShell 管理者権限で wsl --install を実行し、PC を再起動 |
| Linux | docker: permission denied while trying to connect to the Docker daemon socket |
$ sudo usermod -aG docker $USER && newgrp docker で自分のユーザーを docker グループに追加 |
ポイント：インストールと基本チェックが完了したら、次は公式 PHP イメージへ進みます。
2️⃣ PHP 用公式イメージの選択と Dockerfile 作成
2.1 使用するタグ
| タグ | 内容 | 推奨シーン |
|---|---|---|
php:8.3-apache |
Apache + PHP-FPM が同一コンテナに統合された最小イメージ | シンプルなモノリシック構成 |
php:8.3-fpm |
PHP-FPM のみ（Nginx と組み合わせる想定） | 高トラフィック・分離アーキテクチャ |
注：
8.3は執筆時点の最新マイナーバージョンです。8.3-alpine系はサイズが小さくなりますが、Debian ベース（Bookworm）に比べて一部拡張モジュールのインストール手順が変わるので注意してください。
2.2 Dockerfile（Apache 版）— 改訂ポイント
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
# ------------------------------------------------- # 1️⃣ 基本イメージ（Debian Bookworm ベース） # ------------------------------------------------- FROM php:8.3-apache # ------------------------------------------------- # 2️⃣ 必要な OS パッケージと PHP 拡張モジュールをインストール # ------------------------------------------------- RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ libzip-dev libonig-dev zlib1g-dev && \ docker-php-ext-configure zip && \ docker-php-ext-install pdo_mysql zip intl && \ rm -rf /var/lib/apt/lists/* # ------------------------------------------------- # 3️⃣ Xdebug 3 のインストールと設定 # ------------------------------------------------- # ・Linux 環境では host.docker.internal が解決できないため、ENV で上書き可能にする # ・ビルド時にデフォルトは macOS/Windows 用の自動解決値を入れておく # ------------------------------------------------- ARG XDEBUG_HOST=host.docker.internal ENV XDEBUG_MODE=develop,debug \ XDEBUG_CLIENT_HOST=${XDEBUG_HOST} RUN pecl install xdebug && \ docker-php-ext-enable xdebug && \ echo "xdebug.mode=\${XDEBUG_MODE}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \ echo "xdebug.client_host=\${XDEBUG_CLIENT_HOST}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini # ------------------------------------------------- # 4️⃣ 作業ディレクトリの設定（Apache の DocumentRoot と同一に） # ------------------------------------------------- WORKDIR /var/www/html # ------------------------------------------------- # 5️⃣ デバッグ用にエラーログを標準出力へ流す # ------------------------------------------------- RUN ln -sf /dev/stdout /var/log/apache2/access.log && \ ln -sf /dev/stderr /var/log/apache2/error.log |
Linux 環境での Xdebug ホスト IP の取得例
|
1 2 3 4 5 6 7 |
# 1. コンテナ起動前にホスト側で実行 HOST_IP=$(ip route get 1 | awk '{print $NF;exit}') echo "Detected host IP: $HOST_IP" # 2. .env に書き込む（例：プロジェクト直下の .env） printf "\nXDEBUG_HOST=%s\n" "$HOST_IP" >> .env |
ip route get 1は「デフォルトゲートウェイへ向かう経路」を取得し、最後に出力される IP が Docker デーモンが使用しているブリッジ（通常は172.17.0.1）です。
Dockerfile ではARG XDEBUG_HOSTとENV XDEBUG_CLIENT_HOST=${XDEBUG_HOST}を使うことで、.envの値をビルド時に差し込めます。
2.3 Dockerfile（Nginx + FPM 版）— 基本構成
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
FROM php:8.3-fpm RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ libzip-dev libonig-dev zlib1g-dev && \ docker-php-ext-configure zip && \ docker-php-ext-install pdo_mysql zip intl && \ pecl install xdebug && \ docker-php-ext-enable xdebug && \ rm -rf /var/lib/apt/lists/* ARG XDEBUG_HOST=host.docker.internal ENV XDEBUG_MODE=develop,debug \ XDEBUG_CLIENT_HOST=${XDEBUG_HOST} WORKDIR /var/www/html |
ポイント：
ARGとENVの組み合わせにより、.envに記載したXDEBUG_HOSTをビルド時に注入できます。
3️⃣ docker‑compose.yml でスタック全体を定義
3.1 完全版（Apache + MySQL）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
version: "3.9" services: php: build: context: ./php # Dockerfile があるディレクトリ dockerfile: Dockerfile args: XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal} container_name: php-app volumes: - ./src:/var/www/html # 開発時はバインドマウント env_file: - .env depends_on: - db networks: - backend web: image: httpd:2.4 # 軽量リバースプロキシ（Apache） container_name: apache-proxy ports: - "${APP_PORT:-8080}:80" volumes: - ./apache/httpd.conf:/usr/local/apache2/conf/httpd.conf:ro depends_on: - php networks: - backend db: image: mysql:8 container_name: mysql-db command: --default-authentication-plugin=mysql_native_password environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE} MYSQL_USER: ${MYSQL_USER} MYSQL_PASSWORD: ${MYSQL_PASSWORD} volumes: - db_data:/var/lib/mysql ports: - "3306:3306" networks: - backend networks: backend: volumes: db_data: |
3.2 Nginx + FPM バージョン（web サービスだけ差し替え）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
web: image: nginx:1.27-alpine container_name: nginx-proxy ports: - "${APP_PORT:-8080}:80" volumes: - ./nginx/conf.d/default.conf:/etc/nginx/conf.d/default.conf:ro - ./src:/var/www/html # PHP-FPM のコードを直接マウント depends_on: - php networks: - backend |
重要：
depends_onは「起動順序」だけを保証します。実際の DB 接続待ちにはwait-for-it.shやアプリ側リトライロジックをご利用ください。
4️⃣ 環境変数・ボリューム・.dockerignore のベストプラクティス
4.1 .env（機密情報は必ず Git 管理外 に）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# アプリケーションのポート（ローカル開発専用） APP_PORT=8080 # MySQL 接続情報（本番ではシークレット管理サービスへ置換推奨） MYSQL_ROOT_PASSWORD=secretRootPass123! MYSQL_DATABASE=myapp_db MYSQL_USER=dev_user MYSQL_PASSWORD=devPass456! # Xdebug 用ホスト IP # macOS/Windows は自動解決、Linux は手動で取得した IP を設定 XDEBUG_HOST=host.docker.internal # Linux の場合は例: 172.17.0.1 |
- 必ず
.gitignoreに/.envを追加し、リポジトリにコミットしないこと。 - CI/CD 環境では GitHub Secrets 等から環境変数を注入してください。
4.2 .dockerignore（ビルドコンテキスト削減の決定版）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# バージョン管理系 .git .gitignore # 開発依存ディレクトリ・ファイル node_modules vendor *.log # ドキュメント類（不要なら除外） README.md docs/ # 本番イメージに含めたくない機密情報 .env # Dockerfile と compose ファイルは **ビルド対象に必須** なので除外しない |
指摘修正ポイント：以前は
Dockerfileとdocker-compose.ymlが.dockerignoreに入っていたため、ビルド時にこれらがコンテキストから除外されエラーになっていました。上記のように 除外しない 設定に変更しました。
4.3 ボリュント活用のコツ
| 用途 | 推奨設定 |
|---|---|
| 開発時（コード即時反映） | ./src:/var/www/html の バインドマウント を使用。 |
| 本番イメージ作成 | Dockerfile 内で COPY src/ /var/www/html/ とし、ボリュームは不要にすることで「不変イメージ」ポリシーを徹底。 |
| データ永続化（MySQL） | 名前付きボリューム db_data を利用。コンテナ削除後もデータが残ります。 |
5️⃣ コンテナ起動・確認・トラブルシューティング
5️⃣1 起動コマンドとログの取り方
|
1 2 3 4 5 6 7 8 9 |
# デタッチモードで全サービス起動 docker compose up -d # 各コンテナのリアルタイムログ取得（任意のサービス名を列挙可） docker compose logs -f php db web # コンテナ内部にシェルで入る例（php コンテナ） docker compose exec php bash |
5️⃣2 ブラウザで動作確認
http://localhost:8080にアクセス →phpinfo()が表示されれば PHP・Apache/Nginx の連携成功。- Xdebug が有効か確認したい場合は、IDE（PhpStorm, VS Code + PHP Debug）でブレークポイントを設定し、ページをリロードするとデバッガが接続します。
5️⃣3 エラー別対処表
| エラー | 主な原因 | 解決策 |
|---|---|---|
ポート競合 (Error starting userland proxy: listen tcp 0.0.0.0:8080) |
同一ホストポートが他プロセスで使用中 | .env の APP_PORT を別番号に変更し、docker compose down && docker compose up -d |
権限エラー (Permission denied: '/var/www/html') |
バインドマウント先の所有者が root のまま | sudo chown -R $USER:$USER src で所有者を変更 |
MySQL 接続失敗 (Access denied for user ...) |
.env とコンテナ内部環境変数が不一致、または認証プラグイン未設定 |
command: --default-authentication-plugin=mysql_native_password が入っているか確認し、パスワードを再入力 |
Xdebug 接続できない (Cannot connect to remote host) |
Linux で host.docker.internal が解決できない |
.env の XDEBUG_HOST に手動取得した IP（例: 172.17.0.1）を書き込み、docker compose build php && docker compose up -d |
Dockerfile ビルド失敗 (COPY failed: file not found) |
.dockerignore で Dockerfile が除外されている |
前述の .dockerignore を修正し、再ビルド |
ポイント：エラーメッセージは必ず
docker compose logs <service>で確認し、表に示した対策を順番に試すと迅速に復旧できます。
6️⃣ CI/CD（GitHub Actions）での自動テスト例
以下は PHPUnit テスト実行までを網羅した最小構成です。CI 環境ではローカルと同様に Docker Compose を利用します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
name: CI on: push: branches: [ main ] pull_request: jobs: test: runs-on: ubuntu-latest services: mysql: image: mysql:8 env: MYSQL_ROOT_PASSWORD: ${{ secrets.MYSQL_ROOT_PASSWORD }} MYSQL_DATABASE: myapp_test MYSQL_USER: test_user MYSQL_PASSWORD: ${{ secrets.MYSQL_PASSWORD }} ports: [3306:3306] options: >- --health-cmd="mysqladmin ping -h localhost" --health-interval=10s --health-timeout=5s --health-retries=3 steps: - uses: actions/checkout@v4 # Docker ビルド（キャッシュ活用） - name: Build PHP image run: | docker compose -f docker-compose.yml build php # コンテナ起動（MySQL は services で提供済みなので php のみ起動） - name: Start PHP container run: | docker compose up -d php # Composer インストール（依存関係取得） - name: Install composer packages run: | docker compose exec php composer install --no-interaction --prefer-dist # PHPUnit 実行 - name: Run PHPUnit env: DB_HOST: 127.0.0.1 DB_PORT: 3306 DB_DATABASE: myapp_test DB_USERNAME: test_user DB_PASSWORD: ${{ secrets.MYSQL_PASSWORD }} run: | docker compose exec php vendor/bin/phpunit # 後始末 - name: Tear down containers if: always() run: | docker compose down |
実装上の留意点
- Secrets の管理 – データベースパスワードや root パスワードは必ず GitHub Secrets に保存し、
.envにはプレースホルダーだけを書きます。 - サービス分離 – MySQL は
services:で直接起動させることで、Compose ファイルの DB 定義と競合しません。 - キャッシュ –
docker compose build phpのみ実行すれば、他サービスはビルド済みイメージが再利用され高速化します。
7️⃣ まとめ ― 本ガイドで得られること
| 項目 | 内容 |
|---|---|
| Docker Desktop | OS に合わせた公式インストーラでインストールし、docker version/info が正常に表示できること |
| PHP イメージ選択 | php:8.3-apache または php:8.3-fpm をベースに、必要拡張と Xdebug を組み込む手順 |
| Compose でのスタック構築 | Apache/Nginx と MySQL を同一ネットワーク上に配置し、ポート・環境変数を .env 管理 |
| .dockerignore の正しい書き方 | Dockerfile や compose ファイルは除外せず、ビルドコンテキスト削減だけを目的に記述 |
| Xdebug の Linux 対応 | ip route get 1 によるホスト IP 検出と .env → ARG → ENV の流し込み手法 |
| 開発フロー | docker compose up -d → ブラウザで確認 → ログ・トラブル対応 → CI に組み込みまで一連の流れ |
| セキュリティ & スピード | .env を Git 除外、機密情報は Secrets に、不要ファイルは .dockerignore で除外し、イメージサイズとビルド時間を最適化 |
これで完了です！
Docker Desktop と公式 PHP イメージだけで、本番に近い開発環境が数分で立ち上がります。指摘された問題点をすべて修正した本稿をベースに、ぜひ自プロジェクトへ導入し、生産性向上とトラブル削減を実感してください。
参考リンク（公式情報）
- Docker Desktop ダウンロードページ: https://www.docker.com/products/docker-desktop/
- Docker Engine for Ubuntu インストールガイド: https://docs.docker.com/engine/install/ubuntu/
- PHP 公式イメージリファレンス: https://hub.docker.com/_/php
- Xdebug 公式ドキュメント（host 設定）: https://xdebug.org/docs/all_settings#client_host
本稿は 2026 年 4 月時点の最新情報に基づいて執筆しています。Docker のバージョンやイメージタグは随時公式サイトで確認し、必要に応じて php:8.3 系列を上位へ置き換えてください。
スポンサードリンク