FAQ zur Zusammenarbeit von ServBay und Docker unter macOS

Wenn Sie für die lokale Webentwicklung ServBay nutzen, möchten Sie möglicherweise die Vorteile von Docker-Containern einbinden. Dieses FAQ beantwortet häufige Fragen rund um die gemeinsame Nutzung von ServBay und Docker auf macOS – insbesondere, wie Sie ServBay-Dienste aus Docker heraus erreichen und Anwendungen innerhalb von Docker-Containern mit dem ServBay Reverse Proxy verbinden.

Q1: Warum verändert ServBay meine systemeigene hosts-Datei? Kann ich das verhindern?

ServBay fügt Ihrer systemeigenen hosts-Datei Einträge hinzu (z. B. mysite.servbay.demo 127.0.0.1), damit Sie lokale Entwicklungswebseiten komfortabel über eigene Domänennamen wie mysite.servbay.demo aufrufen können. Tatsächlich laufen diese Webseiten auf 127.0.0.1 Ihres Rechners.

Durch Dockers Funktionsweise wird allerdings die hosts-Datei vom Host (macOS) an den Container weitergegeben: mysite.servbay.demo wird in Docker somit auf 127.0.0.1 aufgelöst und verweist fälschlicherweise auf den Container selbst statt auf die ServBay-Website auf dem Host.

Grundprinzip:

• Wenn Sie in ServBay eine neue Website mit eigenem Domainnamen (z. B. example.servbay.demo) erstellen, wird dieser automatisch auf 127.0.0.1 gemappt.
• Das ist Standardpraxis für komfortablen lokalen Domainzugriff. Ohne Änderungen an der hosts-Datei könnten Sie die Seite nur über die IP und Port, z. B. http://127.0.0.1:PORT, jedoch nicht unter dem Wunschnamen aufrufen.

Kann ich das verhindern?

Theoretisch können Sie die von ServBay gesetzten Einträge manuell entfernen. Dann wäre jedoch kein bequemer Zugriff über die lokal konfigurierten Domänennamen mehr möglich, was Sinn und Zweck von ServBay – eine einfache lokale Entwicklungsumgebung – widerspräche. Einer der Hauptvorteile von ServBay ist gerade die Vereinfachung von Website-Erstellung und -Zugriff. Wenn Sie nicht möchten, dass ServBay für eine bestimmte Domain Änderungen an der hosts-Datei vornimmt, legen Sie für diese Domain keine Website in ServBay an.

Für die meisten lokalen Entwicklungsfälle ist das automatische Management der hosts-Datei durch ServBay durchaus erwünscht und beschleunigt den Workflow erheblich.

Q2: Wie kann mein Docker-Container über den Domainnamen auf von ServBay unter macOS bereitgestellte Webseiten zugreifen (z. B. mysite.servbay.demo)?

Das ist eine häufige Anforderung, erfordert jedoch eine gezielte Konfiguration, um Probleme zu vermeiden. Wenn ServBay z. B. eine Seite unter mysite.servbay.demo anbietet (die auf dem Host auf 127.0.0.1 gemappt ist), verweist 127.0.0.1 innerhalb des Containers auf diesen selbst – nicht auf den macOS-Host.

Falscher Weg: Direkt über host.docker.internal die ServBay-Seite aufrufen

Obwohl Docker Desktop für Mac (und Windows) per host.docker.internal eine Möglichkeit bietet, vom Container aus den Host zu erreichen, sollte diese DNS-Adresse nicht direkt in der URL benutzt werden (z. B. http://host.docker.internal/ um die ServBay-Website zu finden).

Der Grund: Die HTTP-Anfrage enthält dann als Host-Header host.docker.internal und nicht mysite.servbay.demo. Der ServBay-Webserver (z. B. Caddy oder Nginx) entscheidet anhand des Host-Headers, welcher virtuelle Host ausgeliefert wird. Ist der Wert hier nicht korrekt, kann ServBay die Anfrage nicht richtig routen und bei HTTPS-Verbindungen kommt es zudem zu SNI (Server Name Indication) Fehlern, weil das bereitgestellte SSL-Zertifikat zu mysite.servbay.demo passt, nicht aber zu host.docker.internal.

Lösung: Beim Start des Docker-Containers extra_hosts setzen

Damit Anwendungen im Container den originalen Domainnamen (z. B. mysite.servbay.demo) mit dem richtigen Host-Header verwenden können, ist ein Eintrag in die /etc/hosts-Datei des Containers nötig. Das erreichen Sie per extra_hosts (in docker-compose.yml) oder per --add-host (bei docker run) – jeweils mit einem Verweis auf host.docker.internal oder noch besser auf host-gateway.

• Mit docker run:

  docker run --add-host=mysite.servbay.demo:host-gateway ... your_image

  (host-gateway ist dabei ein spezieller Platzhalter, der von Docker zur internen IP des Hosts aufgelöst wird – ab Docker 20.10+ eine stabile, tieferliegende Variante von host.docker.internal.)

• Mit docker-compose.yml:

  version: '3.8' # oder neuer
  services:
    myapp:
      image: your_image
      extra_hosts:
        - "mysite.servbay.demo:host-gateway" # oder "mysite.servbay.demo:host.docker.internal"
      # ... weitere Einstellungen

Nach der Konfiguration gilt innerhalb des Containers:

1. Ruft Ihre Anwendung z. B. http://mysite.servbay.demo oder https://mysite.servbay.demo auf, wird dieser Name gemäß /etc/hosts auf die Host-IP aufgelöst.
2. Die Anfrage erreicht den auf dem Host laufenden ServBay-Webserver.
3. Der Host-Header ist korrekt gesetzt und ServBay kann die Anfrage passend routen und das richtige SSL-Zertifikat ausliefern (bei HTTPS).

Q3: Wie kann mein Docker-Container auf von ServBay gemanagte Datenbanken (MySQL, PostgreSQL) oder andere nicht-HTTP-Dienste zugreifen?

Anders als beim Webseitenzugriff (wo SNI und Host-Header eine Rolle spielen), ist für TCP-basierte Dienste wie Datenbanken der Verbindungsaufbau per host.docker.internal empfohlen und problemlos.

So geht's:

1. Stellen Sie sicher, dass die gewünschte ServBay-Datenbank (oder Dienst) läuft und lokale Verbindungen akzeptiert (dies ist bei lokalen Development-Setups die Standardeinstellung).
2. Konfigurieren Sie im Container Ihre Datenbankverbindung:
   • Hostname/Server: host.docker.internal
   • Port: Der in ServBay konfigurierte Port der Datenbank, z. B. standardmäßig 3306 für MySQL, 5432 für PostgreSQL
   • Nutzer/Passwort: Die in ServBay vergebenen Zugangsdaten.

Beispiel (Verbindung zu MySQL in ServBay): Angenommen, MySQL läuft unter Port 3306, verwenden Sie im Container:

• Host: host.docker.internal
• Port: 3306
• Benutzer: your_db_user
• Passwort: your_db_password

Q4: Wie kann mein Docker-Container beim Zugriff auf eine durch ServBay (User CA) ausgestellte HTTPS-Seite per Domainname (über extra_hosts konfiguriert) der CA vertrauen?

Wenn Sie nach Q2 z. B. secure.servbay.demo gezielt auf host-gateway gelenkt haben und ServBay für diese Seite ein SSL-Zertifikat der ServBay User CA nutzt, wird dieses Zertifikat im Container standardmäßig nicht als vertrauenswürdig eingestuft. Die Folge sind fehlgeschlagene SSL-Verbindungen (z. B. bei cURL, Node.js, Python).

Pfad zur ServBay-CA auf dem Host (macOS):

• ServBay User CA Root-Zertifikat: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
• PEM mit ServBay User CA, Public CA und Mozilla Roots:
  • ARM-Mac: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
  • Intel-Mac: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

Lösungsansätze:

Je nach Anwendungsfall gibt es drei gängige Methoden, um dem Container die ServBay-CA bekannt zu machen:

1. Variante 1: Systemweite Vertrauensstellung beim Build (via Dockerfile)
   Empfohlen, wenn Sie das Basisimage selbst bauen und generell eine CA für alle Systemtools/Anwendungen hinterlegen möchten.
2. Variante 2: Anwendungsbezogene Vertrauensstellung zur Laufzeit (via Volume und Umgebungsvariablen)
   Geeignet, wenn Sie nur eine bestimmte App oder Bibliothek anpassen möchten und das Image nicht selbst bauen.
3. Variante 3: Systemweite Vertrauensstellung zur Laufzeit (via Volume und Command) Nutzt ebenfalls Volumes, erweitert das CA-Truststore beim Start. Eignet sich, wenn Sie das Basisimage nicht anpassen, aber systemweite Trust benötigen.

Variante 1: Systemweite Vertrauensstellung beim Build (via Dockerfile)

Sie binden das CA-Zertifikat bereits beim Bauen des Images ins System ein.

• CA-Datei vorbereiten: Kopieren Sie /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt ins Build-Verzeichnis (wo die Dockerfile liegt).
• Dockerfile Beispiel für Debian/Ubuntu:

  # 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/*

• Dockerfile Beispiel für Alpine:

  # 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

• Docker Compose Build-Konfiguration:

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

Variante 2: Anwendungsbezogene Vertrauensstellung zur Laufzeit (mit Volume & Env)

Das CA-Zertifikat wird zur Laufzeit ins Image gemountet und per Umgebungsvariable der Anwendung „eingereicht“.

• docker-compose.yml Beispiel:

  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:
        # Beispiel für Node.js:
        - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
        # Beispiel für Python (requests):
        # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
        # Beispiel für generisch (SSL_CERT_FILE):
        # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
      extra_hosts: ["secure.servbay.demo:host-gateway"]

  Prüfen Sie in der Doku Ihrer jeweiligen Anwendung, welche Variable gesetzt werden muss.

Variante 3: Systemweite Vertrauensstellung zur Laufzeit (Volume & Custom Command)

Das CA-Zertifikat wird ins Standardverzeichnis gemountet und beim Containerstart in die Trust-DB aufgenommen. Das eignet sich für Quick&Dirty-Lösungen ohne Image-Build, ist aber in Startkommandos etwas aufwändiger.

• docker-compose.yml Beispiel (Debian/Ubuntu-Image):

  version: '3.8'
  services:
    myapp:
      image: ubuntu:latest # oder ein beliebiges Image mit update-ca-certificates
      volumes:
        # Mount CA-Zertifikat direkt ins Trustverzeichnis
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Startbefehl überschreiben: erst Zertifikate aktualisieren, dann Anwendung starten
      command: >
        sh -c "
          echo 'Attempting to update CA certificates...' &&
          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 'CA certificates updated.'
          else
            echo 'update-ca-certificates command not found, skipping CA update.'
          fi &&
          echo 'Starting application...' &&
          exec your_original_application_command_here # Ersetzen durch das eigentliche Startkommando
        "
      extra_hosts: ["secure.servbay.demo:host-gateway"]
      # Falls root nötig ist, ggf. noch optionale Einträge für Benutzerrechte
      # user: root

  Hinweise:
  • Komplexität: Das Überschreiben des Startbefehls ist bei Images mit komplexen Startskripten aufwändig.
  • Berechtigungen: Für update-ca-certificates ist root nötig – ggf. Rechte anpassen.
  • Paketabhängigkeiten: Das Paket ca-certificates sowie das Kommando müssen im Container installiert sein; das Skript installiert dies notfalls.
  • Startzeit: Bei jedem Start werden diese Schritte erneut ausgeführt, das dauert etwas länger.
  • Bei Alpine Linux: Dort ist stattdessen apk add --no-cache ca-certificates && update-ca-certificates nötig.

Welche Methode wählen?

• Wenn Sie Images selbst bauen und die CA komplett im Container vertrauenswürdig machen möchten: Variante 1 ist die beste Wahl.
• Wenn Sie bestimmte Anwendungen anpassen möchten und am Image nichts ändern möchten: Variante 2.
• Wenn Sie keine Images bauen, aber systemweite Trust benötigen und Startkommandos anpassen können: Variante 3.

Für durch öffentliche CAs ausgestellte Zertifikate (z. B. Let's Encrypt): Nutzen Sie auf ServBay Webzertifikate einer öffentlichen CA (ACME, Let's Encrypt), sind diese meist schon in allen gängigen Docker-Images als vertrauenswürdig hinterlegt; keine weiteren Maßnahmen nötig.

Q5: Wie kann ich einer im Docker-Container laufenden Anwendung einen Domainnamen zuweisen und sie per ServBay Reverse Proxy erreichbar machen?

Sie betreiben z. B. im Docker-Container eine Anwendung (z. B. Node.js, Port 3000) und möchten diese komfortabel mit einem Domainnamen (myapp.servbay.demo) im Browser aufrufen – inkl. SSL und Reverse Proxy über ServBay.

So gehen Sie vor:

1. Docker-Container starten und Port an die 127.0.0.1 des Hosts binden: Wichtig: Die Portweiterleitung auf Ihrem Mac sollte immer an 127.0.0.1 gebunden werden, damit der Containerport nur lokal, nicht im gesamten Netzwerk, erreichbar ist.

   # Beispiel: App hört im Container auf Port 3000, erreichbar über 127.0.0.1:3001 des Hosts
   docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image

   In diesem Setup ist die App im Container über http://127.0.0.1:3001 am Mac verfügbar.

2. In ServBay einen neuen Website-Eintrag als Reverse Proxy anlegen:

   • Öffnen Sie das ServBay-Interface.
   • Klicken Sie auf „Website hinzufügen“.
   • Domain: Gewünschter Domainname, z. B. myapp.servbay.demo.
   • Website-Typ: Im Dropdown „Reverse Proxy“ auswählen.
   • IP-Adresse: Rechts in das Feld 127.0.0.1 eintragen.
   • Port: Den unter 1. in Docker gemappten Host-Port angeben, z. B. 3001.
   • Speichern.

3. (Optional) SSL einrichten: Nach dem Anlegen können Sie SSL für die Seite in den Einstellungen aktivieren. ServBay unterstützt ACME-basierte Zertifikate (z. B. Let's Encrypt) sowie selbstsignierte (ServBay User CA/ServBay Public CA). Die SSL-Verbindung wird dabei vom ServBay-Webserver terminiert, der Reverse-Proxy-Zugriff vom ServBay-Server auf den Container bleibt HTTP (z. B. http://127.0.0.1:3001).

4. Testen: Mit der gespeicherten Konfiguration rufen Sie nun im Browser http://myapp.servbay.demo oder – falls SSL aktiviert ist – https://myapp.servbay.demo auf. ServBay leitet die Anfragen an die Anwendung im Container weiter.

Ablauf: Browser des Nutzers -> https://myapp.servbay.demo -> ServBay (Übernahme von SSL, Routing per Proxy-Regeln) -> http://127.0.0.1:3001 (Host:localhost, wird an den Container weitergereicht) -> Webanwendung im Container.

Zusammenfassung

ServBay erleichtert die lokale Webentwicklung auf dem Mac enorm. In Verbindung mit Docker gilt:

• Für den Zugriff auf von ServBay gehostete Websites im Container nutzen Sie immer extra_hosts/--add-host, damit der Domainname auf host-gateway gemappt wird – so stimmt der Host-Header und SNI-Probleme werden vermieden.
• Für den Zugriff auf von ServBay gehostete Datenbanken oder sonstige Nicht-HTTP-Dienste reicht es, als Hostnamen host.docker.internal zu verwenden.
• Um SSL-Zertifikate der ServBay User CA im Container als vertrauenswürdig einzustufen, binden Sie das Zertifikat ins Image ein und aktualisieren Sie den CA-Store.
• Für Reverse-Proxys von ServBay zu Containeranwendungen: In ServBay immer als „Reverse Proxy“-Website anlegen und den jeweiligen lokalen Port (127.0.0.1:PORT) angeben.

Stellen Sie abschließend sicher, dass die relevanten ServBay-Softwarepakete (Webserver, Datenbank usw.) sowie Ihre Docker-Container korrekt konfiguriert und gestartet sind.