Step 5: The Web Server Config

Both Caddy and Nginx need to serve from the symlink, not a fixed release.

Caddy

/etc/caddy/Caddyfile:

app.example.com { root * /var/www/app/current/public encode zstd gzip php_fastcgi unix//run/php/php8.3-fpm.sock file_server log { output file /var/log/caddy/app.log } }

Nginx

/etc/nginx/sites-available/app:

server { listen 80; server_name app.example.com; root /var/www/app/current/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass unix:/run/php/php8.3-fpm.sock; fastcgi_split_path_info ^(.+\.php)(/.+)$; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; fastcgi_param DOCUMENT_ROOT $realpath_root; } location ~ /\.(?!well-known).* { deny all; } }

Note $realpath_root instead of $document_root. Without it, Nginx hands FPM the symlink path, and FPM resolves it once and caches the resolved path. Your "atomic" deploy would no-op until FPM was restarted. With $realpath_root, the resolved path goes to FPM on every request and the symlink swap actually takes effect.

Even with that fix, FPM caches opcode for the resolved files. Reloading FPM at the end of the deploy script clears that cache. That's why we run systemctl reload php8.3-fpm.

Step 6: The Queue Worker (Supervisor)

If you run php artisan queue:work, it needs to live under Supervisor or a systemd unit so it restarts on its own and on deploy.

/etc/supervisor/conf.d/laravel-worker.conf:

[program:laravel-worker] process_name=%(program_name)s_%(process_num)02d command=php /var/www/app/current/artisan queue:work --sleep=3 --tries=3 --max-time=3600 autostart=true autorestart=true user=deploy numprocs=2 redirect_stderr=true stdout_logfile=/var/log/laravel-worker.log stopwaitsecs=3600

Reload Supervisor after dropping that in:

sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start laravel-worker:*

If you prefer systemd over Supervisor, a small unit file does the same job. The deploy script already calls systemctl restart laravel-worker.service for that path.

Step 7: Rolling Back

The whole point of this layout is that rollback is trivial. SSH into the server and run:

cd /var/www/app ln -sfn releases/$(ls -1t releases | sed -n '2p') current && sudo systemctl reload php8.3-fpm

That picks the second-most-recent release (the one before the current one) and points current at it. Reload FPM, you're back on the old code. The whole thing takes under a second.

If you want to be explicit, list the releases and pick one by name:

ls -1t /var/www/app/releases ln -sfn /var/www/app/releases/20260501090400 /var/www/app/current sudo systemctl reload php8.3-fpm

Worth knowing: rollback does not undo migrations. If your bad release ran a destructive migration, you've got a separate problem. We'll cover that in "Going Further" below.

Troubleshooting

502 Bad Gateway right after deploy. PHP-FPM cached the resolved path of the old release and is now pointing at files that have been pruned. Make sure your Nginx config uses $realpath_root and that the deploy script reloads FPM. Run sudo systemctl reload php8.3-fpm manually to confirm it clears.

Permission denied on storage/logs/laravel.log. The shared storage directory needs to be writable by the user PHP-FPM runs as (usually www-data). Fix with sudo chown -R deploy:www-data /var/www/app/shared/storage && sudo chmod -R 775 /var/www/app/shared/storage. Set the umask in Supervisor or systemd to 002 if newly written files keep landing with the wrong group.

OPcache serving stale code. Either you didn't reload FPM, or opcache.validate_timestamps=0 is set and the reload isn't reaching the right pool. Confirm with sudo systemctl status php8.3-fpm and check the timestamp on the last reload. As a sanity check, opcache_reset() from a one-off endpoint flushes everything.

Queue workers running old code. They boot the framework once and stay alive. php artisan queue:restart only flags them to exit, it doesn't kill them. They exit after their current job. If your jobs are long-running, give them time, or restart Supervisor directly: sudo supervisorctl restart laravel-worker:*.

composer install fails on the runner with memory errors. Bump the runner to ubuntu-latest-large, or split the steps so composer dump-autoload --optimize runs separately. On free runners, very large dependency trees occasionally hit the 7 GB limit.

Going Further

Forge, Envoyer, and Deployer. All three implement this same atomic-release shape. Laravel Forge provisions the server too, Envoyer focuses purely on zero-downtime deploys, and Deployer is an open-source PHP CLI that does the same job with a deploy.php instead of YAML. If you'd rather click a button than maintain a workflow file, those are the move. The shape we built here is exactly what they automate.

Blue-green deploys. Two full app instances behind a load balancer, deploy to the inactive one, switch traffic. The atomic-symlink pattern is essentially blue-green on a single box. For multi-server setups, a load balancer plus a feature flag on traffic routing gets you full blue-green without much extra plumbing.

DB-safe migration patterns. Atomic releases solve code rollback, not database rollback. The fix is to write expand-then-contract migrations: deploy 1 adds the new column nullable and starts dual-writing, deploy 2 backfills, deploy 3 starts reading from the new column, deploy 4 drops the old one. Slower, but every step is reversible. For destructive changes, take a snapshot before deploying and document the rollback path.

Healthchecks before symlink swap. Add a step in the deploy script that hits /health on the new release (via a dedicated FPM pool) before swapping. If the healthcheck fails, abort the deploy and leave the old release live. Five extra lines of bash, saves you from shipping a broken build.

---

Running Laravel on a VPS and want a fast, predictable host to deploy onto? Our plans run NVMe storage with PHP, Composer, and Node preinstalled. See pricing.