【保存版】Laravel × Docker環境構築を最速で実現する完全ガイド2024

SHARE

目次

目次へ

Docker環境でのLaravel開発のメリット

開発環境の構築は、プロジェクトの成功を左右する重要な要素です。Laravel開発においてDockerを採用することで、多くの利点が得られます。本章では、その具体的なメリットについて詳しく解説していきます。

開発環境の統一による問題解決

開発環境の違いによる問題は、チーム開発における大きな課題の一つです。Dockerを使用することで、以下のような問題を効果的に解決できます：

  • 環境の完全な一致
  • PHP、MySQL、Nginxなどのバージョンを完全に統一
  • 拡張モジュールやライブラリのバージョンも同一に
  • OSの違いに関係なく同じ環境を実現
  • 新規メンバーの参画がスムーズに
  • docker-compose upコマンド一つで環境構築が完了
  • 複雑な設定作業が不要
  • 導入時間の大幅な短縮

本番と環境の一貫性確保

開発環境と本番環境の差異は、デプロイ後のトラブルの主な原因となります。Dockerを使用することで：

  1. 環境の完全な複製が可能
  • 本番環境と同じDockerイメージを使用
  • ミドルウェアの設定も同一に維持
  • 環境依存のバグを事前に発見可能
  1. スケーリングの容易さ
  • 水平スケーリングの事前検証が可能
  • マイクロサービスアーキテクチャへの対応
  • クラウドプラットフォームとの親和性

チーム開発における再現性の向上

Dockerを使用したLaravel開発では、チームメンバー全員が同じ環境で開発を行えます：

バージョン管理の利点

  • アプリケーションコード
  • 環境設定
  • データベース設定
    全てがバージョン管理可能に

CI/CDとの統合

# GitLab CI/CD設定例
stages:
  - test
  - build
  - deploy

test:
  stage: test
  script:
    - docker-compose -f docker-compose.test.yml up -d
    - docker-compose exec app php artisan test

このように、Docker環境でのLaravel開発は、個人開発からチーム開発まで、様々な場面で大きなメリットをもたらします。次章では、この環境を実際に構築する手順について詳しく解説していきます。

Laravel×Docker環境構築の完全手順

本章では、Laravel開発環境をDockerで構築する具体的な手順を解説します。初心者の方でも理解しやすいよう、一つ一つのステップを詳しく説明していきます。

必要なツールのインストール方法

開発を始める前に、以下のツールを準備する必要があります：

  1. Dockerのインストール
  • Docker Desktopをダウンロード
  • OSに応じたインストーラーを実行
  • インストール後、docker --versionで確認
  1. Docker Composeのインストール
  • 最新のDocker Desktopには同梱されています
  • docker-compose --versionで確認

docker-compose.ymlの基本設定

以下が基本的なdocker-compose.ymlの設定例です：

version: '3.8'
services:
  app:
    build:
      context: .
      dockerfile: ./docker/php/Dockerfile
    volumes:
      - .:/var/www/html
    depends_on:
      - db

  web:
    image: nginx: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
    environment:
      MYSQL_DATABASE: laravel
      MYSQL_ROOT_PASSWORD: root
      MYSQL_PASSWORD: password
      MYSQL_USER: laravel
    volumes:
      - db-data:/var/lib/mysql
    ports:
      - "3306:3306"

volumes:
  db-data:

Dockerfile の作成と設定

PHPコンテナ用のDockerfileを作成します（./docker/php/Dockerfile）：

FROM php:8.2-fpm

# システムの依存関係をインストール
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip

# PHP拡張のインストール
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd

# Composerのインストール
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# 作業ディレクトリの設定
WORKDIR /var/www/html

# ユーザー権限の設定
RUN chown -R www-data:www-data /var/www/html

環境変数の設定方法

  1. .envファイルの作成
APP_NAME=Laravel
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost:8080

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=password
  1. 環境構築の実行手順
# プロジェクトディレクトリの作成
mkdir my-laravel-project
cd my-laravel-project

# Dockerコンテナのビルドと起動
docker-compose up -d --build

# Laravelプロジェクトの作成
docker-compose exec app composer create-project laravel/laravel .

# 権限の設定
docker-compose exec app chown -R www-data:www-data storage bootstrap/cache

# アプリケーションキーの生成
docker-compose exec app php artisan key:generate

# データベースのマイグレーション
docker-compose exec app php artisan migrate

これで基本的な環境構築は完了です。http://localhost:8080にアクセスすると、Laravelのウェルカームページが表示されるはずです。

この環境は開発用の基本設定となっています。次章では、この基本設定をさらに改善し、開発効率を向上させるためのベストプラクティスについて解説していきます。

開発効率を上げるDocker設定のベストプラクティス

Docker環境でのLaravel開発をより効率的に行うために、実践的なベストプラクティスをご紹介します。これらの設定を適用することで、開発効率と運用性が大きく向上します。

マルチステージビルドの活用方法

マルチステージビルドを使用することで、開発環境と本番環境で最適化されたイメージを作成できます：

# ビルドステージ
FROM php:8.2-fpm AS builder

RUN apt-get update && apt-get install -y \
    git \
    zip \
    unzip

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

WORKDIR /app
COPY . .
RUN composer install --no-dev --optimize-autoloader

# 本番環境用の最終イメージ
FROM php:8.2-fpm

# 必要な拡張機能のみをインストール
RUN docker-php-ext-install pdo_mysql opcache

# ビルドステージから必要なファイルのみをコピー
COPY --from=builder /app /var/www/html

このアプローチの利点：

  • イメージサイズの最小化
  • ビルド時間の短縮
  • セキュリティの向上

開発環境と本番環境の分離テクニック

異なる環境用のDocker Compose設定を作成します：

docker-compose.yml（共通設定）：

version: '3.8'
services:
  app:
    build:
      context: .
      target: development
    volumes:
      - .:/var/www/html

docker-compose.prod.yml（本番用オーバーライド）：

services:
  app:
    build:
      target: production
    volumes:
      - ./storage:/var/www/html/storage

環境別の起動コマンド：

# 開発環境
docker-compose up -d

# 本番環境
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

ボリュームマウントの最適化

効率的なボリュームマウント設定により、パフォーマンスを向上させることができます：

services:
  app:
    volumes:
      # アプリケーションコード
      - .:/var/www/html
      # Composerキャッシュの永続化
      - composer-cache:/root/.composer/cache
      # node_modulesの分離
      - /var/www/html/node_modules
      # vendorディレクトリの分離（オプション）
      - /var/www/html/vendor

volumes:
  composer-cache:

パフォーマンス最適化のポイント

  1. キャッシュの活用
  • Composerキャッシュの永続化
  • NPMキャッシュの活用
  • PHPのOPcacheの設定
  1. ボリュームマウントの選択的使用
  • 開発中のソースコードのみをマウント
  • ベンダーファイルは必要に応じて分離
  1. 開発用の便利な設定
services:
  app:
    environment:
      PHP_IDE_CONFIG: "serverName=docker"
      XDEBUG_CONFIG: "client_host=host.docker.internal"
    extra_hosts:
      - "host.docker.internal:host-gateway"

これらの設定により：

  • 高速なファイル操作
  • 効率的なキャッシュ管理
  • デバッグのしやすさ
    が実現できます。

実装のベストプラクティス

  1. レイヤーキャッシュの最適化
# 依存関係のインストール
COPY composer.json composer.lock ./
RUN composer install --no-scripts --no-autoloader

# ソースコードのコピー
COPY . .

# オートローダーの最適化
RUN composer dump-autoload --optimize
  1. マルチステージビルドの活用
  • 開発環境用のステージ
  • テスト環境用のステージ
    –

開発効率を上げるDocker設定のベストプラクティス

LaravelとDockerを組み合わせた開発環境をより効率的に運用するために、実践的なベストプラクティスをご紹介します。これらの設定を適切に実装することで、開発効率が大きく向上し、運用コストを削減することができます。

マルチステージビルドの活用方法

マルチステージビルドは、開発環境と本番環境で最適化されたDockerイメージを作成するための強力な手法です。以下に、効果的な実装例を示します：

# ベースイメージとして開発環境を構築
FROM php:8.2-fpm AS development

RUN apt-get update && apt-get install -y \
    git \
    zip \
    unzip \
    libpng-dev \
    libonig-dev \
    libxml2-dev

RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
WORKDIR /var/www/html

# 本番環境用のイメージを最適化
FROM php:8.2-fpm AS production

RUN apt-get update && apt-get install -y \
    libpng-dev \
    libonig-dev \
    libxml2-dev

RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd opcache

COPY --from=development /var/www/html /var/www/html
RUN chown -R www-data:www-data /var/www/html

# 本番環境用の設定を適用
COPY docker/php/production.ini /usr/local/etc/php/conf.d/

マルチステージビルドのメリット：

  • イメージサイズの最適化：本番環境に不要なツールを含めない
  • ビルド時間の短縮：キャッシュレイヤーの効率的な活用
  • セキュリティの向上：開発ツールによる攻撃面の削減

開発環境と本番環境の分離テクニック

環境ごとに最適化された設定を実現するため、Docker Compose設定を適切に分離します：

# docker-compose.base.yml（共通設定）
version: '3.8'
services:
  app:
    build:
      context: .
      target: development
    volumes:
      - .:/var/www/html
    depends_on:
      - db

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: ${DB_DATABASE}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_USER: ${DB_USERNAME}

# docker-compose.dev.yml（開発環境用）
services:
  app:
    environment:
      PHP_IDE_CONFIG: "serverName=docker"
      XDEBUG_MODE: "debug,coverage"
    volumes:
      - .:/var/www/html:cached
      - ./docker/php/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini

# docker-compose.prod.yml（本番環境用）
services:
  app:
    build:
      target: production
    restart: unless-stopped
    volumes:
      - ./storage:/var/www/html/storage

ボリュームマウントの最適化

効率的なボリュームマウント設定は、開発環境のパフォーマンスに大きく影響します：

services:
  app:
    volumes:
      # アプリケーションコード（キャッシュモード有効）
      - .:/var/www/html:cached

      # パフォーマンス向上のための永続化設定
      - composer-cache:/root/.composer/cache
      - node-modules:/var/www/html/node_modules

      # 設定ファイルのマウント
      - ./docker/php/custom.ini:/usr/local/etc/php/conf.d/custom.ini

      # ログと一時ファイルの永続化
      - ./storage:/var/www/html/storage

volumes:
  composer-cache:
  node-modules:

最適化のポイント：

  1. キャッシュ戦略
  • cachedマウントモードの活用
  • 頻繁に変更されないファイルの分離
  • 適切なボリューム永続化
  1. パフォーマンス設定
  • PHP-FPMのプロセス数最適化
  • OPcacheの適切な設定
  • MySQLのチューニング
; php.ini パフォーマンス設定例
opcache.enable=1
opcache.memory_consumption=256
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
  1. 開発効率化のための設定
services:
  app:
    environment:
      # デバッグ設定
      XDEBUG_CONFIG: "client_host=host.docker.internal"
      PHP_IDE_CONFIG: "serverName=docker"

      # 開発環境固有の設定
      APP_ENV: local
      APP_DEBUG: "true"

    extra_hosts:
      - "host.docker.internal:host-gateway"

これらの設定により、以下のような利点が得られます：

  • 開発環境での高速なファイル操作
  • 効率的なキャッシュ管理
  • 快適なデバッグ環境
  • 本番環境との一貫性確保
  • チーム間での環境の統一

実装時の注意点

  1. セキュリティ考慮事項
  • 機密情報は.envファイルで管理
  • 本番環境では不要なポートは公開しない
  • アクセス制御の適切な設定
  1. CI/CD統合のポイント
  • ビルドキャッシュの効果的な活用
  • テスト環境の自動構築
  • デプロイメントの自動化

トラブルシューティングガイド

Docker環境でのLaravel開発中に発生する可能性のある問題とその解決方法を詳しく解説します。このガイドを参考に、効率的なトラブルシューティングを行ってください。

よくあるエラーとその解決方法

1. コンテナ起動時のポート競合

エラーメッセージ:

Error starting userland proxy: listen tcp 0.0.0.0:3306: bind: address already in use

解決策:

  1. 使用中のポートの確認
# Windowsの場合
netstat -ano | findstr :3306

# macOS/Linuxの場合
lsof -i :3306
  1. docker-compose.ymlでポート番号の変更
services:
  db:
    ports:
      - "3307:3306"  # ローカルポートを3307に変更

2. パーミッション関連の問題

症状: storage/logsへの書き込みエラー

解決策:

# コンテナ内でパーミッション設定
docker-compose exec app chmod -R 775 storage bootstrap/cache
docker-compose exec app chown -R www-data:www-data storage bootstrap/cache

3. Composerのメモリ不足エラー

エラーメッセージ:

PHP Fatal error: Allowed memory size of 1610612736 bytes exhausted

解決策:

  1. PHPのメモリ制限を増やす
; php.ini
memory_limit = 2G
  1. Composerコマンドでメモリ制限を指定
COMPOSER_MEMORY_LIMIT=-1 composer require package-name

パフォーマンス最適化のポイント

1. コンテナの起動時間改善

# docker-compose.yml
services:
  app:
    # 健全性チェックの追加
    healthcheck:
      test: ["CMD", "php", "artisan", "--version"]
      interval: 30s
      timeout: 10s
      retries: 3

2. ビルド時間の短縮

  • マルチステージビルドの活用
  • .dockerignoreファイルの最適化
# .dockerignore
node_modules
vendor
*.log
.git
.env*

3. キャッシュの効果的な利用

services:
  app:
    volumes:
      - .:/var/www/html:cached
      - vendor:/var/www/html/vendor
      - node_modules:/var/www/html/node_modules

デバッグ環境の準備方法

1. Xdebugの設定

php.ini設定:

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

docker-compose.yml追加設定:

services:
  app:
    environment:
      XDEBUG_CONFIG: "client_host=host.docker.internal"
      PHP_IDE_CONFIG: "serverName=Docker"

2. デバッグログの設定

services:
  app:
    volumes:
      - ./docker/php/custom.ini:/usr/local/etc/php/conf.d/custom.ini

custom.ini:

error_reporting = E_ALL
display_errors = On
log_errors = On
error_log = /var/log/php/error.log

3. コンテナログの確認方法

# 全コンテナのログを表示
docker-compose logs

# 特定のサービスのログをフォロー
docker-compose logs -f app

# 最新の100行のみ表示
docker-compose logs --tail=100 app

トラブルシューティングのベストプラクティス

  1. システマティックなアプローチ
  • エラーメッセージの詳細な確認
  • ログファイルの解析
  • 環境変数の検証
  • コンテナの状態確認
  1. 問題の切り分け
   # コンテナの状態確認
   docker-compose ps

   # コンテナ内のプロセス確認
   docker-compose top

   # ネットワーク接続の確認
   docker network ls
   docker network inspect [network-name]
  1. デバッグ情報の収集
   # コンテナの詳細情報
   docker inspect [container-id]

   # リソース使用状況
   docker stats

これらのトラブルシューティング手法を習得することで、開発中に発生する問題を効率的に解決できるようになります。次章では、より実践的なDocker活用術について解説していきます。

実践的なDocker活用術

本章では、Laravel×Docker環境をより実践的に活用するための高度なテクニックを紹介します。CI/CDパイプラインの構築から、本番デプロイの自動化、そしてセキュリティ対策まで、実務で必要となる重要な知識を解説します。

CI/CDパイプラインとの連携方法

1. GitHub Actionsでの実装例

# .github/workflows/laravel.yml
name: Laravel CI/CD

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Docker compose up
      run: docker-compose -f docker-compose.ci.yml up -d

    - name: Install Dependencies
      run: docker-compose exec -T app composer install

    - name: Generate key
      run: docker-compose exec -T app php artisan key:generate

    - name: Run Tests
      run: docker-compose exec -T app php artisan test

2. GitLab CIでの実装例

# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

test:
  stage: test
  script:
    - docker-compose -f docker-compose.ci.yml up -d
    - docker-compose exec -T app composer install
    - docker-compose exec -T app php artisan test

build:
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

本番デプロイの自動化テクニック

1. デプロイメントスクリプトの例

#!/bin/bash
# deploy.sh

# 環境変数の読み込み
source .env.prod

# 新しいイメージのプル
docker-compose -f docker-compose.prod.yml pull

# アプリケーションの停止
docker-compose -f docker-compose.prod.yml down

# マイグレーションの実行
docker-compose -f docker-compose.prod.yml run --rm app php artisan migrate --force

# アプリケーションの起動
docker-compose -f docker-compose.prod.yml up -d

# キャッシュのクリア
docker-compose -f docker-compose.prod.yml exec app php artisan cache:clear
docker-compose -f docker-compose.prod.yml exec app php artisan config:clear
docker-compose -f docker-compose.prod.yml exec app php artisan route:clear

2. ゼロダウンタイムデプロイの実装

# docker-compose.prod.yml
services:
  app:
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s
        order: start-first

3. ロールバック戦略

# rollback.sh
#!/bin/bash

# 前回のイメージにロールバック
docker-compose -f docker-compose.prod.yml pull $PREVIOUS_IMAGE
docker-compose -f docker-compose.prod.yml up -d

# データベースのロールバック
docker-compose -f docker-compose.prod.yml exec app php artisan migrate:rollback

セキュリティ対策の実装方法

1. セキュアなDockerfile設定

# 本番環境用Dockerfile
FROM php:8.2-fpm-alpine

# 必要最小限のパッケージのみをインストール
RUN apk add --no-cache \
    postgresql-libs \
    libzip \
    && rm -rf /var/cache/apk/*

# セキュリティ設定
RUN set -ex \
    && adduser -u 1000 -D laravel \
    && chown -R laravel:laravel /var/www/html

# 非rootユーザーとして実行
USER laravel

# 必要なファイルのみをコピー
COPY --chown=laravel:laravel . /var/www/html

2. セキュリティベストプラクティス

  1. コンテナのハードニング
services:
  app:
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
  1. 機密情報の管理
services:
  app:
    secrets:
      - db_password
      - app_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  app_key:
    file: ./secrets/app_key.txt
  1. ネットワークセキュリティ
services:
  app:
    networks:
      - backend
  web:
    networks:
      - frontend
      - backend

networks:
  frontend:
  backend:
    internal: true

モニタリングと運用管理

1. コンテナヘルスチェック

services:
  app:
    healthcheck:
      test: ["CMD", "php", "artisan", "health:check"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

2. ロギング設定

services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

3. メトリクス収集

services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    depends_on:
      - prometheus

これらの実践的なテクニックを適切に組み合わせることで、本番環境でも安定した運用が可能になります。特に、セキュリティ対策は常に最新の脅威に対応できるよう、定期的な見直しと更新が重要です。

前の記事

Laravel Eloquentの完全ガイド：DBアクセスを2…

次の記事

【保存版】LaravelのDB操作完全ガイド2024：設定から…