FAQ : Problèmes fréquents lors de la collaboration entre ServBay et Docker

Lorsque vous utilisez ServBay pour le développement web local, il peut être judicieux de combiner cet outil avec Docker pour bénéficier d'environnements conteneurisés. Cette FAQ vise à répondre aux problèmes les plus courants lors de l'utilisation simultanée de ServBay et Docker sous macOS et Windows, comme l'accès aux services ServBay depuis Docker, ou l'utilisation du proxy inversé ServBay pour des applications dans les conteneurs Docker.

Q1 : Pourquoi ServBay modifie-t-il mon fichier `hosts` système ? Est-il possible de l’empêcher ?

ServBay ajoute automatiquement des entrées dans votre fichier système hosts (par exemple, mysite.servbay.demo 127.0.0.1), afin de permettre l’accès à vos sites web de développement via des noms de domaine personnalisés comme mysite.servbay.demo. En réalité, ces sites tournent bien sur l’adresse locale 127.0.0.1.

Néanmoins, à cause du fonctionnement de Docker, le fichier hosts du système hôte (macOS ou Windows) est aussi lu par Docker, ce qui fait que mysite.servbay.demo sera résolu vers 127.0.0.1 dans le conteneur, et Docker pointera alors vers le service du conteneur lui-même, ce qui est incorrect.

Principe de fonctionnement :

Quand vous créez un nouveau site dans ServBay et spécifiez un nom de domaine (exemple : example.servbay.demo), ServBay pointe automatiquement ce domaine vers 127.0.0.1.
Il s’agit de la méthode standard pour permettre l’accès via des noms de domaine locaux conviviaux. Si vous ne modifiez pas le fichier hosts, vous devrez accéder à vos sites avec des URLs du type http://127.0.0.1:PORT, sans pouvoir profiter de domaines customisés.

Peut-on l'empêcher ?

En théorie, vous pouvez retirer manuellement les lignes ajoutées par ServBay, mais alors vous ne pourrez plus accéder à votre site local via le domaine configuré, contournant ainsi l’objectif premier de ServBay qui est de simplifier la gestion locale des sites. L’une des fonctionnalités clés de ServBay reste le processus facilité de création et d’accès aux sites locaux. Si vous ne souhaitez pas que ServBay gère l’entrée d’un domaine particulier dans le fichier hosts, évitez tout simplement de créer un site pour ce domaine dans ServBay.

Dans la grande majorité des cas de développement local, la gestion automatique du fichier hosts par ServBay est souhaitable, car elle simplifie considérablement le flux de travail.

Q2 : Comment mon conteneur Docker peut-il accéder correctement, via le nom de domaine, aux sites gérés par ServBay sur l’hôte (exemple : `mysite.servbay.demo`) ?

Ce besoin est fréquent mais nécessite une manipulation spécifique pour éviter les erreurs. Un site ServBay tournant sur votre machine hôte (macOS ou Windows) — par exemple mysite.servbay.demo, qui se résout en 127.0.0.1 sur l’hôte — verra 127.0.0.1 dans un conteneur Docker pointer vers le conteneur lui-même, pas vers l’hôte.

Mauvaise pratique : accéder au site ServBay en utilisant directement host.docker.internal comme nom d’hôte dans l'URL

Docker Desktop pour Mac (et Windows) propose un nom DNS spécial, host.docker.internal, permettant aux conteneurs de pointer vers l’IP de l’hôte. Cependant, il est fortement déconseillé d’utiliser ce nom comme hôte dans l’URL pour accéder directement aux sites ServBay (par exemple, accéder à http://host.docker.internal/ en pensant que cela pointera vers mysite.servbay.demo).

En effet, dans ce cas, l’en-tête HTTP Host envoyé au serveur web ServBay (comme Caddy ou Nginx) sera host.docker.internal. Or, ServBay se sert de cet en-tête pour identifier le site web concerné : si la valeur est host.docker.internal au lieu de mysite.servbay.demo, le routage échouera, ou, en HTTPS, provoquera une erreur SNI (Server Name Indication), car le certificat SSL est généré pour mysite.servbay.demo et non pour host.docker.internal.

Bonne solution : Ajoutez l’entrée via extra_hosts au démarrage du conteneur Docker

Pour permettre à l’application située dans le conteneur Docker d’utiliser le vrai nom de domaine du site ServBay (comme mysite.servbay.demo) et d’envoyer l’en-tête Host correct, il faut ajouter une entrée dans le fichier /etc/hosts du conteneur, faisant pointer ce domaine vers l’IP de votre système hôte. Cela se configure via extra_hosts (dans docker-compose.yml) ou via --add-host avec docker run, en pointant vers host.docker.internal ou (préféré) vers host-gateway.

Avec docker run :
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway est une valeur spéciale, docker la remplacera automatiquement par l’IP interne de l’hôte, équivalent avancé de host.docker.internal depuis Docker 20.10+.)

Avec docker-compose.yml :

yaml

version: '3.8' # ou ultérieur
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # ou "mysite.servbay.demo:host.docker.internal"
    # ... autres options

Une fois configuré :

L’application dans le conteneur peut accéder à http://mysite.servbay.demo ou https://mysite.servbay.demo — le fichier /etc/hosts du conteneur résout alors aujourd’hui ce domaine vers l’IP du macOS hôte.
La requête est envoyée vers le serveur web ServBay sur l’hôte.
L’en-tête HTTP Host est bien mysite.servbay.demo, permettant à ServBay de router comme il faut et d’offrir le certificat SSL attendu (en mode HTTPS).

Q3 : Comment mon conteneur Docker peut-il se connecter aux bases de données gérées par ServBay (MySQL, PostgreSQL, etc.) ou à d’autres services non-HTTP ?

Contrairement aux services web exposés par nom de domaine, pour des connexions vers une base de données ou tout service TCP ne reposant pas sur SNI : il est courant et recommandé d’utiliser host.docker.internal comme nom d’hôte serveur.

Étapes :

Vérifiez que le service de base de données (ou autre) soit lancé dans ServBay et acceptez les connexions du système hôte (par défaut OK pour usage local).
Dans le conteneur Docker, configurez la connexion à la base (ou au service) :
- Host : host.docker.internal
- Port : Le port utilisé par ServBay pour ce service (MySQL par défaut : 3306, PostgreSQL : 5432, etc.)
- Identifiants : Ceux configurés dans ServBay.

Exemple (connexion à un MySQL ServBay) : Si MySQL tourne sur le port 3306, la configuration de votre appli dans Docker ressemblera à :

Host : host.docker.internal
Port : 3306
Utilisateur : your_db_user
Mot de passe : your_db_password

Q4 : Comment permettre à mon conteneur Docker de faire confiance au User CA ServBay pour les sites HTTPS (avec le nom de domaine via `extra_hosts`) ?

Supposons que, conformément à Q2, vous ayez configuré secure.servbay.demo dans extra_hosts ou via --add-host pour pointer vers host-gateway. Si secure.servbay.demo utilise un certificat SSL émis par ServBay User CA, votre conteneur Docker ne fait pas confiance à ce CA par défaut et l’échange SSL échouera.

Chemins d’accès au CA ServBay :

Certificat racine CA User ServBay :
- macOS : /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows : C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
PEM combiné (CA User/Public ServBay et Mozilla) :
- macOS ARM : /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- macOS Intel : /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem
- Windows : C:\ServBay\package\common\openssl\3.3\cacert.pem

Résumé des solutions :

Plusieurs méthodes existent pour rendre le CA ServBay fiable dans un conteneur Docker :

Méthode 1 : Intégration lors de la construction du conteneur (via Dockerfile) — idéale pour des images personnalisables et besoins étendus.
Méthode 2 : Ajout du CA au runtime pour une application spécifique (montage du CA + variables d’environnement) — utile pour appliquer la confiance à une appli ciblée, sans modifier l’image.
Méthode 3 : Mise à jour de la confiance système au runtime (montage + commande personnalisée au démarrage) — pour besoin de confiance sur l’ensemble du système conteneur, sans rebuild d'image.

Méthode 1 : Ajout système lors du build (via Dockerfile)

Le CA ServBay est intégré à l’image Docker lors de son build en ajoutant le fichier au store de confiance système.

Préparez le fichier CA : Copiez le CA racine User ServBay au même niveau que le Dockerfile.
- macOS : /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows : C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt

Exemple Dockerfile (Debian/Ubuntu) :

dockerfile

# Dockerfile
FROM ubuntu:latest
COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
    update-ca-certificates && \
    rm -rf /var/lib/apt/lists/*

Exemple Dockerfile (Alpine) :

dockerfile

# Dockerfile
FROM alpine:latest
COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
RUN apk add --no-cache ca-certificates && update-ca-certificates

Build avec Docker Compose :

yaml

# docker-compose.yml
version: '3.8'
services:
  myapp:
    build:
      context: ./app_service # Dossier contenant Dockerfile et ServBay-Private-CA-ECC-Root.crt
      dockerfile: Dockerfile
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Méthode 2 : Ajout runtime au niveau application (montage volume + variables d’environnement)

Montez le fichier CA dans le conteneur puis configurez l’application pour qu’elle le reconnaisse via une variable d’environnement.

Exemple docker-compose.yml :

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      # Chemin macOS
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      # Chemin Windows (à ajuster selon votre OS)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
    environment:
      # Exemple Node.js :
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Exemple Python (requests) :
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # Exemple générique :
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Veuillez consulter la documentation de votre application pour choisir la variable environnement appropriée.

Méthode 3 : Ajout confiance système au runtime (montage + commande personnalisée)

Vous pouvez monter le CA puis mettre à jour les trusted CA lors du démarrage du conteneur, sans reconstruire l’image — mais cela complexifie le lancement.

Exemple docker-compose.yml (Debian/Ubuntu) :

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # ou image compatible update-ca-certificates
    volumes:
      # Montage du CA directement dans le répertoire système
      # Exemple macOS
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Exemple Windows (ajustez selon OS)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # Commande personnalisée :
    command: >
      sh -c "
        echo 'Mise à jour des certificats CA...' &&
        if command -v update-ca-certificates > /dev/null; then
          if [ ! -f /usr/bin/update-ca-certificates ]; then apt-get update && apt-get install -y --no-install-recommends ca-certificates; fi &&
          update-ca-certificates &&
          echo 'Certificats mis à jour.'
        else
          echo 'update-ca-certificates non trouvé, mise à jour CA ignorée.'
        fi &&
        echo 'Démarrage de l’application...' &&
        exec your_original_application_command_here # À remplacer par la commande de démarrage de l’appli
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # Utilisation temporaire en root si nécessaire pour update-ca-certificates
    # user: root # À ajuster au besoin

Points d'attention :

Complexité : La modification de la commande ou du entrypoint peut se révéler complexe pour des images officielles avec logic startup avancé. Assurez-vous d’appeler correctement la vraie commande d’application.
Droits : La commande update-ca-certificates requiert souvent les droits root.
Dépendances : Le conteneur doit embarquer le paquet ca-certificates et la commande update-ca-certificates. Le script teste et installera éventuellement le paquet si le conteneur utilise apt.
Temps de démarrage : Cette vérification rallongera le démarrage du conteneur.
Alpine Linux : Pour Alpine : apk add --no-cache ca-certificates && update-ca-certificates.

Quelle méthode choisir ?

Si la construction d’image est possible et la confiance CA doit être généralisée, la Méthode 1 est la meilleure.
Pour un besoin localisé ou sans build, préférez Méthode 2.
Si vous ne souhaitez pas modifier ou construire l'image mais voulez un niveau système, la Méthode 3 est adaptée.

Pour les certificats CA publics (type Let's Encrypt) : Si votre site ServBay utilise un certificat acquis auprès d’un CA public via ACME (ex : Let's Encrypt), les images Docker de base font déjà confiance à ces CA et aucune étape supplémentaire n’est requise.

Q5 : Comment attribuer un nom de domaine et activer le proxy inversé ServBay pour une application tournant dans un conteneur Docker ?

Si une application tourne dans un conteneur Docker (par exemple un service Node.js sur le port 3000), vous pouvez utiliser ServBay pour lui attribuer un nom de domaine convivial (ex. : myapp.servbay.demo) accessible par navigateur, tout en profitant de la gestion SSL.

Étapes :

Lancez le conteneur Docker avec mapping du port sur l’hôte 127.0.0.1 : Assurez-vous que votre conteneur mappe son port d’application vers un port local de l’hôte (« binding » sur 127.0.0.1) — pour qu’il soit accessible uniquement en local, jamais depuis le réseau extérieur.
bash
```
# Ex : l’appli écoute sur le port 3000 dans le conteneur, mappée sur 127.0.0.1:3001 sur l’hôte
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
Dans cet exemple : le service est accessible via http://127.0.0.1:3001 sur l’hôte.
Ajoutez un nouveau site dans ServBay et configurez le proxy inversé :
- Allez dans l’interface ServBay.
- Cliquez sur “Ajouter un site”.
- Domaine : Entrez le nom voulu, e.g. : myapp.servbay.demo.
- Type de site : Choisissez “Proxy inversé” dans le menu déroulant.
- Adresse IP : Dans le champ à droite, indiquez 127.0.0.1.
- Port : Entrez le port mappé par Docker : 3001.
- Cliquez sur “Enregistrer” ou “Ajouter”.
(Optionnel) Activez SSL : Après l’ajout, vous pouvez activer SSL via les paramètres du site ServBay. ServBay permet l’obtention automatique de certificats publics via ACME (ex : Let's Encrypt) ou l’utilisation du CA interne ServBay User/ServBay Public CA. ServBay prendra en charge la terminaison SSL ; le routage ServBay vers Docker pourra rester en HTTP (http://127.0.0.1:3001).
Testez l’accès : Une fois configuré, ouvrez votre navigateur et accédez à http://myapp.servbay.demo ou https://myapp.servbay.demo (si SSL activé). ServBay prend en charge l’intermédiation vers l’application dans Docker.

Schéma de fonctionnement : Navigateur utilisateur -> https://myapp.servbay.demo -> ServBay (gère SSL, trouve la règle de proxy) -> http://127.0.0.1:3001 (port localhost hôte) -> application dans le conteneur Docker.

Résumé

ServBay simplifie grandement le développement web local sous macOS et Windows. Lors de l’utilisation avec Docker :

Pour accéder aux sites ServBay depuis un conteneur Docker, configurez le mapping de domaine via extra_hosts ou --add-host vers host-gateway, pour un bon passage de l’en-tête Host et éviter les erreurs SNI.
Pour accéder aux bases de données ou autres services non-HTTP de ServBay depuis Docker, utilisez tout simplement host.docker.internal comme hostname.
Pour que Docker fasse confiance au CA ServBay User pour SSL, intégrez le certificat CA dans l’image et mettez à jour le truststore système.
Pour utiliser le proxy inversé ServBay vers une appli Docker, choisissez “Proxy inversé” comme type de site dans ServBay et rentrez l’IP 127.0.0.1 et le port mappé.

Assurez-vous toujours que les paquets ServBay pertinents (serveur web, base de données...) et vos conteneurs Docker sont opérationnels et correctement configurés.

FAQ : Problèmes fréquents lors de la collaboration entre ServBay et Docker ​

Q1 : Pourquoi ServBay modifie-t-il mon fichier hosts système ? Est-il possible de l’empêcher ? ​

Q2 : Comment mon conteneur Docker peut-il accéder correctement, via le nom de domaine, aux sites gérés par ServBay sur l’hôte (exemple : mysite.servbay.demo) ? ​

Q3 : Comment mon conteneur Docker peut-il se connecter aux bases de données gérées par ServBay (MySQL, PostgreSQL, etc.) ou à d’autres services non-HTTP ? ​

Q4 : Comment permettre à mon conteneur Docker de faire confiance au User CA ServBay pour les sites HTTPS (avec le nom de domaine via extra_hosts) ? ​

Méthode 1 : Ajout système lors du build (via Dockerfile) ​

Méthode 2 : Ajout runtime au niveau application (montage volume + variables d’environnement) ​

Méthode 3 : Ajout confiance système au runtime (montage + commande personnalisée) ​

Q5 : Comment attribuer un nom de domaine et activer le proxy inversé ServBay pour une application tournant dans un conteneur Docker ? ​

Résumé ​

FAQ : Problèmes fréquents lors de la collaboration entre ServBay et Docker

Q1 : Pourquoi ServBay modifie-t-il mon fichier `hosts` système ? Est-il possible de l’empêcher ?

Q2 : Comment mon conteneur Docker peut-il accéder correctement, via le nom de domaine, aux sites gérés par ServBay sur l’hôte (exemple : `mysite.servbay.demo`) ?

Q3 : Comment mon conteneur Docker peut-il se connecter aux bases de données gérées par ServBay (MySQL, PostgreSQL, etc.) ou à d’autres services non-HTTP ?

Q4 : Comment permettre à mon conteneur Docker de faire confiance au User CA ServBay pour les sites HTTPS (avec le nom de domaine via `extra_hosts`) ?

Méthode 1 : Ajout système lors du build (via Dockerfile)

Méthode 2 : Ajout runtime au niveau application (montage volume + variables d’environnement)

Méthode 3 : Ajout confiance système au runtime (montage + commande personnalisée)

Q5 : Comment attribuer un nom de domaine et activer le proxy inversé ServBay pour une application tournant dans un conteneur Docker ?

Résumé