Lors d’un déploiement Laravel sur un VPS, nous avons rencontré plusieurs problèmes : une erreur 500 sur l’espace d’administration, des problèmes liés aux permissions Laravel, ainsi qu’une erreur de compilation Vite liée à la version de Node.js. Voici la méthode que nous avons utilisée pour identifier et résoudre ces problèmes. 1. Commencer par les logs Laravel Lorsqu’une page Laravel retourne simplement : 500 Internal Server Error il ne faut pas commencer par modifier les routes ou la configuration Nginx au hasard. La première chose à vérifier est le journal Laravel : cd /var/www/portfolio sudo tail -n 100 storage/logs/laravel.log En production, APP_DEBUG est généralement désactivé. Le navigateur ne montre donc pas le détail de l'exception. Le fichier : storage/logs/laravel.log est beaucoup plus utile pour identifier la cause réelle. 2. Vérifier la connexion à la base de données Après le déploiement, il est important de vérifier que Laravel communique correctement avec MySQL. Dans notre cas, nous avons utilisé : sudo -u www-data php artisan migrate:status La commande permet de vérifier l'état des migrations. Lorsque les migrations apparaissent comme : Ran cela confirme notamment que Laravel arrive à communiquer avec la base de données configurée. Si vous devez importer une base SQL existante, utilisez une commande adaptée à votre configuration MySQL : mysql -u root -p portfolio < /var/www/portfolio/public/portfolio.sql Le -p est important : il permet de saisir le mot de passe MySQL. 3. Vérifier les permissions de Laravel Laravel doit pouvoir écrire dans certains répertoires, notamment : storage/ bootstrap/cache/ Sur notre VPS, nous avons corrigé les permissions avec : sudo chown -R www-data:www-data /var/www/portfolio/storage sudo chown -R www-data:www-data /var/www/portfolio/bootstrap/cache Puis : sudo chmod -R 775 /var/www/portfolio/storage sudo chmod -R 775 /var/www/portfolio/bootstrap/cache Cette étape est importante lorsque PHP-FPM utilise l'utilisateur www-data. 4. Nettoyer le cache Laravel Après une modification du .env, des routes ou de la configuration, Laravel peut continuer à utiliser des données mises en cache. Nous avons donc exécuté : sudo -u www-data php artisan optimize:clear Puis reconstruit les caches nécessaires : sudo -u www-data php artisan config:cache sudo -u www-data php artisan route:cache sudo -u www-data php artisan view:cache Cela permet notamment de s'assurer que Laravel utilise bien la configuration actuelle. 5. Vérifier les fichiers frontend générés par Vite Un autre problème rencontré concernait Vite. Nous avons vérifié : ls -lah public/build/ Le répertoire public/build/ n'existait pas. Or, lorsqu'une application Laravel utilise Vite, les ressources frontend doivent être compilées avant la mise en production. La commande à utiliser est : npm run build Mais cette commande a d'abord échoué. 6. Vérifier la version de Node.js Le serveur utilisait initialement : Node.js v18.19.1 alors que la version de Vite utilisée par le projet nécessitait une version plus récente de Node.js. La compilation retournait notamment une erreur indiquant que Node.js était trop ancien. Après la mise à jour de Node.js, nous avons obtenu : node -v v22.23.2 et : npm -v 10.9.8 Nous pouvions alors utiliser une version compatible avec Vite. 7. Réinstaller les dépendances npm Après la mise à jour de Node.js, nous avons supprimé les anciennes dépendances : rm -rf node_modules rm -f package-lock.json Puis réinstallé les dépendances : npm install Une première tentative a rencontré une erreur réseau : npm error code ETIMEDOUT npm error network read ETIMEDOUT Il ne s'agissait pas d'un problème Laravel, mais d'un problème de connexion lors du téléchargement des paquets npm. Après avoir relancé l'installation avec une connexion fonctionnelle, les dépendances ont pu être installées. 8. Compiler les assets pour la production Une fois les dépendances installées : npm run build a permis de générer les fichiers frontend nécessaires. Nous avons ensuite vérifié : ls -lah public/build/ et : test -f public/build/manifest.json && echo "MANIFEST OK" Le fichier manifest.json confirme que Vite a correctement généré les assets de production. 9. Nettoyer une dernière fois Laravel Après la compilation des assets, nous avons effectué un dernier nettoyage : sudo -u www-data php artisan optimize:clear Puis : sudo -u www-data php artisan config:cache sudo -u www-data php artisan route:cache sudo -u www-data php artisan view:cache Et nous avons vérifié les permissions : sudo chown -R www-data:www-data storage bootstrap/cache sudo chmod -R 775 storage bootstrap/cache Conclusion Une erreur 500 après le déploiement d'une application Laravel ne signifie pas nécessairement que le code de l'application est incorrect. Dans notre cas, le diagnostic a nécessité de vérifier plusieurs éléments : les logs Laravel ; la connexion MySQL ; les permissions de storage et bootstrap/cache ; le cache Laravel ; la version de Node.js ; l'installation des dépendances avec npm ; la compilation des ressources avec Vite ; la présence de public/build/manifest.json. La méthode la plus efficace est donc de procéder étape par étape : identifier l'erreur dans les logs, vérifier l'environnement serveur, corriger le problème, puis reconstruire les caches et les assets de production. Cette démarche permet d'éviter de modifier inutilement Nginx, les routes Laravel ou le code de l'application alors que le problème peut simplement venir de l'environnement de production. Commandes utiles à retenir # Voir les erreurs Laravel sudo tail -n 100 storage/logs/laravel.log # Vérifier les migrations sudo -u www-data php artisan migrate:status # Corriger les permissions sudo chown -R www-data:www-data storage bootstrap/cache sudo chmod -R 775 storage bootstrap/cache # Nettoyer Laravel sudo -u www-data php artisan optimize:clear # Installer les dépendances frontend npm install # Compiler Vite npm run build # Vérifier le build ls -lah public/build/ test -f public/build/manifest.json && echo "MANIFEST OK" # Recréer les caches sudo -u www-data php artisan config:cache sudo -u www-data php artisan route:cache sudo -u www-data php artisan view:cache