nginx + PHP-FPM production配備スクリプト群を整備する

[strnh]

背景

現状の quotebuilder は開発環境では稼働できるが、production サーバへ安全かつ再現可能に配置する手順・スクリプト・Webサーバ設定がない。

開発DBは別稼働環境からJSONバックアップを取得して復元できた一方、ユーザーアカウントは復元対象外だった。production運用では、アプリ更新時に .env、SQLite DB、バックアップ、アップロード等の永続データを壊さず、migration前に復旧点を確保できる配備経路が必要。

参考実装:

• strnh/sd_forum/scripts/deploy.sh
• strnh/sd_forum/scripts/.deploy_full.env.example
• strnh/sd_forum/tests/deploy/test_deploy.sh

目的

nginx + PHP-FPM（FastCGI）のproduction環境へ、初回配置・通常更新・検証・コードrollbackを一貫して実行できるスクリプト群と設定例を整備する。

想定構成

• nginx が public/ のみを公開し、PHP-FPMへ index.php をFastCGI転送する。
• release は例として /var/www/quotebuilder/releases/<timestamp-or-commit>/ に配置する。
• /var/www/quotebuilder/current symlinkを正常なreleaseへatomicに切り替える。
• .env、database/database.sqlite、storage/ は shared/ 配下へ永続化し、releaseからsymlinkする。
• deployユーザーとPHP-FPM実行ユーザーを分離し、必要最小限の権限だけを付与する。

パス、ユーザー名、PHP-FPM socket、URL等は環境ファイルで変更可能にし、上記の固定値へ依存させない。

実装対象

配備スクリプト

• scripts/deploy-production.sh
  • set -euo pipefail。
  • target、SSH、必要コマンド、PHP version/extensions、書込権限、共有ファイルをpreflightで検証する。
  • --dry-run、--target、--user、--ref または同等の明示的オプションを持つ。
  • branch / commit / timestamp / target / release pathを開始前に表示する。
  • production用artifactを作成し、.git、node_modules、ローカル .env、ローカルSQLite DB、テスト・一時ファイルを転送対象から除外する。
  • composer install --no-dev --prefer-dist --optimize-autoloader と npm ci && npm run build を再現可能な場所で実行する。productionサーバへNode.jsを必須化しない構成を優先する。
  • shared assetsをsymlinkし、Laravel cache最適化を行う。
  • health check成功後にのみ current を切り替える。失敗時は現行releaseを維持する。
  • deploy version（commit SHA、timestamp）を配置先で確認できるようにする。
  • 世代数または保持日数に基づいて旧releaseを整理する。
• scripts/rollback-production.sh または同等機能
  • 直前の正常releaseへコードを戻せる。
  • DB migrationの自動rollbackは行わず、互換性・復元手順を明示する。
• scripts/.deploy.production.env.example
  • target、remote base、deploy/runtime owner、PHP-FPM socket、health check URL、release保持数等を例示する。
  • secretや実環境の認証情報は含めない。

DB・永続データ保護

• 初回配置ではSQLite DBがなければ安全に作成し、既存DBがあれば上書きしない。
• 通常deployではローカルDBをproductionへ転送しない。
• migration前に対象DB、-wal、-shmの状態を考慮した整合性のあるバックアップを取得し、checksumと保存先をログへ残す。
• php artisan migrate --force の前後でmigration状態を検証する。
• migrate:fresh、seedの暗黙実行、既存DBの置換をproduction deployから禁止する。
• deploy失敗時も .env、SQLite DB、storage/app/private/backups を削除・上書きしない。
• SQLite DB本体と親ディレクトリをPHP-FPMユーザーが必要範囲で書き込めるようにする。chmod 777 は使用しない。

nginx / PHP-FPM設定

• server_config/nginx/quotebuilder.conf.example 等にsite設定例を追加する。
• document rootは current/public とする。
• Laravel front controller向け try_files と fastcgi_pass を設定する。
• 任意の .php ファイルを直接実行させず、原則 index.php のみをFastCGIへ渡す。
• .env、dotfile、database/、SQLite関連ファイル、storage/app/private/、ソース・設定ファイルへのHTTPアクセスを拒否する。
• upload/body size、timeout、ログパス、TLS終端の前提をドキュメント化する。
• nginx -t とPHP-FPM設定検証をdeploy前後に実行できるようにする。

production設定・運用手順

• .env.production.example またはドキュメントで最低限以下を明示する。
  • APP_ENV=production
  • APP_DEBUG=false
  • APP_MODE=production
  • APP_KEY を初回だけ生成し、更新deployで変更しないこと
  • secure cookie / trusted proxy / backup保存先等のproduction設定
• docs/production-deploy.md に以下を記載する。
  • OS package / PHP extension / nginx / PHP-FPMの前提
  • 初回provision、初回deploy、通常deploy、rollback、バックアップ復元
  • 管理者ユーザーの初期作成・再作成手順
  • file ownership / sudoersの最小権限例
  • nginx/PHP-FPM reloadと障害切り分け

テスト

• shell scriptへ bash -n と shellcheck を適用する。
• fixtureまたはsandboxで以下を自動検証する。
  • --dry-run がリモート状態を変更しない。
  • 初回deployが更地から成功する。
  • 同一releaseの再deployが冪等に成功する。
  • 既存SQLite DB・.env・backupが更新後も保持される。
  • migration失敗・health check失敗時に current が切り替わらない。
  • コードrollback後も共有データが保持される。
  • nginx設定で機密パスへアクセスできない。
• 実productionへの破壊的テストを既定で拒否し、sandbox targetを明示した場合だけ実配備テストを許可する安全弁を設ける。

完了条件

• nginx + PHP-FPM環境の更地サーバへ、文書化された手順だけで初回配置できる。
• --dry-run、通常deploy、コードrollbackが実行できる。
• 更新deployで .env、SQLite DB、backup、storageが保持される。
• migration前バックアップとdeploy後health checkが自動実行される。
• deploy途中の失敗で現行releaseが壊れない。
• nginxが public/ 以外と機密ファイルを公開しない。
• production設定で APP_DEBUG=false / APP_MODE=production が検証される。
• shell lint、fixture test、sandbox E2E deployが成功する。
• 配備・rollback・DB復元・管理者作成のrunbookがある。

対象外

• Docker / Kubernetes化。
• multi-node、load balancer、zero-downtime DB migrationの一般化。
• TLS証明書の自動発行（TLS終端の前提と設定箇所の文書化は対象）。
• application dataやユーザーアカウントを開発環境からproductionへ自動転送する機能。