Guide de dépannage des serveurs Web ServBay

ServBay prend en charge Caddy, NGINX et Apache comme serveurs Web par défaut, vous offrant ainsi un environnement de développement local flexible. Au cours de l’utilisation, il se peut que vous rencontriez des problèmes comme l’inaccessibilité de votre site, des ralentissements ou encore des erreurs (par exemple, erreur interne du serveur 500). Ce guide vous aide à diagnostiquer et résoudre les pannes courantes liées au serveur Web dans l’environnement ServBay.

Utiliser l’outil de diagnostic intégré ServBay

ServBay met à disposition un outil de diagnostic puissant, capable de détecter et signaler automatiquement les anomalies les plus courantes de configuration ou de service. En cas de souci, il est vivement conseillé de commencer par cet outil pour effectuer une première analyse autonome.

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

Cet outil vérifie l’état des composants essentiels de ServBay, la disponibilité des ports, la syntaxe des fichiers de configuration, et fournit des conseils ciblés afin de localiser rapidement l’origine du problème.

Vérifier les fichiers de configuration du serveur Web

Les erreurs au sein des fichiers de configuration du serveur sont l’une des causes les plus fréquentes d’indisponibilité des sites. ServBay fournit, pour chaque serveur Web, des outils dédiés à la vérification de la syntaxe.

Vérification du Caddyfile

Utilisez la commande interne validate de Caddy pour valider votre fichier de configuration Caddyfile.

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

Si la syntaxe est correcte, la commande retournera Valid configuration. En cas d’erreur, un message d’avertissement adapté sera affiché selon le type de problème.

Remarque : La commande caddy validate peut produire de nombreux messages INFO ou WARN. Ceux-ci relèvent généralement du processus de chargement interne de Caddy et ne signifient pas forcément une erreur de configuration. Si vous obtenez au final Valid configuration, la syntaxe est bien correcte.

Exemples d’erreurs courantes dans Caddyfile :

• Erreur de fichier de certificat introuvable :

  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

  Si une erreur du type loading certificates: open xxxxx: no such file or directory apparaît, cela signifie que le chemin du certificat SSL référencé dans votre Caddyfile est incorrect ou que le fichier n’existe pas. Vérifiez bien l’emplacement des certificats (.crt/.cer/.pem) et des clés privées (.key) mentionnés, et assurez-vous que les fichiers existent bien au bon endroit. ServBay prend en charge l’import manuel de certificats ou la génération automatique via ACME. Vérifiez également vos réglages SSL dans ServBay.

• Erreur de chemin du dossier racine (présence d’un espace) :

  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

  Cette erreur parsing caddyfile tokens for 'root': too many arguments vient généralement d’un espace dans le chemin du dossier racine du site. Par exemple, dans root * /Applications/ServBay/www/public web, public web sera interprété comme deux arguments séparés. La solution est d’englober le chemin contenant des espaces entre guillemets, comme ceci : root * "/Applications/ServBay/www/public web".

  Conseil : Pour éviter ce genre de soucis, il est fortement recommandé de ne pas utiliser d’espaces ni de caractères spéciaux dans les noms de fichiers ou de dossiers. Préférez les tirets - ou les underscores _ pour séparer les mots (ex : public-folder ou public_dir).

• Erreur dans les règles de réécriture :

  Utiliser dans le Caddyfile une règle de réécriture qui ne respecte pas la syntaxe Caddy – par exemple, en copiant directement une règle NGINX – provoquera un échec de validation. Consultez la documentation officielle du module Rewrite de Caddy ou le guide ServBay pour migrer un site NGINX vers ServBay et assurez-vous de la bonne syntaxe de vos règles.

Vérification de la configuration NGINX

Pour tester la syntaxe et la validité de la configuration NGINX, utilisez le paramètre interne -t.

/Applications/ServBay/bin/nginx -t

Si la configuration est correcte, vous verrez :

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

En cas d’erreur, NGINX précisera le nom du fichier et la ligne concernée. Les erreurs NGINX classiques sont :

1. Erreur de syntaxe : Manque de point-virgule ;, accolades } mal fermées, etc.
2. Chemin de fichier incorrect : Fichier ou dossier référencé via include ou une autre directive n’existe pas ou est mal orthographié.
3. Conflit de port : Le port configuré pour l’écoute est déjà utilisé par un autre processus.

Vérification de la configuration Apache

Pour vérifier la syntaxe des fichiers Apache, utilisez la commande suivante :

/Applications/ServBay/bin/apachectl configtest

Si tout va bien, la réponse sera Syntax OK. En cas d’erreur, un message explicite sera affiché. Erreurs Apache courantes :

1. Échec de chargement d’un module : Un module activé via LoadModule n’existe pas ou le chemin indiqué est incorrect.
2. Erreur de syntaxe dans .htaccess : Une erreur dans un fichier .htaccess (présent dans le dossier du site) peut faire échouer la vérification globale ou empêcher l’accès à certains répertoires.
3. Mauvais réglages des permissions : Les directives Directory ou Files peuvent restreindre excessivement l’accès (Require, Allow, Deny) et bloquer l’affichage des fichiers du site.

Gestion des erreurs internes 500

L’erreur 500 Internal Server Error est un code HTTP générique signalant que le serveur a rencontré une situation inattendue et n’a pas pu honorer la demande. Dans le cas d’applications Web, cela traduit souvent un échec d’un script backend (PHP, Python, Node.js, etc.).

Étapes générales d’investigation

Face à une erreur 500, suivez ces étapes pour remonter à la cause :

1. Vérifier les logs d’erreurs du serveur Web : C’est la première chose à faire, car les logs détaillent souvent le motif de l’erreur (erreur de script, fichier manquant, soucis de permissions, etc.).

   • Caddy : /Applications/ServBay/var/logs/caddy/error.log
   • NGINX : /Applications/ServBay/var/logs/nginx/error.log
   • Apache : /Applications/ServBay/var/logs/apache/error.log Consultez les entrées les plus récentes, cherchez les mentions error ou critical.

2. Contrôler si les services backend (ex : PHP-FPM) tournent : Si votre site s’appuie sur PHP, vérifier que le service PHP-FPM est lancé.

   ps aux | grep php-fpm

   Vérifiez la présence de lignes contenant php-fpm: master process ou php-fpm: pool www. Si rien n’apparaît, le processus PHP-FPM est stoppé ou a planté. Vous pouvez le relancer via l’interface ServBay ou via la commande servbayctl.

3. Vérifier les logs d’erreurs de scripts backend (PHP, etc.) : Si les logs du serveur évoquent une erreur FastCGI ou d’exécution de script, consultez aussi les logs du langage concerné.

   • PHP : /Applications/ServBay/var/logs/php/php_error.log Recherchez des mentions comme Fatal error, Parse error, Warning, Notice, surtout en lien avec le script actuellement exécuté. Assurez-vous que display_errors est désactivé en production mais activé temporairement en développement si besoin (la variable se règle dans le php.ini).

4. Vérifier les permissions des fichiers et dossiers : Le serveur fonctionne sous un utilisateur spécifique (généralement _www) qui doit pouvoir lire les fichiers/dossiers du site et écrire dans les dossiers d’upload ou de logs.

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

   Vérifiez que l’utilisateur du serveur a les droits de lecture sur le dossier racine du site et ses sous-dossiers/fichiers. Pour l’upload ou l’écriture dans les logs, il faut aussi les droits en écriture. Modifiez les permissions ou la propriété via chmod et chown (procédez avec prudence).

Points clés d’investigation pour chaque serveur Web

• Caddy :

  1. Configuration FastCGI : Vérifiez que l’instruction php_fastcgi ou reverse_proxy du Caddyfile cible correctement l’adresse d’écoute de PHP-FPM (habituellement 127.0.0.1:9000 ou bien unix:/path/to/php-fpm.sock).
  2. État de PHP-FPM : Assurez-vous que la version PHP correspondante et PHP-FPM sont bien lancés dans ServBay.
  3. Paramétrage du reverse proxy : Lors de l’utilisation de reverse_proxy pour des backend Node.js ou autres, contrôlez l’adresse/port ainsi que l’état du service cible.

• NGINX :

  1. Directive fastcgi_pass : Contrôlez sa concordance dans le fichier nginx.conf ou la configuration du site, et qu’elle pointe bien sur PHP-FPM.
  2. client_max_body_size : Si l’upload de gros fichiers provoque une erreur 500, ce paramètre est peut-être trop bas et bride la taille maximale des requêtes.
  3. Directive try_files : Vérifiez la configuration try_files afin qu’elle permette de retrouver les bons fichiers d’index ou route les requêtes FastCGI comme il faut.

• Apache :

  1. Module mod_rewrite : Si vous faites du rewriting via .htaccess, le module mod_rewrite doit être activé.
  2. Contenu .htaccess : Une directive erronée dans .htaccess provoque directement une erreur 500. Traquez les fautes de syntaxe (ex : RewriteRule).
  3. Réglage AllowOverride : Assurez-vous dans la configuration Apache que le dossier concerné autorise .htaccess via AllowOverride (typiquement All, ou à défaut inclure au minimum FileInfo et Limit).

Gestion des services

Après modification d’une configuration ou résolution d’un problème backend, il faut en général redémarrer le service serveur Web ou associé pour que les changements soient pris en compte.

Redémarrer un service

Utilisez la commande servbayctl restart pour relancer le serveur Web de votre choix.

# Redémarrage du service Caddy
servbayctl restart caddy -all

# Redémarrage du service NGINX
servbayctl restart nginx -all

# Redémarrage du service Apache
servbayctl restart apache -all

Le paramètre -all tentera aussi de redémarrer les services annexes liés au serveur (par exemple, un redémarrage de Caddy, NGINX ou Apache inclura PHP-FPM si FastCGI est configuré).

Consulter l’état d’un service

La commande servbayctl status donne la situation actuelle d’un service.

# État du service Caddy
servbayctl status caddy -all

# État du service NGINX
servbayctl status nginx -all

# État du service Apache
servbayctl status apache -all

La sortie indique si le service est running (en cours), stopped (arrêté), ou dans un autre état. Cela permet de vérifier s’il a bien démarré.

Étapes de dépannage avancées

Si le problème persiste malgré les vérifications précédentes, essayez ces démarches plus poussées :

1. Consulter les outils de développement du navigateur : Ouvrez la console développeur (généralement par F12), allez dans l’onglet Console et Network. Cherchez des erreurs JavaScript côté client, le détail des statuts réseau, en-têtes et corps de réponse : cela aide à distinguer un problème frontal d’un souci côté serveur.
2. Utiliser la commande curl -v : Depuis le terminal, lancez : curl -v your-website.servbay.demo (remplacez par le vrai domaine de votre site ServBay). Le mode verbeux affiche tous les détails (requêtes, réponses, infos SSL/TLS…), utile pour diagnostiquer les problèmes de connexion ou de protocole.
3. Désactiver temporairement le pare-feu : Le pare-feu local (comme celui de macOS) ou certains antivirus peuvent bloquer les connexions entrantes. Désactivez-le pour tester : si le problème disparaît, ajustez les règles pour autoriser les ports ServBay (ex : 80, 443).
4. Tester sur plusieurs navigateurs/appareils : Accédez au site via un navigateur ou appareil différent pour écarter une question de cache, de configuration locale, ou de compatibilité.
5. Vérifier la résolution DNS locale ou la configuration du fichier hosts : Avec un nom de domaine personnalisé (autre que localhost ou une IP), contrôlez /etc/hosts ou la configuration DNS locale. Vérifiez que le domaine pointe bien sur 127.0.0.1 ou ::1.

Conclusion

Les défaillances de serveur Web sont un défi courant dans le développement local. En vérifiant systématiquement la syntaxe des fichiers de configuration, en analysant les logs, en s’assurant de l’état des services, et en contrôlant les permissions des fichiers, la plupart des problèmes trouveront une solution rapide. Les outils de diagnostic intégrés de ServBay et sa ligne de commande servbayctl sont de précieux alliés. Si le problème est complexe, consultez la documentation ServBay plus détaillée ou contactez l’équipe support.