Guide de dépannage des serveurs Web ServBay

ServBay prend en charge Caddy, NGINX et Apache comme serveurs Web par défaut, vous offrant un environnement de développement local flexible. Lors de son utilisation, il se peut que vous rencontriez des difficultés telles que l’inaccessibilité du site, des chargements lents ou des erreurs (comme la fameuse erreur interne du serveur 500). Ce guide vise à vous aider à diagnostiquer et à résoudre les problèmes courants liés aux serveurs Web dans l’environnement ServBay.

Utiliser l’outil de diagnostic intégré à ServBay

ServBay propose un outil de diagnostic intégré puissant capable de détecter automatiquement et d’indiquer les problèmes courants de configuration ou de service. Il est fortement recommandé de commencer par cet outil en cas de problème.

Ouvrez l’application ServBay et, dans la barre de navigation à gauche, cliquez sur « Diagnostic des pannes » pour accéder à l’outil intégré.

L’outil vérifie l’état des composants essentiels, les ports occupés, la syntaxe des fichiers de configuration et fournit des recommandations qui facilitent la localisation rapide des problèmes.

Lenteur lors du premier accès au site après la migration depuis MAMP ou Laravel Herd

Si, après avoir migré de MAMP ou Laravel Herd vers ServBay, vous constatez que votre site met plus de 5 secondes à répondre lors du premier accès après une période d’inactivité, alors que les accès suivants sont normaux, et que la lenteur revient après un temps sans accès…

Symptômes du problème

Ouvrez les outils de développement de Chrome (touche F12 ou Cmd+Option+I), allez dans l’onglet Network (Réseau), rafraîchissez la page et observez les détails dans la section Timing du ou des requêtes : le temps attribué à DNS Lookup sera d’environ 5 secondes.

(Illustration : Visualisation du temps DNS Lookup dans l’onglet Network de Chrome DevTools)

Cause du problème

MAMP et Laravel Herd modifient la configuration DNS de macOS lors de leur installation, en créant des fichiers de configuration de résolveur DNS spéciaux, destinés à intercepter certains suffixes de domaine (*.test, *.local, etc.), généralement dans le répertoire /etc/resolver/.

Même après la désinstallation de MAMP ou Herd, ces fichiers de résolveur peuvent rester. Lorsqu’un site utilise un suffixe géré (par ex. .test), macOS tente d’abord une résolution DNS via ces anciens résolveurs. Si les services DNS de MAMP/Herd n’existent plus, la requête expire (après ~5 secondes) avant que macOS n’utilise la résolution DNS habituelle.

Solution

Suivez ces étapes pour éliminer complètement les résidus DNS de MAMP ou Laravel Herd :

1. Désinstallez correctement MAMP ou Laravel Herd

Si l’une de ces applications est encore installée, utilisez d’abord son programme de désinstallation ou script officiel :

Désinstallation de MAMP :

• Utilisez la fonction de désinstallation de l’application MAMP
• Ou supprimez manuellement le dossier /Applications/MAMP et les fichiers de configuration associés

Désinstallation de Laravel Herd :

# Commande de désinstallation fournie par Herd
herd uninstall

# Si la commande n’est pas disponible, supprimez l’application et ses réglages manuellement
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. Supprimez les fichiers résiduels dans le dossier /etc/resolver

Ces fichiers DNS peuvent subsister même après une désinstallation :

# Lister les fichiers du dossier /etc/resolver
ls -la /etc/resolver

# Supprimer les fichiers de résolution spécifiques (ex : test et local)
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# Supprimez également tous les fichiers créés par MAMP/Herd
# Par exemple : sudo rm /etc/resolver/herd

Exemples de fichiers créés par MAMP/Herd :

• test – pour les domaines *.test
• local – pour les domaines *.local
• herd – spécifique à Laravel Herd

Remarque : La suppression de ces fichiers requiert les privilèges administrateur (sudo).

3. Évitez d’utiliser le suffixe *.local pour vos domaines

macOS réserve le suffixe *.local aux services mDNS (Bonjour), utilisés sur les réseaux locaux. Employer .local pour le développement peut occasionner :

• Des conflits de résolution DNS
• Des accès très lents
• Des comportements réseau imprévisibles

Recommandé : Utilisez plutôt des suffixes tels que :

• .test – TLD réservé aux environnements de test
• .localhost – qui pointe systématiquement vers l’adresse locale
• .dev – un vrai TLD mais aussi souvent employé pour le développement local
• Ou choisissez le suffixe personnalisé recommandé par ServBay

4. Videz le cache DNS (optionnel)

Après les suppressions ci-dessus, il peut être utile de vider le cache DNS du système :

# Pour macOS Big Sur (11) et versions ultérieures
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Pour macOS Catalina (10.15) et antérieures
sudo killall -HUP mDNSResponder

5. Vérifiez la correction

Après nettoyage, testez l’accès à votre site ServBay :

1. Accédez à votre site local via le navigateur
2. Ouvrez Chrome DevTools → Network
3. Rafraîchissez pour consulter le Timing des requêtes
4. Assurez-vous que le temps DNS Lookup est désormais sous 50 ms

Si la lenteur persiste, vérifiez la présence d’autres logiciels tiers (VPN, proxys, etc.) pouvant perturber la résolution DNS.

Vérifier les fichiers de configuration du serveur Web

Des erreurs dans la configuration du serveur Web sont une cause courante d’inaccessibilité du site. ServBay propose pour chaque serveur des outils de vérification de la syntaxe.

Vérification du Caddyfile

Utilisez la commande intégrée validate pour vérifier la syntaxe du fichier de configuration de Caddy :

# macOS
/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

# Windows
C:\ServBay\bin\caddy.exe validate -c C:\ServBay\etc\caddy\Caddyfile

Si la configuration est correcte, la réponse est Valid configuration. En cas d’erreur, des messages spécifiques vous aideront à les localiser.

Remarque : La commande caddy validate peut produire de nombreux messages INFO ou WARN qui ne signalent pas toujours une erreur de configuration. Tant que le résultat final est Valid configuration, la syntaxe est acceptée.

Exemples d’erreurs fréquentes Caddyfile :

• Erreur de certificat manquant :

  # Exemple macOS
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (autres messages INFO/WARN) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory
  
  # Exemple Windows
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (autres messages INFO/WARN) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open C:\\ServBay\\ssl\\private\\tls-certs\\mail.servbay.host\\mail.servbay.host.1crt: no such file or directory

  Un message comme loading certificates: open xxxxx: no such file or directory signale un chemin incorrect ou manquant pour les certificats SSL dans votre Caddyfile. Vérifiez les chemins des certificats (.crt/.cer/.pem) et des clés privées (.key). ServBay permet l’import manuel ou la demande automatique de certificat via ACME — pensez à contrôler les réglages SSL ServBay.

• Erreur de chemin racine (avec espaces) :

  # Exemple macOS
  2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388
  
  # Exemple Windows
  2024/12/09 17:26:37.371 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at C:\\ServBay\\etc\\caddy\\Caddyfile:1388

  parsing caddyfile tokens for 'root': too many arguments survient souvent lorsqu’un chemin racine comporte des espaces, par exemple :

  • macOS : root * /Applications/ServBay/www/public web (public web est pris comme deux arguments)
  • Windows : root * C:\ServBay\www\public web

  Utilisez des guillemets pour entourer le chemin contenant des espaces :

  • macOS : root * "/Applications/ServBay/www/public web"
  • Windows : root * "C:\ServBay\www\public web"

  Conseil : Évitez les espaces et caractères spéciaux dans les noms de fichiers/dossiers. Préférez le tiret - ou l’underscore _ pour séparer les mots (ex : public-folder, public_dir).

• Erreur de règle de réécriture (rewrite) :

  Copier des règles NGINX dans Caddyfile sans adapter leur syntaxe peut provoquer des erreurs de validation. Consultez la documentation officielle Caddy sur les réécritures ou le guide ServBay Migration d’un site NGINX vers ServBay pour vos réglages.

Vérification de la configuration NGINX

Servez-vous de l’option -t pour tester la configuration NGINX :

# macOS
/Applications/ServBay/bin/nginx -t

# Windows
C:\ServBay\bin\nginx.exe -t

En cas de succès :

# macOS
nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

# Windows
nginx: the configuration file C:\ServBay\etc\nginx\nginx.conf syntax is ok
nginx: configuration file C:\ServBay\etc\nginx\nginx.conf test is successful

Sinon, NGINX indique l’erreur, le fichier concerné et la ligne fautive. Problèmes fréquemment rencontrés :

1. Erreurs de syntaxe : points-virgules manquants, accolades mal fermées…
2. Erreurs sur les chemins : dossier ou fichier absent suite à un include ou autre directive.
3. Conflits de port : tentative d'écoute sur un port déjà pris.

Vérification de la configuration Apache

Utilisez la commande suivante pour tester la syntaxe de configuration d’Apache :

# macOS
/Applications/ServBay/bin/apachectl configtest

# Windows
C:\ServBay\bin\httpd.exe -t

Apache retournera Syntax OK en cas de succès, ou affichera une erreur précise sinon. Problèmes communs :

1. Échec du chargement de module : la directive LoadModule pointe vers un module absent ou un chemin erroné.
2. Erreur syntaxique dans .htaccess : une faute dans ce fichier peut invalider l'ensemble de la configuration ou causer des erreurs sur certains dossiers.
3. Permissions insuffisantes des dossiers : réglages Directory, Files (Require, Allow, Deny) trop restrictifs.

Traitement de l’erreur interne du serveur 500

L’erreur 500 Internal Server Error est un code HTTP générique indiquant que le serveur a rencontré une situation inattendue lors du traitement d’une requête (souvent un échec d’exécution du script backend comme PHP, Python, Node.js…).

Étapes générales de diagnostic

Face à une erreur 500 :

1. Consultez le journal d’erreur du serveur Web : C’est l’étape de base. Les logs contiennent souvent la cause exacte : script défectueux, fichier manquant, problème de permission…

   macOS :

   • Caddy : /Applications/ServBay/var/logs/caddy/error.log
   • NGINX : /Applications/ServBay/var/logs/nginx/error.log
   • Apache : /Applications/ServBay/var/logs/apache/error.log

   Windows :

   • Caddy : C:\ServBay\var\logs\caddy\error.log
   • NGINX : C:\ServBay\var\logs\nginx\error.log
   • Apache : C:\ServBay\var\logs\apache\error.log

   Recherchez les entrées récentes comportant error ou critical.

2. Vérifiez le fonctionnement des services backend (ex : PHP-FPM) : Si votre site repose sur PHP, assurez-vous que le service PHP-FPM est démarré.

   ps aux | grep php-fpm

   Repérez php-fpm: master process ou php-fpm: pool www. Si rien n'apparaît, il faut lancer le service via l’UI ServBay ou la commande servbayctl.

3. Consultez le journal d’erreur du backend (ex : PHP) : Si le log serveur signale une erreur FastCGI ou de script :

   Emplacement du log PHP :

   • macOS : /Applications/ServBay/var/logs/php/php_error.log
   • Windows : C:\ServBay\var\logs\php\php_error.log

   Examinez les erreurs Fatal error, Parse error, Warning, Notice, notamment celles liées au script que vous essayez d’accéder. En environnement de développement, vous pouvez activer display_errors (dans php.ini) pour voir plus de détails.

4. Vérifiez les permissions des fichiers et des dossiers : Le serveur Web (ex : _www sous macOS) doit posséder les droits suffisants pour lire vos fichiers, écrire dans les dossiers d’upload ou les logs. macOS :

   ls -la /Applications/ServBay/www/your-site/

   Utilisez chmod et chown pour ajuster droits et propriétaires au besoin.

   Windows :

   dir C:\ServBay\www\your-site

   Sur Windows, vérifiez via l’onglet « Sécurité » dans les propriétés du dossier que votre compte a les bons droits.

Points spécifiques selon le serveur Web

• Caddy :

  1. Configuration FastCGI : Assurez-vous que les directives php_fastcgi ou reverse_proxy du Caddyfile pointent vers le bon socket ou port PHP-FPM (127.0.0.1:9000 ou un unix:/…).
  2. État de PHP-FPM : Vérifiez que la version PHP correspondante est opérationnelle côté ServBay.
  3. Paramètres de proxy reverse : Si vous utilisez reverse_proxy vers une appli Node.js ou autre, confirmez le port/adresse et le démarrage du backend.

• NGINX :

  1. fastcgi_pass : La directive dans nginx.conf ou le fichier du site doit bien pointer vers PHP-FPM.
  2. client_max_body_size : Si vous rencontrez une erreur 500 en upload, vérifiez la taille limite configurée.
  3. try_files : Assurez-vous que cette directive fonctionne bien pour router les requêtes vers les bons fichiers ou FastCGI.

• Apache :

  1. mod_rewrite : Si vous avez un .htaccess pour les URLs, le module doit être activé.
  2. Syntaxe du .htaccess : Une erreur dans ce fichier cause souvent un 500 direct.
  3. AllowOverride : Le paramètre dans le fichier de configuration doit autoriser les commandes du .htaccess (souvent réglé sur All ou au minimum FileInfo, Limit).

Gestion des services

Après avoir modifié une configuration ou corrigé une erreur backend, il faut généralement redémarrer le serveur Web concerné ou le service associé.

Redémarrage des services

Utilisez la commande servbayctl restart :

# Redémarrer le service Caddy
servbayctl restart caddy -all

# Redémarrer le service NGINX
servbayctl restart nginx -all

# Redémarrer le service Apache
servbayctl restart apache -all

L’argument -all redémarre aussi les services couplés (ex : PHP-FPM si FastCGI est configuré).

Vérification du statut des services

La commande servbayctl status montre l’état actuel du serveur :

# Vérifier le statut du service Caddy
servbayctl status caddy -all

# Vérifier le statut du service NGINX
servbayctl status nginx -all

# Vérifier le statut du service Apache
servbayctl status apache -all

Le retour indique si le service est running (en marche), stopped (arrêté) ou autre.

Procédures avancées de dépannage

Si vos soucis persistent, essayez ces méthodes supplémentaires :

1. Examinez les outils de développement du navigateur : F12 puis onglets Console et Network pour repérer les erreurs JS ou anomalies HTTP côté frontend/backend.
2. Utilisez curl -v en terminal : Cela permet de suivre étape par étape la connexion à votre site (headers, SSL/TLS…), remplaçant your-website.servbay.demo par votre vrai domaine ServBay.
3. Testez sans le pare-feu local temporairement : Le pare-feu macOS ou suites de sécurité tierces peuvent bloquer l’accès : testez en les désactivant (puis ajustez vos règles si nécessaire).
4. Testez sur différents navigateurs/appareils : Pour exclure un cache ou une configuration spécifique à un navigateur/machine, effectuez des essais croisés.
5. Vérifiez la résolution DNS locale ou la config hosts : Si vous utilisez un domaine personnalisé, assurez-vous qu’il pointe bien vers 127.0.0.1 (IPv4) ou ::1 (IPv6) :
   • macOS : /etc/hosts
   • Windows : C:\Windows\System32\drivers\etc\hosts

Conclusion

Les erreurs de serveur Web sont courantes lors du développement local. Le diagnostic systématique des fichiers de configuration, des logs, des permissions et de l’état des services résout la majorité des problèmes. Les outils integrés ServBay et la CLI servbayctl sont vos alliés. Pour des cas complexes, n’hésitez pas à consulter la documentation ServBay détaillée ou à contacter le support technique.