Contents
Docker のインストールと前提条件
Docker がローカルで正しく動作すれば、PHP 8.3 環境の構築は OS に依存せず同一手順で行えます。この章では Docker Desktop（または Docker Engine） のインストール方法と、最低限満たすべきシステム要件を解説します。環境が整うことで、以降の PHP コンテナ構築作業がスムーズに進むことを目的としています。
Docker Desktop（または Docker Engine）のインストール手順
以下では主要な OS 別にインストーラ取得からバージョン確認までの流れを示します。各ステップは公式サイトの指示に従うだけで完了するため、初心者でも安心です。
- Windows
- 対象: Windows 10 Pro/Enterprise（Build 1903 以上）または Windows 11
- 手順: Docker Desktop のインストーラを公式サイトからダウンロードし実行。インストール中に Hyper‑V と WSL2 の有効化が求められます。
- macOS
- 対象: macOS Ventura 以降（Intel/Apple Silicon 両方対応）
- 手順: Docker Desktop for Mac をダウンロードし、ドラッグ＆ドロップでアプリケーションフォルダーに移動。起動時に自動的に必要な仮想化コンポーネントがセットアップされます。
- Linux（Ubuntu 22.04 LTS や CentOS Stream 9 を例示）
- 手順: 公式リポジトリを追加したうえで
apt（Ubuntu 系）またはdnf（CentOS 系）を使いdocker-ceパッケージをインストールします。
インストールが完了したら、ターミナル／PowerShell で以下を実行しバージョン情報が表示されれば成功です。
|
1 2 |
docker version # Docker Engine とクライアントのバージョンが出力されることを確認 |
対応 OS とシステム要件
Docker が安定して動作するために最低限必要なハードウェア・ファームウェア構成は次の通りです。CPU コア数やメモリは推奨値を満たすほど快適に利用できます。
| 項目 | 推奨環境 |
|---|---|
| CPU | 2 コア以上（4 コア推奨） |
| メモリ | 4 GB 以上（8 GB 推奨） |
| ストレージ | 空き容量 10 GB 以上 |
| 仮想化サポート | BIOS/UEFI で VT‑x / AMD‑V を有効化 |
上記要件を満たせば、Docker Desktop のインストール直後に docker compose が利用可能です。
公式 PHP 8.3 イメージの選定とタグの説明
PHP の公式イメージは Docker Hub の php リポジトリで管理されており、定期的にセキュリティパッチやバグ修正が提供されます。この章では 開発向き と 本番向き のタグ選択基準と、代表的なイメージの違いを解説します。
php:8.3‑fpm と php:8.3‑cli の違い
php:8.3-fpm は FastCGI Process Manager が組み込まれた Web 用ランタイムです。一方 php:8.3-cli はコマンドライン実行専用で、Composer やテストスクリプトの実行に適しています。開発環境では両方を併用し、FPM コンテナがリクエスト処理を担当し、CLI コンテナがビルドやユニットテストを実行 する構成が一般的です。
アルパイン vs デビアンベースの選択基準
| タグ | 主な特徴 | 推奨シーン |
|---|---|---|
php:8.3-fpm-alpine |
イメージサイズが約 30 MB と非常に小さく、脆弱性リスクも低い。パッケージ管理は apk。 |
開発・本番共に 軽量化 が最優先の場合。 |
php:8.3-fpm-bullseye |
Debian Bullseye ベースで apt が利用可能。拡張モジュールのインストールが容易。 |
多数の PHP 拡張（例：gd、intl）を追加したい場合や、Alpine ではビルドが困難な PECL パッケージが必要なケース。 |
⚠️ 注意
本稿で示したイメージサイズ（30 MB／70 MB）は執筆時点の概算です。将来的にベースイメージやパッケージ構成が変更されると、実際のサイズは増減します。また、php:8.3系タグは随時マイナーバージョン（例：8.3.12）へ更新されるため、バージョン情報はdocker pull php:8.3-fpm-alpine時点での最新ものが取得されます。運用環境では特定バージョンを固定するタグ（例：php:8.3.12-fpm-alpine）の使用も検討してください。
Dockerfile とマルチステージビルドで最小構成を作る
マルチステージビルドは 開発ツールと本番イメージを分離 でき、不要なファイルやビルド時依存を除外することで軽量かつ安全なコンテナが得られます。この章では「開発ステージ」「本番ステージ」の2段階構成例と、よく使う拡張モジュールのインストール方法を紹介します。
Dockerfile の基本構造
以下は Alpine ベースで作るマルチステージビルドのサンプルです。コメントで各ステップの目的を明示しています。
|
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 |
# ---------- 開発ステージ ---------- FROM php:8.3-fpm-alpine AS builder # 必要なツールと開発用拡張をインストール RUN apk add --no-cache \ $PHPIZE_DEPS \ libzip-dev \ && pecl install xdebug-3.2.0 \ && docker-php-ext-enable xdebug \ && docker-php-ext-install zip pdo_mysql # Composer を公式イメージから取得 COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer WORKDIR /app COPY composer.json composer.lock ./ RUN composer install --no-dev --optimize-autoloader # 本番に不要な dev パッケージは除外 # アプリケーションコードをコピー COPY . . # ---------- 本番ステージ ---------- FROM php:8.3-fpm-alpine AS production WORKDIR /app # ビルダーから最小限のファイルだけを持ち込む COPY --from=builder /app /app # 本番で必要な拡張のみインストール（開発ツールは除外） RUN docker-php-ext-install pdo_mysql zip \ && apk del $PHPIZE_DEPS # ビルド時に入れたパッケージを削除してサイズ削減 # 標準ポートとエントリポイント EXPOSE 9000 CMD ["php-fpm"] |
この構成でビルドすると、本番イメージは約 40 MB（執筆時点）に圧縮されます。実際のサイズはベースイメージやインストールした拡張によって変動するため、docker images コマンドで確認してください。
必要な拡張モジュールと Composer のインストール例
- zip ：Composer が依存パッケージを取得する際に必須。
- pdo_mysql ：MySQL / MariaDB への接続を提供。
- xdebug （開発ステージのみ）：デバッグやコードカバレッジ測定に使用。
プロジェクト固有の要件がある場合は、apk add や docker-php-ext-install の行に追記してください。また、.dockerignore に .git/, tests/, README.md など不要なファイルを列挙すると、ビルド時にコピーされるデータ量が減りさらに軽量化できます。
docker‑compose.yml における php-fpm と Web サーバーの定義
Docker Compose を利用すれば、PHP コンテナと Nginx（または Apache）コンテナをワンコマンドで起動できます。この章では php-fpm と nginx:alpine の連携例を示し、ボリュームマウントや環境変数の扱い方も解説します。
php-fpm と nginx サービスの設定例
以下の docker-compose.yml は、先ほど作成したマルチステージイメージを本番ステージ（target: production）として利用し、ローカルディレクトリをリアルタイムで反映させる構成です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
version: "3.9" services: php: build: context: . target: production # 本番ステージを使用 volumes: - ./src:/app # ソースコードをマウント environment: APP_ENV: development # デバッグ情報の出力などに利用 expose: - "9000" # php-fpm がリッスンするポート nginx: image: nginx:alpine ports: - "${NGINX_HOST_PORT:-8080}:80" volumes: - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro - ./src:/app # PHP が参照する同じディレクトリを共有 depends_on: - php |
nginx の設定ファイル（nginx/default.conf）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
server { listen 80; server_name localhost; root /app/public; # アプリの公開ディレクトリ index index.php index.html; location ~ \.php$ { fastcgi_pass php:9000; # php コンテナ名とポートを指定 include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } } |
この設定により、docker compose up -d で Nginx がホストの 8080 ポート にバインドし、src ディレクトリを共有することでコード変更が即座にコンテナ内へ反映されます。
ソースコードのボリュームマウントとホットリロード
- ボリューム：
./src:/appによってローカルディレクトリとコンテナ内部を同期させ、ファイル更新時に自動的に読み込まれます。 - OPcache の有効化：開発環境でもキャッシュが影響しないよう
.envでOPCACHE_VALIDATE_TIMESTAMPS=1を設定すれば、変更検知が可能です。
環境変数・PHP 設定ファイルのカスタマイズとコンテナ起動手順
環境ごとの差分は .env ファイルにまとめて管理すると、コードベースから機密情報やポート番号を切り離せます。また、php.ini の上書きはボリュームマッピングで簡単に実現できます。
.env ファイルで管理する設定例
プロジェクトルートに .env を作成し、Compose が自動的に読み込みます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# アプリケーション環境 APP_ENV=development # php-fpm の内部ポート（変更不要だが明示） PHP_FPM_PORT=9000 # Nginx の公開ポート NGINX_HOST_PORT=8080 # データベース接続情報（例） MYSQL_ROOT_PASSWORD=example_root_pw MYSQL_DATABASE=myapp |
docker-compose.yml では ${変数名} の形で参照できます。
|
1 2 3 4 5 |
ports: - "${NGINX_HOST_PORT}:80" environment: - APP_ENV=${APP_ENV} |
コンテナ起動と PHP バージョン確認手順
設定が整ったら、以下のコマンドでバックグラウンド起動します。
|
1 2 |
docker compose up -d |
起動後に PHP のバージョンを確認する例です。$(docker ps -qf "name=php") は php サービスのコンテナ ID を取得します。
|
1 2 3 |
docker exec -it $(docker ps -qf "name=php") php -v # 期待される出力例: PHP 8.3.12 (cli) (built: Apr 10 2026 ...) |
バージョンが 8.3 系 と表示されれば、環境構築は完了です。
トラブルシューティングと本番環境向け最適化
Docker と PHP の組み合わせでよく遭遇する問題と、その対処法をまとめました。初心者がハマりやすいポイントを中心に、本番環境でのベストプラクティス も併せて紹介します。
権限エラー・ポート競合・Xdebug 設定の対処法
| 症状 | 主な原因 | 解決策 |
|---|---|---|
Permission denied（ファイル書き込み） |
ホスト側ディレクトリが root 権限で作成されている | docker-compose exec php chown -R www-data:www-data /app もしくは compose に user: "${UID}:${GID}" を追加 |
| ポート 8080 がすでに使用中 | 他のローカルサーバーや過去のコンテナが同ポートを占有 | .env の NGINX_HOST_PORT を別番号（例: 8081）に変更し、compose 再起動 |
| Xdebug が有効にならない | xdebug.mode が未設定、または php.ini が上書きされていない |
コンテナ内で echo 'zend_extension=xdebug.so' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && echo 'xdebug.mode=debug,develop' >> ... を実行し再起動 |
本番向けイメージ最適化のポイント
- 開発ツールは除外
composer install --no-dev、apk del $PHPIZE_DEPSを本番ステージで実行してサイズを削減。- 不要ファイルの削除
.dockerignoreに.git/,tests/,README.mdなどを書き込み、ビルド時にコピーされないようにする。- 最小権限で実行
- Dockerfile の最後に
USER www-dataを追加し、コンテナ内プロセスが root で走らないように設定。 - OPcache と PHP‑FPM のチューニング
- 本番環境では
opcache.memory_consumption=128,pm.max_children=10などをphp.iniに記述し、リソース使用率と応答速度のバランスを最適化。
⚠️ 注意
本稿で示した「約 40 MB 以下」のイメージサイズは、Alpine ベースかつビルドツール・開発用拡張を除外した場合 の目安です。実際の運用環境では追加パッケージやカスタム設定に応じてサイズが変動します。定期的にdocker imagesでサイズを確認し、不要な層が残っていないかチェックしてください。
これらのベストプラクティスを取り入れることで、開発時は柔軟性・デバッグ機能を活用しつつ、本番環境では軽量かつ高速にデプロイできる PHP 8.3 コンテナが実現します。