Deployment

Nginx serves the files in public/ and passes everything else to index.php over FastCGI. The configuration below is the one from the Laravel documentation, with the FPM container’s address and $realpath_root:

Source: Laravel — Nginx

PHP-FPM clears the environment of its workers by default, so variables are set in the pool configuration. The first version of this file stopped FPM from starting at all:

Source: PHP — FPM Configuration

FPM parses pool files as INI, where a bare false is a boolean and env[...] needs a string. Quoting every value fixed it. Real secrets usually come from the environment or a secrets manager rather than a file in the image (Security: CSRF, Encryption and Hashing covers encrypted .env files).

The first requests through the stack:

Source: Laravel — Directory Permissions

Directory permissions. FPM workers run as www-data (uid 33), and storage/ and bootstrap/cache belonged to root. Blade could not write a compiled view and PHP fell back to /tmp, which Laravel turns into an exception. chown -R www-data:www-data storage bootstrap/cache fixed it, as would a chmod for a deploy user in the www-data group. The next failure was filemtime(): stat failed for /tmp/claude-0/…/storage/framework/views/…: compiled views from the development machine referred to its absolute paths. php artisan optimize:clear removed them. Caches are built on the server, or in the image at the final path, never copied from development.

php artisan optimize caches the configuration, routes, events and compiled views. Without caches, every request reads config/*.php, registers every route and scans for listeners. OPcache keeps compiled PHP in shared memory, and with opcache.validate_timestamps=0 it stops checking files for changes. Two hundred requests to /books after 20 warm-up requests, on each setup:

Source: Laravel — Optimization

optimize cut the median by about 30% on a page that runs two queries, and OPcache without timestamp checks took off a little more. config:cache has one consequence that catches people: env() returns null outside config/ files once the cache exists (Directory Structure and Configuration).

Without timestamp checks, nothing changes until PHP-FPM reloads. A /version route was added and php artisan route:cache rebuilt the route file twice, with release v1 and then release v2:

Source: PHP — opcache.validate_timestamps

The new bootstrap/cache/routes-v7.php was on disk, but OPcache served the copy it had compiled at the first request. A graceful reload (systemctl reload php8.5-fpm, or USR2 to the master) is therefore part of every deploy on such a server.

Zero-downtime deploys build each release in its own directory, run composer install --no-dev --optimize-autoloader, npm run build, php artisan migrate --force and php artisan optimize there, and then point a current symlink at it with an atomic rename (ln -sfn releases/2 current.tmp && mv -T current.tmp current). Two Nginx servers in front of the same FPM pool, one passing $document_root (the symlink path) and one $realpath_root (the resolved directory), each served a one-line release:

Source: nginx — $realpath_root

With $document_root, PHP received /srv/app/current/public/index.php, and its realpath cache and OPcache had already resolved that to release 1. It kept serving the old release, even with timestamp checks on, until the cache expired or FPM reloaded. With $realpath_root, Nginx resolves the symlink itself, PHP sees the new path, and the switch is immediate. Envoy (laravel/envoy), Deployer and Forge’s zero-downtime deployments all automate this layout. storage/ and .env live in a shared directory linked into each release.

Schema changes must work with both releases during the switch. A column is added in one release and used in the next, and a column is dropped only after no running code reads it. The ordering patterns are on Schema Evolution Best Practices.

Workers, the scheduler loop, Reverb and Octane keep the old code in memory, so every deploy must restart them. php artisan reload signals all of them at once. In Bookshelf it reported:

Source: Laravel — Reloading Services

The command only asks the processes to exit after their current work. A process monitor starts them again with the new release. Horizon is restarted with php artisan horizon:terminate. With systemd:

Source: Laravel — Deploying Horizon

The same shape works for php artisan reverb:start and php artisan queue:work, or Supervisor can be used as on Queues and Jobs. WorkingDirectory points at current, so a restarted process picks up the new release. TimeoutStopSec must exceed the longest job. The scheduler is the single cron line from Task Scheduling, on one server or with onOneServer() tasks on all of them.

FrankenPHP is Caddy with PHP embedded, so one process replaces Nginx and FPM and handles HTTPS certificates itself. frankenphp php-server --root public served Bookshelf from the official dunglas/frankenphp:php8.5 image:

Source: Laravel — FrankenPHP

The 400 came from Bookshelf itself. trustHosts(at: ['^bookshelf\.test$']) from Middleware rejects any other Host header in production. That protects password-reset links and redirects from host header injection, but it also refuses a load balancer’s health check that uses the IP address, so the health check must send the real host name. Without worker mode, FrankenPHP was about as fast as Nginx and FPM (10.7 against 9.5 ms). Worker mode through Octane, which keeps the application booted, is where it differs (Octane and Performance).

Laravel Cloud runs Laravel applications without servers to manage: it builds from Git and runs web, workers and the scheduler. It also provides managed databases, Redis-compatible caches and object storage, scales automatically and reloads services itself. Laravel Forge provisions and manages servers on a provider such as AWS, DigitalOcean or Hetzner, with Nginx, PHP-FPM, Supervisor, cron and zero-downtime deployments configured as above. Vapor deploys to AWS Lambda. These platforms remove the work on this page, at a price per month. Containers on a cloud platform, such as ECS and Fargate (ECS and Fargate) or Kubernetes (Kubernetes), are the self-managed alternative, with the image from Docker and Sail.