Nginx for Laravel with PHP-FPM: production config, permissions and queues

1. Install PHP

sudo apt install nginx php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-bcmath composer
php -v
ls /run/php/

Change php8.3-fpm.sock in the config if your version differs. A wrong socket name is the usual reason for a 502.

2. Deploy the code

cd /var/www/myapp
composer install --no-dev --optimize-autoloader
cp .env.example .env        # first time only, then fill it in
php artisan key:generate    # first time only
php artisan migrate --force
npm ci && npm run build

In .env, for production:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com

APP_DEBUG=true in production shows your settings and passwords on any error page, so check that one twice.

3. Permissions

PHP has to write in storage and bootstrap/cache, and nowhere else:

sudo chown -R root:www-data /var/www/myapp
sudo find /var/www/myapp -type d -exec chmod 750 {} +
sudo find /var/www/myapp -type f -exec chmod 640 {} +
sudo chown -R www-data:www-data /var/www/myapp/storage /var/www/myapp/bootstrap/cache

Files uploaded by users need a link from public to storage, as Nginx only serves public:

php artisan storage:link

The chmod Calculator explains these numbers.

4. Speed it up

Each of these needs running again after a deploy, or the old values stay in the cache:

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

After config:cache, the app no longer reads .env directly, so calling env() outside config files returns null. Then restart PHP-FPM, which also clears OPcache:

sudo systemctl reload php8.3-fpm

5. Queues and the scheduler

These don’t run by themselves. For the queue, use a service in /etc/systemd/system/myapp-queue.service:

[Unit]
Description=Laravel queue worker
After=network.target

[Service]
User=www-data
WorkingDirectory=/var/www/myapp
ExecStart=/usr/bin/php artisan queue:work --sleep=3 --tries=3 --max-time=3600
Restart=always

[Install]
WantedBy=multi-user.target

The worker keeps your code in memory, so restart it on each deploy, with php artisan queue:restart. The systemd Unit Generator can write a fuller unit.

For the scheduler, add this line with sudo crontab -u www-data -e:

* * * * * cd /var/www/myapp && php artisan schedule:run >> /dev/null 2>&1

If it doesn’t run, see cron job not running.

6. Get HTTPS, and turn it on

sudo certbot certonly --standalone -d example.com \
  --pre-hook "systemctl stop nginx" --post-hook "systemctl start nginx"
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

If that fails, see Certbot failed to authenticate.

Behind Cloudflare or a load balancer, tell Laravel to trust it, or it builds http:// links and can redirect in a loop. Since Laravel 11, this goes in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(at: ['10.0.0.0/8']);
})

Use your proxy’s real address range rather than * where you can.