technical-services-exchange/docs/DEPLOYMENT.md

Deployment Notes

This document records the explicit runtime requirements and server changes for Provider Exchange deployments.

Required Runtime

• Linux server.
• Nginx.
• PHP-FPM with PHP ^8.3; PHP 8.5 is acceptable for the current Laravel build.
• PHP extensions required by Laravel and current dependencies:
  • ctype
  • curl
  • dom
  • fileinfo
  • filter
  • hash
  • mbstring
  • openssl
  • pdo
  • pdo_sqlite for SQLite test deployments and the default automated test suite
  • session
  • tokenizer
  • xml
• Composer for clean production installs, or an uploaded vendor/ tree for temporary live testing when Composer is unavailable.
• Node.js/npm only on build machines. The server can receive prebuilt Vite assets in public/build.
• Writable Laravel directories:
  • storage/
  • bootstrap/cache/
  • the SQLite database file for SQLite test deployments.
• Public attachment URLs require php artisan storage:link; the update script now runs it idempotently.
• Attachment policy environment variables:
  • TSE_ATTACHMENT_DISK, default public.
  • TSE_ATTACHMENT_ROOT, default attachments.
  • TSE_ATTACHMENT_MAX_KB, default 10240.
  • TSE_ATTACHMENT_MIME_TYPES, comma-separated allowlist.

Local Test Requirements

• The default PHPUnit configuration uses an in-memory SQLite database, so whichever PHP runtime executes php artisan test must include pdo_sqlite and sqlite3.
• On Windows, php -m should list both PDO and pdo_sqlite; otherwise the feature tests fail before reaching app code with could not find driver.
• WSL Ubuntu is acceptable for local verification when Windows PHP is missing SQLite support, as long as WSL PHP has pdo_sqlite and sqlite3.

Recommended Production Runtime

• Nginx.
• PHP-FPM 8.5 or current supported PHP version satisfying Composer constraints.
• MariaDB/MySQL or PostgreSQL for production data.
• Redis for cache, session, and queue once traffic or notifications grow.
• Supervisor or systemd units for Laravel queue workers.
• Cron entry for php artisan schedule:run.
• Shared/object storage before multi-server deployment.

ChristIT Test Deployment

Target URL:

• https://christit.com/tse

Chosen deployment shape:

• Subdirectory deployment under the existing christit.com certificate.
• App code path: /sites/provider-exchange.
• Public web root exposed through Nginx should be /sites/provider-exchange/public only.
• Existing PHP-FPM socket should be reused: /run/php/php8.5-fpm.sock.
• Do not install or switch PHP 8.3 unless PHP 8.5 proves incompatible.
• Do not alter the existing generic PHP handling for the rest of christit.com.
• Add only a narrow /tse Nginx location and related PHP handler.

Initial test data/runtime:

• SQLite database at /sites/provider-exchange/database/database.sqlite.
• APP_URL=https://christit.com.
• APP_BASE_PATH= for the current Nginx setup, because Nginx passes SCRIPT_NAME=/tse/index.php and Laravel derives the request base from that.
• ASSET_URL=https://christit.com/tse.
• SESSION_PATH=/tse.
• SESSION_DRIVER=database.
• CACHE_STORE=database.
• QUEUE_CONNECTION=database.
• MAIL_MAILER=log.
• TSE_ATTACHMENT_DISK=public.
• TSE_ATTACHMENT_ROOT=attachments.
• TSE_ATTACHMENT_MAX_KB=10240.

ChristIT Deployment Log

2026-07-10:

• Confirmed remote server uses Nginx and PHP 8.5-FPM.
• Confirmed /run/php/php8.5-fpm.sock exists.
• Confirmed tse.christit.com does not currently resolve and no certificate exists for it.
• Chose https://christit.com/tse as the first live test URL.
• Uploaded app source to /home/jbird/provider-exchange-release.
• Installed app source into /sites/provider-exchange.
• Remote Composer was not available in noninteractive SSH; uploaded the local vendor/ tree for this temporary test deployment.
• Installed php8.5-sqlite3 so the isolated SQLite test database can run under the existing PHP 8.5 runtime.
• Added a narrow /tse Nginx block to /etc/nginx/sites-available/christit.com.
• Nginx backups created by the helper include:
  • /etc/nginx/sites-available/christit.com.provider-exchange-tse-20260710-115810.bak
  • /etc/nginx/sites-available/christit.com.provider-exchange-tse-20260710-120003.bak
  • /etc/nginx/sites-available/christit.com.provider-exchange-tse-20260710-120209.bak
  • /etc/nginx/sites-available/christit.com.provider-exchange-tse-20260710-121044.bak
  • /etc/nginx/sites-available/christit.com.provider-exchange-tse-20260710-121151.bak
• Confirmed nginx -t passes after the /tse block was applied.
• Confirmed https://christit.com/tse/ redirects to https://christit.com/tse/jobs.
• Confirmed https://christit.com/tse/login loads with a single-prefix form action.
• Confirmed seeded admin login succeeds and redirects to https://christit.com/tse/dashboard.
• No PHP-FPM version changes have been made.
• No database server changes have been made.
• Installed Composer on the remote server through Ubuntu packages so future updates can install PHP dependencies from composer.lock.
• Converted /sites/provider-exchange from the initial rsync test deployment into a Git checkout of https://github.com/jasonybird/technical-services-exchange.git.
• Preserved the previous rsync deployment at /sites/provider-exchange.pre-git-20260710-125739.
• Preserved the existing production .env, SQLite database, and Laravel storage/ contents during the Git checkout conversion.
• Confirmed remote Git checkout at commit b45a9ec.
• Confirmed bash scripts/update.sh works from the remote Git checkout: Git pull, Composer install, npm install, Vite build, migrations, and Laravel cache rebuild completed successfully.
• Confirmed remote working tree is clean after normalizing copied storage/ placeholder file modes.
• Confirmed authenticated smoke login with admin@example.com reaches https://christit.com/tse/dashboard and renders dashboard count content.