Despliegues Laravel sin downtime — el pipeline de symlink atómico que mantiene honestas las colas

Los «despliegues Laravel sin downtime» rara vez lo son. El release directory se construye nuevo, el symlink se actualiza atómicamente — hasta ahí bien — pero los queue workers siguen apuntando al código viejo, y OPcache en el PHP-FPM que corre no se ha reseteado, así que las peticiones tras el swap del symlink pueden ejecutar una mezcla de paths de código viejos y nuevos durante varios segundos.

Este es el pipeline de despliegue que entregamos y que de verdad hace los despliegues aburridos.

El release directory + symlink atómico

# /var/www/app/
#   releases/
#     2026-05-20-123456/   ← nuevo release directory
#     2026-05-19-090000/   ← anterior, conservado para rollback
#   current → releases/2026-05-20-123456   ← symlink atómico
 
cd /var/www/app/releases
git clone --depth 1 git@github.com:org/app.git 2026-05-20-123456
cd 2026-05-20-123456
composer install --no-dev --optimize-autoloader
ln -s /var/www/app/shared/.env .env
ln -s /var/www/app/shared/storage storage
 
php artisan migrate --force --no-interaction
php artisan event:cache
php artisan route:cache
php artisan view:cache
 
ln -nfs /var/www/app/releases/2026-05-20-123456 /var/www/app/current
php artisan queue:restart
sudo systemctl reload php8.3-fpm

ln -nfs es atómico en POSIX — Nginx nunca ve un symlink a medio actualizar. queue:restart dice a los workers que salgan graciosamente tras su job actual. systemctl reload php8.3-fpm resetea OPcache sin caer conexiones.

El artículo completo cubre:

Pre-deploy composer install — nunca en el host live, siempre construido en otro sitio
La historia de seguridad de migraciones: solo cambios de esquema compatibles hacia atrás
Handoff de queue workers — drenar los viejos, arrancar los nuevos, sin pérdida de jobs
Timing del reset de OPcache respecto al swap del symlink
Rollback en 5 segundos: re-apuntar el symlink a la release anterior
El patrón de directorio shared/ (.env, storage/, uploads persistentes)

Entregamos este pipeline de despliegue en cada cliente Laravel gestionado.