Déploiements Laravel zero-downtime — la pipeline symlink-atomique qui garde les queues honnêtes

Les « déploiements Laravel zero-downtime » le sont rarement. Le répertoire de release est construit à neuf, le symlink est mis à jour atomiquement — jusque-là, ça va — mais les queue workers pointent encore vers l'ancien code, et OPcache sur le PHP-FPM qui tourne n'a pas été reset, donc les requêtes après le swap du symlink peuvent exécuter un mélange d'anciens et nouveaux chemins de code pendant plusieurs secondes.

Voici la pipeline de déploiement que nous livrons et qui rend réellement les déploiements ennuyeux.

Le release directory + symlink atomique

# /var/www/app/
#   releases/
#     2026-05-20-123456/   ← nouveau répertoire de release
#     2026-05-19-090000/   ← précédent, gardé pour rollback
#   current → releases/2026-05-20-123456   ← symlink atomique
 
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 est atomique sur POSIX — Nginx ne voit jamais un symlink à moitié mis à jour. queue:restart dit aux workers de sortir gracieusement après leur job en cours. systemctl reload php8.3-fpm reset OPcache sans laisser tomber les connexions.

L'article complet couvre :

• Pre-deploy composer install — jamais sur l'hôte live, toujours construit ailleurs
• L'histoire de safety des migrations : changements de schéma rétro-compatibles seulement
• Handoff des queue workers — drainer les anciens, démarrer les nouveaux, pas de perte de job
• Timing du reset OPcache par rapport au swap du symlink
• Rollback en 5 secondes : repointer le symlink vers la release précédente
• Le pattern de répertoire shared/ (.env, storage/, uploads persistants)

Nous livrons cette pipeline de déploiement sur chaque client Laravel managé.