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 :
bash2024/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
1
2
3Si 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) :
bash2024/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
1
2Cette 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, dansroot * /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
oupublic_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
2
En cas d’erreur, NGINX précisera le nom du fichier et la ligne concernée. Les erreurs NGINX classiques sont :
- Erreur de syntaxe : Manque de point-virgule
;
, accolades}
mal fermées, etc. - Chemin de fichier incorrect : Fichier ou dossier référencé via
include
ou une autre directive n’existe pas ou est mal orthographié. - 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 :
- Échec de chargement d’un module : Un module activé via
LoadModule
n’existe pas ou le chemin indiqué est incorrect. - 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. - Mauvais réglages des permissions : Les directives
Directory
ouFiles
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 :
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 mentionserror
oucritical
.
- Caddy :
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é.
bashps aux | grep php-fpm
1Vérifiez la présence de lignes contenant
php-fpm: master process
ouphp-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 commandeservbayctl
.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 commeFatal error
,Parse error
,Warning
,Notice
, surtout en lien avec le script actuellement exécuté. Assurez-vous quedisplay_errors
est désactivé en production mais activé temporairement en développement si besoin (la variable se règle dans lephp.ini
).
- PHP :
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.bashls -la /Applications/ServBay/www/your-site/
1Vé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
etchown
(procédez avec prudence).
Points clés d’investigation pour chaque serveur Web
Caddy :
- Configuration FastCGI : Vérifiez que l’instruction
php_fastcgi
oureverse_proxy
du Caddyfile cible correctement l’adresse d’écoute de PHP-FPM (habituellement127.0.0.1:9000
ou bienunix:/path/to/php-fpm.sock
). - État de PHP-FPM : Assurez-vous que la version PHP correspondante et PHP-FPM sont bien lancés dans ServBay.
- 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.
- Configuration FastCGI : Vérifiez que l’instruction
NGINX :
- Directive
fastcgi_pass
: Contrôlez sa concordance dans le fichiernginx.conf
ou la configuration du site, et qu’elle pointe bien sur PHP-FPM. 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.- Directive
try_files
: Vérifiez la configurationtry_files
afin qu’elle permette de retrouver les bons fichiers d’index ou route les requêtes FastCGI comme il faut.
- Directive
Apache :
- Module
mod_rewrite
: Si vous faites du rewriting via.htaccess
, le module mod_rewrite doit être activé. - Contenu .htaccess : Une directive erronée dans
.htaccess
provoque directement une erreur 500. Traquez les fautes de syntaxe (ex :RewriteRule
). - Réglage
AllowOverride
: Assurez-vous dans la configuration Apache que le dossier concerné autorise.htaccess
viaAllowOverride
(typiquementAll
, ou à défaut inclure au minimumFileInfo
etLimit
).
- Module
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
2
3
4
5
6
7
8
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
2
3
4
5
6
7
8
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 :
- Consulter les outils de développement du navigateur : Ouvrez la console développeur (généralement par F12), allez dans l’onglet
Console
etNetwork
. 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. - 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. - 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).
- 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é.
- 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 sur127.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.