Guide détaillé de la structure des dossiers ServBay

Vue d’ensemble

ServBay est une plateforme de développement Web local compatible avec macOS et Windows, dont la structure de dossiers est à la fois claire et ordonnée. Les développeurs familiers avec les systèmes Linux/Unix reconnaîtront une organisation similaire à la structure standard de ces systèmes, facilitant ainsi la localisation et la gestion des différents fichiers.

Emplacement de l’installation ServBay

Les emplacements d’installation par défaut de ServBay sont :

• macOS : /Applications/ServBay
• Windows : C:\ServBay

Bien comprendre la structure des dossiers de ServBay est essentiel pour gérer efficacement votre environnement de développement, configurer les services, diagnostiquer les problèmes et réaliser des sauvegardes. Cet article vous présente en détail les principaux dossiers et leur utilité.

La structure d’installation typique de ServBay ressemble à ceci :

ServBay
|____backup                 # Dossier des fichiers de sauvegarde
| |____config               # Sauvegardes de configuration
| |____databases            # Sauvegardes des bases de données
| |____ssl                  # Sauvegardes des certificats SSL
| |____websites             # Sauvegardes des sites Web
|____bin                    # Dossier des exécutables utilisateur (lien symbolique vers package/bin)
|____data                   # Données internes de ServBay
| |____servbay              # Configurations et données noyaux de ServBay
|____db                     # Dossier de stockage des bases de données
| |____mariadb              # Fichiers de données MariaDB
| |____mongodb              # Fichiers de données MongoDB
| |____mysql                # Fichiers de données MySQL
| |____postgresql           # Fichiers de données PostgreSQL
| |____redis                # Fichiers de données Redis
|____etc                    # Dossier de configuration (lien symbolique vers package/etc)
|____logs                   # Dossier des journaux (lien symbolique vers package/var/log)
|____package                # Dossier d’installation des packages
| |____bin                  # Exécutables des packages
| |____common               # Bibliothèques et composants communs
| | |____imap-uw
| | |____include            # Fichiers d’en-tête (ServBay Development Library)
| | |____lib                # Bibliothèques partagées et statiques (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Emplacement réel des fichiers de configuration des packages
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (autres packages, ex. Python, Go, Java, Ruby, Rust, etc.)
| |____<package_name>       # Dossier principal de chaque package
| | |____<major_version>   # Dossier de version majeure
| | | |____<full_version> # Dossier version complète (package principal)
| | | |____current         # Lien symbolique vers la dernière version complète
| | |____...
| |____sbin                 # Exécutables système des packages
| |____var                  # Données variables des packages (ex. logs)
| | |____log                # Logs
| | |____run                # Fichiers runtime (.pid, etc.)
|____sbin                   # Dossier exécutables système (lien symbolique vers package/sbin)
|____script                 # Scripts de gestion interne ServBay
|____ssl                    # Dossier certificats SSL
| |____acme                 # Certificats obtenus via le protocole ACME
| |____caddy                # Certificats SSL générés automatiquement par Caddy
| |____import               # Certificats SSL tiers importés
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Dossier fichiers temporaires et sockets
|____www                    # Racine des sites Web
| |____servbay              # Dossier de site d’exemple

Nous détaillerons ci-dessous l’utilité de chaque dossier.

Dossier principal de ServBay

Le dossier principal de ServBay se trouve par défaut dans /Applications/ServBay. L’ensemble des packages, fichiers de configuration, données, journaux et autres éléments liés à ServBay y sont regroupés.

Pour assurer la sécurité de votre environnement local et de vos données, il est vivement recommandé de sauvegarder régulièrement ce dossier principal. Utilisez Time Machine ou tout autre outil de sauvegarde pour effectuer une copie complète du dossier /Applications/ServBay.

Racine du site Web (www)

Les fichiers de vos sites Web se trouvent dans /Applications/ServBay/www. C’est ici que vous placez tous les projets de sites locaux.

Pour une organisation claire et une gestion facilitée, il est conseillé de créer un sous-dossier pour chaque projet ou site virtuel (appelé « site » dans ServBay).

Par exemple, si vous avez créé les sites web.servbay.demo, api.servbay.demo et new.servbay.local, la structure suggérée serait :

/Applications/ServBay/www
|____servbay.demo           # Sites liés au domaine *.servbay.demo
| |____web               # Fichiers du site web.servbay.demo
| |____api               # Fichiers du site api.servbay.demo
|____servbay.local          # Sites liés au domaine *.servbay.local
| |____new               # Fichiers du site new.servbay.local
|____myproject              # Autres projets, ex. myproject.local

Cette organisation permet de distinguer facilement chaque projet et domaine, pour une gestion optimale.

Dossier de configuration (etc)

Le dossier de configuration /Applications/ServBay/etc est en réalité un lien symbolique vers /Applications/ServBay/package/etc. Tous les packages installés (PHP, MariaDB, Nginx, Caddy, etc.) conservent leurs fichiers de configuration principaux ici.

Vous pouvez directement accéder et modifier ces configurations via ce chemin. Généralement, après modification, il faudra redémarrer le service concerné pour que les changements soient pris en compte.

Exemples d’emplacements de fichiers de configuration pour les principaux packages :

PHP (etc/php)

Le dossier de configuration PHP présente une structure à deux niveaux pour séparer les différentes versions principales. Vous trouverez par exemple, dans etc/php, les dossiers 5.6, 7.4, 8.3, chaque dossier correspondant à une grande version de PHP. Structure typique :

php
|____5.6                    # Configuration pour PHP 5.6
| |____conf.d               # Configuration des extensions
| |____php.ini              # Configuration principale
|____7.4                    # Configuration pour PHP 7.4
| |____conf.d               # Configuration des extensions
| |____php-fpm.d            # Pools FPM
| |____php-fpm.conf         # Configuration principale PHP-FPM
| |____php.ini              # Configuration principale
|____8.3                    # Configuration pour PHP 8.3
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (autres versions PHP)

Chaque dossier de version contient le php.ini (configuration principale), le php-fpm.conf (configuration principale PHP-FPM, si FPM est supporté), et potentiellement pear.conf, etc. Après toute modification, redémarrez le service PHP-FPM via le panneau ServBay ou la commande servbayctl pour appliquer les changements.

Le dossier conf.d regroupe les configurations des extensions PHP, comme xdebug.ini, opcache.ini, redis.ini, etc. Modifier ces fichiers permet d’activer, désactiver ou paramétrer chaque extension PHP. Là encore, un redémarrage du service PHP-FPM est requis.

Remarque : ServBay est conçu pour que toutes les sous-versions d’une même version majeure de PHP partagent la même configuration. Par exemple, PHP 8.3.3 et 8.3.5 utilisent la configuration du dossier etc/php/8.3.

MariaDB / MySQL / PostgreSQL (etc/mariadb, etc/mysql, etc/postgresql)

Les dossiers de configuration des bases de données suivent une séparation par version, ex. etc/mariadb/11.2. Vous y trouverez les fichiers de configuration principaux (my.cnf pour MariaDB/MySQL, postgresql.conf pour PostgreSQL). Chaque sous-version majeure partage la même configuration.

Pour réinitialiser le mot de passe « root » de MariaDB, MySQL ou PostgreSQL, cela se fait via outil en ligne de commande ou panneau ServBay, et non via modification directe du fichier de configuration.

Caddy (etc/caddy)

Le fichier de configuration Caddy (Caddyfile) est situé dans etc/caddy.

Avertissement : ServBay génère ce fichier automatiquement selon vos paramètres de site dans le panneau de contrôle. Ne modifiez pas ce fichier manuellement, car tout changement peut être écrasé par ServBay lors d’une prochaine mise à jour. Pour ajouter une configuration personnalisée pour un site, passez toujours par les paramètres du panneau ServBay.

Nginx (etc/nginx)

Le fichier principal de Nginx, nginx.conf, est situé dans etc/nginx. À l’instar de Caddy, ServBay génère ou inclut automatiquement les fragments de configuration de site. Modifiez ce fichier avec précaution et préférez la gestion via le panneau ServBay.

dnsmasq (etc/dnsmasq)

Le dossier de configuration dnsmasq contient le fichier dnsmasq.conf (configuration par défaut) et domains.conf (généré automatiquement selon vos domaines locaux configurés).

Avertissement : Ces fichiers sont gérés automatiquement par ServBay pour garantir le bon fonctionnement de la résolution des domaines locaux. Ne modifiez pas ces fichiers manuellement, sous peine d’inaccessibilité de vos sites locaux.

Autres packages

Pour les autres packages pris en charge par ServBay (Node.js, Python, Go, Java, Ruby, Rust, etc.), les éventuels fichiers de configuration globaux ou de service sont généralement stockés dans des sous-dossiers de etc, selon la même structure versionnée.

Dossier de données internes ServBay (data/servbay)

/Applications/ServBay/data/servbay

Ce dossier conserve les fichiers de configuration essentiels, l’état interne, et les paramètres spécifiques utilisateur dont ServBay a besoin pour fonctionner correctement (notamment pour le panneau de contrôle, la gestion des packages, la configuration des sites et des bases de données).

Avertissement : Veillez à sauvegarder régulièrement ce dossier et n’y supprimez ni ne modifiez aucun fichier manuellement. Toute suppression ou modification peut rendre ServBay inutilisable ou compromettre sa configuration.

Dossiers des exécutables et scripts (bin, sbin, script)

/Applications/ServBay/bin -> package/bin
/Applications/ServBay/sbin -> package/sbin
/Applications/ServBay/script

Tous les exécutables de ServBay sont organisés dans bin et sbin, qui sont des liens symboliques vers package/bin et package/sbin. Vous y trouverez tous les outils intégrés et les interpréteurs des différents langages.

ServBay ajoute ces dossiers au PATH système au démarrage, ce qui permet d’exécuter ces outils directement dans le terminal. Parmi eux :

• Outils courants : curl, openssl, frpc, etc.
• Interpréteurs de plusieurs versions : php (défaut), php-5.6, php-7.4, php-8.3, node (défaut), node-16, node-18, python3, go, java, ruby, rustc, etc. Utilisez le nom versionné pour invoquer une version spécifique.
• Clients de base de données : mysql, psql, mongosh, redis-cli, etc.

Le dossier script (/Applications/ServBay/script) contient les scripts d’administration interne servant à démarrer/arrêter des services, initialiser des bases de données ou effectuer des tâches de maintenance. Bien que vous puissiez les exécuter directement, il est recommandé d’utiliser l’outil en ligne de commande servbayctl, qui propose une interface utilisateur plus conviviale, tout en exécutant ces scripts en arrière-plan.

Par exemple, pour démarrer le service PHP 7.4 FPM :

servbayctl start php 7.4

L’outil servbayctl se trouve dans /Applications/ServBay/bin.

Dossier des bases de données (db)

/Applications/ServBay/db

Ce dossier est l’emplacement où les bases de données stockent leurs fichiers de données. L’organisation suit la structure par version du package, par exemple :

• /Applications/ServBay/db/mariadb/<major_version> : données MariaDB
• /Applications/ServBay/db/mysql/<major_version> : données MySQL
• /Applications/ServBay/db/postgresql/<major_version> : données PostgreSQL
• /Applications/ServBay/db/mongodb : données MongoDB
• /Applications/ServBay/db/redis : données Redis

Chaque version majeure d’un SGBD utilise le même dossier de données, par exemple MariaDB 11.2.x stocke ses données dans /Applications/ServBay/db/mariadb/11.2.

Avertissement : Ce dossier contient l’ensemble de vos bases de données locales. Avant toute opération critique (mise à niveau, migration système, etc.), sauvegardez-le intégralement. Les sauvegardes automatiques ServBay intègrent également les données de ce dossier.

Dossier des journaux (logs)

/Applications/ServBay/logs -> package/var/log

ServBay regroupe tous les journaux de ses services dans /Applications/ServBay/logs (lien vers /Applications/ServBay/package/var/log). Les développeurs peuvent ainsi facilement surveiller l’activité et les erreurs.

Les fichiers de logs sont organisés par service :

• logs/caddy/ ou logs/nginx/ : logs d’accès et d’erreur de Caddy ou Nginx (généralement par site/domaine)
• logs/php/ : logs PHP-FPM (php-fpm.log) et erreurs PHP (errors.log). Le fichier errors.log enregistre les erreurs fatales non prises en charge par l’application ou le framework.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/ : logs des services de bases de données (erreurs, requêtes lentes, etc.)
• Journaux des autres services : Python, Go, Java, Ruby, Rust, etc.

Remarque : Les fichiers journaux, en particulier ceux des accès et erreurs, peuvent occuper beaucoup d’espace disque, surtout pour les projets très actifs. Pensez à vérifier et nettoyer régulièrement les logs inutiles pour optimiser l’espace de stockage.

Dossier des packages (package)

/Applications/ServBay/package

ServBay installe et gère ses packages dans ce dossier. Chaque package est organisé selon le schéma nom/major_version/full_version (ex. PHP installé dans /Applications/ServBay/package/php/8.3/8.3.7).

Le panneau de contrôle ServBay vous permet d’installer, désinstaller et de basculer entre différentes versions.

Pour libérer de l’espace, vous pouvez supprimer manuellement les dossiers de versions obsolètes (ex. /Applications/ServBay/package/php/8.2/8.2.10).

Avertissement : Chaque dossier de version majeure (ex. /Applications/ServBay/package/php/8.3) contient généralement un lien symbolique current vers la version active. Ne supprimez ni ne modifiez jamais ces liens, sous peine de blocage du fonctionnement des services ou de non résolution des chemins binaires ou des bibliothèques.

Dossier des certificats SSL (ssl)

/Applications/ServBay/ssl

Ce dossier contient tous les fichiers de certificats SSL/TLS :

• Certificats SSL obtenus automatiquement pour vos sites locaux via le protocole ACME (généralement dans ssl/caddy ou ssl/acme, suivant le serveur utilisé)
• Certificats racine pour le développement HTTPS local (ServBay User CA et ServBay Public CA), dans ssl/private et ssl/public. L’installation de ces certificats CA dans le trousseau de confiance de votre système permet à votre navigateur de faire confiance aux certificats ServBay et d’éviter les avertissements HTTPS.

Dossier des sauvegardes (backup)

/Applications/ServBay/backup

C’est ici que ServBay stocke ses fichiers de sauvegarde générés automatiquement. Ces sauvegardes facilitent la récupération de vos données et configurations clés, notamment :

• backup/config : sauvegardes des configurations principales et des packages
• backup/databases : sauvegardes des bases de données MariaDB, MySQL, PostgreSQL, MongoDB
• backup/ssl : sauvegardes des certificats SSL
• backup/websites : sauvegardes des projets de sites Web contenus dans /Applications/ServBay/www

Il est conseillé de vérifier régulièrement ce dossier, et d’externaliser les sauvegardes vers un autre support pour une stratégie de secours optimale.

Dossier des fichiers temporaires (tmp)

/Applications/ServBay/tmp

Ce dossier accueille les fichiers temporaires générés par les services, dont le plus courant est le fichier .pid et les fichiers socket nécessaires à la communication inter-processus.

• .pid : identifiant de processus d’un service en cours d’exécution
• Fichiers socket : ex. php-cgi.sock, mysql.sock, pgsql.sock, utilisés pour la communication locale via Unix Domain Socket. Cette méthode est souvent plus performante et avec moins de latence qu’un accès réseau TCP, surtout entre processus sur la même machine.

Composants communs et bibliothèques de développement (package/common)

/Applications/ServBay/package/common

Ce dossier regroupe les composants nécessaires au fonctionnement des packages : bibliothèques partagées (ex. *.dylib), ainsi que des bibliothèques de développement optionnelles.

Si vous installez le ServBay Development Library (package optionnel pour la compilation), vous trouverez aussi un dossier include (fichiers d’en-tête) et lib (bibliothèques statiques *.a, liens *.la). Ces fichiers sont requis pour compiler des extensions PHP ou d’autres outils dépendant des bibliothèques intégrées ServBay.

Avertissement : Ne supprimez jamais les fichiers *.dylib du dossier package/common/lib, essentiels au fonctionnement des logiciels intégrés. Leur suppression entraînera des erreurs graves d’exécution.

Conclusion

La structure des dossiers ServBay sépare clairement packages, configurations, données, journaux et fichiers de sites, inspirée des conventions Unix pour une gestion intuitive de l’environnement local. Connaître la fonction de chaque dossier vous permettra d’optimiser vos développements Web avec ServBay. N’oubliez pas d’effectuer des sauvegardes régulières des dossiers clés (notamment data et db) pour préserver vos travaux.