FAQ : Intégration de ServBay et Docker sous macOS

Lorsque vous développez localement avec ServBay, il peut être utile de combiner son utilisation avec des environnements conteneurisés via Docker. Cette FAQ répond aux questions courantes sur la cohabitation de ServBay et Docker, notamment concernant l’accès aux services ServBay depuis Docker, et l’utilisation de ServBay comme proxy inverse vers des applications tournant dans des conteneurs sous macOS.

Q1 : Pourquoi ServBay modifie-t-il le fichier `hosts` de mon système ? Puis-je empêcher cela ?

ServBay ajoute automatiquement des entrées dans votre fichier hosts système (par exemple, mysite.servbay.demo 127.0.0.1) afin que vous puissiez accéder à vos sites de développement locaux à l’aide de domaines personnalisés comme mysite.servbay.demo. Ces sites s’exécutent effectivement sur l’adresse locale 127.0.0.1.

Cependant, à cause des mécanismes de Docker, le fichier hosts du système hôte macOS est lu dans le conteneur, ce qui fait que mysite.servbay.demo est résolu vers 127.0.0.1, amenant Docker à accéder à un service incorrect (le conteneur lui-même).

Principe clé :

Lors de la création d’un site via ServBay et attribution d’un nom de domaine (ex : example.servbay.demo), ServBay le fait pointer automatiquement sur 127.0.0.1.
C’est la méthode standard pour un accès convivial en local par noms de domaine. Sans écriture du fichier hosts, seul un accès via http://127.0.0.1:PORT serait possible, rendant impossible l’utilisation de domaines personnalisés.

Est-il possible de le bloquer ?

En théorie, vous pouvez supprimer manuellement les entrées ajoutées par ServBay, mais cela vous privera de l’accès à vos sites via les domaines définis dans ServBay, ce qui contredit l’objectif de ServBay : faciliter le développement local. L’une des fonctions principales de ServBay est justement de simplifier la création et l’accès à vos sites locaux. Si vous ne souhaitez pas que ServBay gère l’entrée hosts d’un domaine donné, évitez simplement de créer ce domaine dans ServBay.

Dans la plupart des scénarios de développement local, cette automatisation du fichier hosts par ServBay est un comportement souhaité qui facilite grandement le processus de développement.

Q2 : Comment mon conteneur Docker peut-il accéder correctement à un site géré par ServBay via son nom de domaine (ex : `mysite.servbay.demo`) sur macOS ?

C’est une question fréquente qui nécessite une gestion particulière pour éviter des erreurs. Lorsque ServBay fait tourner un site sur votre hôte macOS (par exemple mysite.servbay.demo, résolu sur 127.0.0.1), 127.0.0.1 à l’intérieur d’un conteneur Docker fait référence à la boucle locale du conteneur, et non à celle de votre Mac.

La mauvaise pratique : utiliser directement host.docker.internal comme domaine dans les URLs pour accéder au site ServBay

Bien que Docker Desktop pour Mac (et Windows) fournisse le nom DNS spécial host.docker.internal permettant aux conteneurs de joindre l’IP de l’hôte, il est fortement déconseillé d’utiliser directement ce nom dans l’URL pour accéder à un site web ServBay (par exemple, accéder à http://host.docker.internal/ en espérant atteindre mysite.servbay.demo).

La raison : lors d’un tel accès, l’entête HTTP Host envoyé au serveur (ex : Caddy ou Nginx dans ServBay) sera host.docker.internal, alors que les serveurs web s’appuient sur cette entête pour déterminer quel site servir. Si le Host n’est pas mysite.servbay.demo, le serveur n’identifiera pas le bon site, ou en HTTPS, cela entraînera une erreur SNI (Server Name Indication) puisque le certificat SSL délivré par ServBay est valide pour mysite.servbay.demo et non pour host.docker.internal.

La bonne solution : ajouter le domaine dans le conteneur via extra_hosts

Pour permettre à vos applications dans Docker d’utiliser le nom de domaine originel (ex : mysite.servbay.demo) avec le bon entête Host, ajoutez une entrée dans le fichier /etc/hosts du conteneur pour rediriger ce domaine vers l’IP de l’hôte. Ceci se fait via extra_hosts (avec docker-compose.yml) ou --add-host (avec docker run), de préférence 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 que Docker remplace par l’IP interne de l’hôte. Avec Docker 20.10+, c’est un alias plus bas niveau de host.docker.internal.)

Avec docker-compose.yml :

yaml

version: '3.8' # ou supérieur
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # ou "mysite.servbay.demo:host.docker.internal"
    # ... autre configuration

Après cette configuration, à l'intérieur de votre conteneur Docker :

Lorsque votre application accède à http://mysite.servbay.demo ou https://mysite.servbay.demo, le /etc/hosts du conteneur résout ce domaine vers l’IP de l’hôte macOS.
La requête est envoyée au serveur web ServBay sur l’hôte.
L’entête HTTP Host porte correctement mysite.servbay.demo, ce qui permet à ServBay de router la requête et fournir le bon certificat SSL en HTTPS.

Q3 : Comment mon conteneur Docker peut-il se connecter à une base de données (MySQL, PostgreSQL, etc.) ou à un autre service non-HTTP géré par ServBay ?

Contrairement aux services web nécessitant un nom de domaine, pour se connecter à une base de données ou à tout service TCP sans SNI, il est recommandé et efficace d’utiliser host.docker.internal comme nom d’hôte du serveur.

Étapes :

Vérifiez que le service (base de données, etc.) dans ServBay est démarré et configuré pour accepter les connexions locales (généralement le cas par défaut pour le développement).
À l'intérieur de votre conteneur Docker, configurez la connexion :
- Nom d’hôte (Hostname/Server): host.docker.internal
- Port : Port attribué par ServBay pour ce service (par ex. MySQL : 3306, PostgreSQL : 5432).
- Utilisateur/Mot de passe : identifiants définis dans ServBay.

Exemple (connexion à MySQL géré par ServBay) : Si MySQL tourne sur le port 3306, la configuration de votre app serait :

Hôte : host.docker.internal
Port : 3306
Utilisateur : your_db_user
Mot de passe : your_db_password

Q4 : Comment faire en sorte que mon conteneur Docker fasse confiance au certificat CA ServBay User lorsque j’accède à un site ServBay HTTPS via le nom de domaine (configuré avec `extra_hosts`) ?

Supposons que vous avez suivi la FAQ précédente (Q2), en ajoutant une entrée extra_hosts ou --add-host pour que secure.servbay.demo pointe sur host-gateway. Si secure.servbay.demo utilise un certificat SSL émis par la ServBay User CA, votre conteneur Docker ne la reconnaît pas par défaut, ce qui entraîne un échec de la négociation SSL.

Emplacement du fichier CA ServBay sur votre Mac :

Racine ServBay User CA : /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
Fichier PEM incluant ServBay User CA, Public CA et certificats Mozilla :
- Mac ARM : /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- Mac Intel : /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

Résumé des solutions :

Il y a trois méthodes principales pour rendre la ServBay User CA reconnue côté conteneur Docker :

Méthode 1 : Ajout système lors du build (via Dockerfile) – Idéal pour une confiance générale et si vous pouvez personnaliser l’image.
Méthode 2 : Ajout applicatif à l’exécution (volumes + variables d’environnement) – Idéal quand seule votre application doit faire confiance au CA ou si vous ne voulez pas modifier l’image.
Méthode 3 : Ajout système à l’exécution (volumes + commande d’initialisation personnalisée) – Utile pour faire confiance au CA au niveau système sans modifier l’image.

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

Ajoutez le certificat CA lors de la construction de l’image Docker.

Préparez le fichier CA : Copiez /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt dans le contexte de build Docker (même dossier que le Dockerfile).

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

Exemple docker-compose (build) :

yaml

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

Méthode 2 : Ajout applicatif à l’exécution (volumes + variables d’environnement)

Montez le fichier CA dans le conteneur et configurez l’application pour l’utiliser via une variable d’environnement spécifique.

Exemple docker-compose.yml :

yaml

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

Consultez la documentation de votre application pour savoir quelle variable d’environnement utiliser.

Méthode 3 : Ajout système à l’exécution (volumes + commande personnalisée)

Combinez un montage de volume avec une commande exécutée au démarrage du conteneur pour mettre à jour le magasin de certificats système, sans builder une image personnalisée.

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

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # ou toute image avec update-ca-certificates
    volumes:
      # Monte le CA directement à l’endroit attendu par système
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # Override commande pour mettre à jour les certificats puis lancer l’appli
    # Assurez-vous d’avoir les droits root pour update-ca-certificates
    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 CA mis à jour.'
        else
          echo 'update-ca-certificates non trouvé, CA non mis à jour.'
        fi &&
        echo 'Démarrage de l’application...' &&
        exec your_original_application_command_here # À adapter avec la commande réelle
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # Pour exécuter en root si nécessaire :
    # user: root

Remarques :

Complexité : Modifier command ou entrypoint peut être délicat selon l'image et la logique de démarrage.
Privilèges : update-ca-certificates nécessite généralement les droits root.
Dépendances : Le package ca-certificates doit être installé. Le script tente de l’installer si manquant (pour systèmes apt).
Temps de démarrage : Les vérifications et installations au lancement peuvent rallonger le démarrage.
Pour Alpine Linux : commande à adapter : apk add --no-cache ca-certificates && update-ca-certificates.

Quelle méthode choisir ?

Si vous pouvez builder une image personnalisée et que la confiance au CA doit être globale : méthode 1 recommandée.
Si vous ne voulez pas modifier l’image et que la confiance au CA est requise par une application précise : méthode 2 est simple.
Si vous cherchez un compromis sans builder d’image mais avec une confiance système : méthode 3 est adaptée.

Certificats de CA publics (Let’s Encrypt, etc.) : Si votre site ServBay utilise un certificat public (via ACME, comme Let’s Encrypt), la plupart des images Docker reconnaitront ce CA par défaut et aucune configuration additionnelle n’est nécessaire.

Q5 : Comment utiliser ServBay pour assigner un nom de domaine à une application tournant dans Docker et configurer un reverse proxy ?

Vous pouvez avoir une application (ex : serveur Node.js écoutant sur le port 3000 dans le conteneur) et souhaitez y accéder via un nom de domaine convivial (ex : myapp.servbay.demo) par le navigateur, tout en profitant de la gestion SSL apportée par ServBay.

Étapes :

Lancez le conteneur Docker en mappant son port vers 127.0.0.1 sur l’hôte : Assurez-vous que le port de l’application du conteneur est mappé sur une interface locale uniquement sur le Mac, pour éviter l’exposition directe sur le réseau.
bash
```
# Exemple : l’application écoute 3000, mappée sur 127.0.0.1:3001 sur le Mac
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
Ici, l’appli dans le conteneur (port 3000) est accessible sur l’hôte via http://127.0.0.1:3001.
Ajoutez un nouveau site dans ServBay et configurez le reverse proxy :
- Ouvrez l’interface ServBay.
- Cliquez sur “Ajouter un site”.
- Domaine : Saisissez le domaine souhaité, ex : myapp.servbay.demo.
- Type de site : Sélectionnez “Reverse Proxy”.
- Adresse IP : Entrez 127.0.0.1.
- Port : Indiquez le port hôte Docker ciblé, ex : 3001.
- Cliquez sur “Enregistrer” ou “Ajouter”.
(Optionnel) Configurez SSL : Une fois le site créé, activez SSL dans ses paramètres. ServBay prend en charge l’obtention automatique de certificats via ACME (Let’s Encrypt, etc.) ou l’utilisation de ServBay User CA/Public CA. ServBay gèrera l’arrêt SSL ; la connexion vers le conteneur restera en HTTP (http://127.0.0.1:3001).
Testez l’accès : Une fois la configuration sauvegardée dans ServBay, accédez à http://myapp.servbay.demo ou https://myapp.servbay.demo (si SSL activé). ServBay proxyfiera la requête vers votre application dans le conteneur.

Flux de travail : Navigateur utilisateur -> https://myapp.servbay.demo -> ServBay (SSL / reverse proxy) -> http://127.0.0.1:3001 (hôte) -> application dans Docker.

Résumé

ServBay simplifie grandement le développement web local sous macOS. Lorsqu’il est combiné à Docker :

Pour que vos conteneurs Docker accèdent à un site ServBay, utilisez extra_hosts ou --add-host pour faire pointer le domaine vers host-gateway, ainsi, l’entête Host sera correct et les problèmes SNI seront évités.
Pour accéder à une base de données ou autre service non-HTTP ServBay depuis Docker, le nom d’hôte host.docker.internal est simple et efficace.
Pour faire confiance aux certificats SSL délivrés par ServBay User CA depuis vos conteneurs, copiez le certificat CA dans l’image Docker et mettez à jour le magasin de confiance.
Pour utiliser ServBay comme reverse proxy vers les applications dans Docker, créez un site “Reverse Proxy” dans ServBay qui cible le port adéquat sur 127.0.0.1.

Assurez-vous toujours que les packages nécessaires de ServBay (serveur web, base de données, etc.) et vos conteneurs Docker soient bien démarrés et correctement configurés.

FAQ : Intégration de ServBay et Docker sous macOS ​

Q1 : Pourquoi ServBay modifie-t-il le fichier hosts de mon système ? Puis-je empêcher cela ? ​

Q2 : Comment mon conteneur Docker peut-il accéder correctement à un site géré par ServBay via son nom de domaine (ex : mysite.servbay.demo) sur macOS ? ​

Q3 : Comment mon conteneur Docker peut-il se connecter à une base de données (MySQL, PostgreSQL, etc.) ou à un autre service non-HTTP géré par ServBay ? ​

Q4 : Comment faire en sorte que mon conteneur Docker fasse confiance au certificat CA ServBay User lorsque j’accède à un site ServBay HTTPS via le nom de domaine (configuré avec extra_hosts) ? ​

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

Méthode 2 : Ajout applicatif à l’exécution (volumes + variables d’environnement) ​

Méthode 3 : Ajout système à l’exécution (volumes + commande personnalisée) ​

Q5 : Comment utiliser ServBay pour assigner un nom de domaine à une application tournant dans Docker et configurer un reverse proxy ? ​

Résumé ​

FAQ : Intégration de ServBay et Docker sous macOS

Q1 : Pourquoi ServBay modifie-t-il le fichier `hosts` de mon système ? Puis-je empêcher cela ?

Q2 : Comment mon conteneur Docker peut-il accéder correctement à un site géré par ServBay via son nom de domaine (ex : `mysite.servbay.demo`) sur macOS ?

Q3 : Comment mon conteneur Docker peut-il se connecter à une base de données (MySQL, PostgreSQL, etc.) ou à un autre service non-HTTP géré par ServBay ?

Q4 : Comment faire en sorte que mon conteneur Docker fasse confiance au certificat CA ServBay User lorsque j’accède à un site ServBay HTTPS via le nom de domaine (configuré avec `extra_hosts`) ?

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

Méthode 2 : Ajout applicatif à l’exécution (volumes + variables d’environnement)

Méthode 3 : Ajout système à l’exécution (volumes + commande personnalisée)

Q5 : Comment utiliser ServBay pour assigner un nom de domaine à une application tournant dans Docker et configurer un reverse proxy ?

Résumé