FAQ: Współpraca ServBay i Docker na macOS

Podczas korzystania z ServBay do lokalnego rozwoju stron internetowych możesz chcieć połączyć go z Dockerem i środowiskami kontenerowymi. Niniejsze FAQ odpowiada na najczęstsze pytania związane ze współpracą ServBay i Docker, szczególnie na macOS – m.in. jak uzyskać dostęp do usług ServBay z poziomu kontenerów oraz jak skonfigurować reverse proxy ServBay dla aplikacji uruchamianych w Dockerze.

Q1: Dlaczego ServBay modyfikuje mój plik systemowy `hosts`? Czy mogę temu zapobiec?

ServBay dodaje wpisy do systemowego pliku hosts (np. mysite.servbay.demo 127.0.0.1), abyś mógł używać niestandardowych nazw domen (np. mysite.servbay.demo) do lokalnego dostępu do stron developerskich. Te strony faktycznie działają pod adresem 127.0.0.1 na Twoim komputerze.

Ze względu na mechanizm Dockera, który czyta plik hosts z hosta macOS, wpis mysite.servbay.demo kieruje na 127.0.0.1, co oznacza, że Docker próbuje połączyć się z usługą wewnątrz kontenera zamiast z hostem.

Podstawowy mechanizm:

Tworząc nową stronę w ServBay i przypisując jej domenę (np. example.servbay.demo), ServBay automatycznie kieruje ją na 127.0.0.1.
To standard dla uzyskiwania przyjaznego dostępu lokalnego przez domenę. Bez tej modyfikacji musiałbyś używać adresów typu http://127.0.0.1:PORT.

Czy można temu zapobiec?

Teoretycznie możesz ręcznie usunąć wpisy dodane przez ServBay, ale wtedy nie będziesz mógł korzystać z własnych domen do lokalnego rozwoju, co jest sprzeczne z ideą ułatwionej pracy. Jednym z głównych celów ServBay jest uproszczenie tworzenia i obsługi lokalnych stron. Jeśli nie chcesz, by ServBay zarządzał wpisem hosts dla danej domeny, najlepiej nie twórz dla niej strony w ServBay.

W większości przypadków automatyczne zarządzanie plikiem hosts przez ServBay upraszcza pracę przy lokalnym developmencie.

Q2: Jak pozwolić kontenerowi Docker poprawnie uzyskać dostęp przez nazwę domeny do serwisu zarządzanego przez ServBay na macOS (np. `mysite.servbay.demo`)?

To bardzo częsta potrzeba, wymagająca jednak poprawnej konfiguracji. Gdy ServBay uruchamia stronę (np. mysite.servbay.demo, kierującą na hosta 127.0.0.1), to w środku kontenera Docker adres 127.0.0.1 wskazuje na sam kontener, a nie na macOS.

Błędna metoda: bezpośrednie użycie host.docker.internal jako hosta w URL przy dostępie do strony ServBay

Docker Desktop dla Mac (oraz Windows) udostępnia specjalną nazwę DNS host.docker.internal, przekierowującą z kontenera na IP hosta, ale stanowczo odradza się jej używania w URL do stron ServBay (np. http://host.docker.internal/ w miejsce mysite.servbay.demo).

Dzieje się tak dlatego, że nagłówek HTTP Host będzie miał wartość host.docker.internal, a serwer www ServBay (Caddy lub Nginx) używa tego nagłówka do rozpoznania, do której strony kierować ruch. W efekcie taka nazwa hosta nie pozwala zidentyfikować poprawnie żądanej strony. Przy HTTPS wywoła to także błąd SNI (Server Name Indication), bo SSL zostanie wydany dla mysite.servbay.demo, a nie host.docker.internal.

Poprawne rozwiązanie: dodaj extra_hosts przy uruchamianiu Dockera

By aplikacja w kontenerze mogła korzystać z oryginalnej domeny ServBay (mysite.servbay.demo) i prawidłowo wysłać nagłówek Host, podczas uruchamiania kontenera należy dodać wpis do /etc/hosts, wskazujący tę domenę na IP hosta. Można to zrobić przez extra_hosts (w docker-compose.yml) lub --add-host (docker run), wskazując domenę na host.docker.internal lub – zalecane – na host-gateway.

Użycie docker run:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway to specjalna wartość, którą Docker zamienia na wewnętrzny IP hosta. Od Dockera 20.10+ to domyślne aliasowanie do host.docker.internal.)

W pliku docker-compose.yml:

yaml

version: '3.8' # lub wyższa
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # lub "mysite.servbay.demo:host.docker.internal"
    # ... inne ustawienia

Po tej konfiguracji, wewnątrz kontenera:

Aplikacja próbując skomunikować się przez http://mysite.servbay.demo lub https://mysite.servbay.demo, rozwiąże domenę do IP hosta.
Żądanie trafi do SerwBay na komputerze macOS.
Nagłówek Host będzie miał wartość mysite.servbay.demo, a ServBay poprawnie obsłuży żądanie, włączając właściwy certyfikat SSL dla HTTPS.

Q3: Jak połączyć kontener Docker z bazą danych zarządzaną przez ServBay (np. MySQL, PostgreSQL) lub inną usługą TCP?

W przeciwieństwie do usług www przez domenę, do połączeń z bazami danych czy innymi usługami TCP (niewymagającymi SNI) zaleca się i jest skuteczne używanie jako hosta host.docker.internal.

Kolejne kroki:

Upewnij się, że baza danych (lub inna usługa) w ServBay jest uruchomiona i pozwala na połączenia z hosta (standardowe ustawienia są zwykle wystarczające).
W kontenerze Docker ustaw do łączenia się z bazą danych:
- Host: host.docker.internal
- Port: port usługi/bazy danych skonfigurowany w ServBay (np. MySQL domyślnie 3306, PostgreSQL 5432).
- Użytkownik/hasło: zgodnie z konfiguracją w ServBay.

Przykład (połączenie z MySQL via ServBay): Załóżmy, że MySQL ServBay działa na porcie 3306. W aplikacji w kontenerze:

Host: host.docker.internal
Port: 3306
Użytkownik: your_db_user
Hasło: your_db_password

Q4: Kontener Docker łączy się przez domenę (z użyciem `extra_hosts`) do strony HTTPS zarządzanej przez ServBay (z certyfikatem ServBay User CA). Jak sprawić, by kontener ufał temu CA?

Zakładamy, że wg. instrukcji Q2 dodałeś wpis extra_hosts lub --add-host, kierując secure.servbay.demo na host-gateway. Jeśli ta domena korzysta z certyfikatu ServBay User CA, kontener Docker domyślnie nie ufa temu CA i połączenie HTTPS zakończy się błędem podczas handshake SSL.

Ścieżki do CA ServBay na macOS:

Główny certyfikat ServBay User CA: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
PEM z CA ServBay User + Public + Mozilla:
- Mac ARM: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
- Mac Intel: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

Możliwe rozwiązania:

Są trzy sposoby, by kontener Docker zaczął ufać ServBay User CA:

Metoda 1: Wbudowane zaufanie systemowe (w Dockerfile) – zalecane, gdy budujesz własny obraz i wiele aplikacji potrzebuje zaufania do CA.
Metoda 2: Zaufanie aplikacyjne w runtime (wolumen + zmienna środowiskowa) – do pojedynczych aplikacji/dziłających poza standardowymi ścieżkami.
Metoda 3: Systemowe zaufanie w runtime (wolumen + komenda startowa) – gdy nie budujesz obrazu a chcesz systemowe zaufanie w trakcie uruchomienia.

Metoda 1: Systemowe zaufanie przy budowie (Dockerfile)

Podczas budowania obrazu Docker integrujemy CA w systemowy store zaufanych certyfikatów.

Przygotuj plik CA: Skopiuj /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt do katalogu z Dockerfile.

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

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

Budowanie z Docker Compose:

yaml

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

Metoda 2: Zaufanie aplikacyjne w czasie uruchomienia (volumes + env)

Montujemy plik CA do kontenera i przekazujemy zmienną środowiskową aplikacji korzystającej z tego certyfikatu.

Fragment 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:
      # Przykład dla Node.js:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Przykład dla Python (requests):
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # Ogólne SSL_CERT_FILE:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Sprawdź dokumentację aplikacji w celu dobrania właściwej zmiennej środowiskowej.

Metoda 3: Systemowe zaufanie w runtime (volumes + komenda startowa)

Łączy wolumen i polecenie odświeżenia zaufanych CA przy starcie kontenera. Nie wymaga budowania nowego obrazu, ale komplikuje komendę startową.

docker-compose.yml (Debian/Ubuntu):

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # lub inny kompatybilny z update-ca-certificates
    volumes:
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # Custom command uruchamia najpierw update CA, potem aplikację
    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 # zamień na prawdziwą komendę uruchamiającą aplikację
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # Jeśli wymagane, zmień user na root lub zadbaj o uprawnienia
    # user: root # lub użyj własnego entrypointa

Uwaga:

Złożoność: Modyfikacja komendy startowej może być problematyczna dla obrazów z niestandardowym entrypointem. Upewnij się, że właściwie uruchamiasz aplikację.
Uprawnienia: Komenda update-ca-certificates musi być wykonywana przez root’a.
Pakiety: W kontenerze musi być zainstalowany pakiet ca-certificates.
Czas startu: Update CA przy każdym uruchomieniu spowalnia start.
Alpine Linux: Użyj apk add --no-cache ca-certificates && update-ca-certificates zamiast apt-get.

Jaka metoda jest najlepsza?

Jeśli tworzysz własny obraz i chcesz zaufania systemowego – Metoda 1.
Jeśli nie możesz modyfikować obrazu i wystarczy zaufanie tylko do pojedynczej aplikacji – Metoda 2.
Jeśli nie chcesz customizacji obrazu, ale wymagasz zaufania systemowego – Metoda 3.

W przypadku certyfikatów wydanych przez publiczne CA (np. Let's Encrypt): Gdy Twoja strona w ServBay używa certyfikatu z Let's Encrypt, większość oficjalnych obrazów Dockera domyślnie już mu ufa i nie musisz nic więcej robić.

Q5: Jak skonfigurować domenę dla aplikacji działającej w kontenerze Docker przez ServBay i reverse proxy?

Załóżmy, że masz aplikację w Dockerze (np. Node.js na porcie 3000) i chcesz, by była dostępna z hosta pod własną domeną (np. myapp.servbay.demo) przez ServBay oraz korzystała z certyfikatów SSL zarządzanych przez ServBay.

Kroki:

Uruchom kontener Dockera z mapowaniem portu na hosta 127.0.0.1: Upewnij się, że port aplikacji jest mapowany na port dostępny TYLKO lokalnie (127.0.0.1) – to ogranicza dostęp tylko do hosta macOS.
bash
```
# Przykład: aplikacja w kontenerze słucha na 3000, hostuje się na 127.0.0.1:3001
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
Teraz aplikacja dostępna jest przez http://127.0.0.1:3001.
Dodaj nową stronę w ServBay jako reverse proxy:
- Przejdź do panelu ServBay.
- Kliknij „Dodaj stronę”.
- Domena: Wprowadź np. myapp.servbay.demo.
- Typ witryny: Wybierz „Reverse Proxy”.
- Adres IP: Podaj 127.0.0.1.
- Port: Wpisz port, na który mapujesz kontener (tu: 3001).
- Zapisz ustawienia.
(Opcjonalnie) Skonfiguruj SSL: Po dodaniu strony w ServBay możesz ją skonfigurować dla HTTPS (SSL). ServBay może samodzielnie generować certyfikaty Let's Encrypt, bądź używać ServBay User CA/Public CA. Terminuje SSL "przed" reverse proxy, komunikacja z Dockerem po HTTP.
Testuj dostęp: Po zapisaniu konfiguracji ServBay, spróbuj wejść w przeglądarce na http://myapp.servbay.demo lub https://myapp.servbay.demo (w zależności od SSL). ServBay przekieruje ruch do aplikacji pracującej w kontenerze Docker.

Opis działania: Przeglądarka użytkownika -> https://myapp.servbay.demo -> ServBay (obsługa SSL, reverse proxy) -> http://127.0.0.1:3001 (port na hoście) -> aplikacja wewnątrz kontenera Docker.

Podsumowanie

ServBay bardzo upraszcza lokalny rozwój www na macOS. W połączeniu z Docker:

Aby uzyskać dostęp z kontenera Docker do strony hostowanej przez ServBay, użyj extra_hosts lub --add-host, by skierować domenę na host-gateway – zapewnisz poprawny nagłówek Host i unikniesz problemów SNI.
Aby łączyć się z bazami danych lub innymi usługami nie-HTTP przez Docker, użyj jako hosta host.docker.internal.
Aby kontener Docker ufał certyfikatom SSL wystawionym przez ServBay User CA, dołącz certyfikat CA do obrazu (lub montuj jako wolumen) i zaktualizuj store zaufanych CA.
Aby reverse proxy ServBay przekierowało ruch do aplikacji w kontenerze Docker, skonfiguruj „reverse proxy” i wskaż odpowiedni port na 127.0.0.1.

Dbaj o to, by wszystkie wymagane pakiety ServBay (serwery www, bazy danych) oraz kontenery Docker były prawidłowo skonfigurowane i uruchomione.

FAQ: Współpraca ServBay i Docker na macOS ​

Q1: Dlaczego ServBay modyfikuje mój plik systemowy hosts? Czy mogę temu zapobiec? ​

Q2: Jak pozwolić kontenerowi Docker poprawnie uzyskać dostęp przez nazwę domeny do serwisu zarządzanego przez ServBay na macOS (np. mysite.servbay.demo)? ​

Q3: Jak połączyć kontener Docker z bazą danych zarządzaną przez ServBay (np. MySQL, PostgreSQL) lub inną usługą TCP? ​

Q4: Kontener Docker łączy się przez domenę (z użyciem extra_hosts) do strony HTTPS zarządzanej przez ServBay (z certyfikatem ServBay User CA). Jak sprawić, by kontener ufał temu CA? ​

Metoda 1: Systemowe zaufanie przy budowie (Dockerfile) ​

Metoda 2: Zaufanie aplikacyjne w czasie uruchomienia (volumes + env) ​

Metoda 3: Systemowe zaufanie w runtime (volumes + komenda startowa) ​

Q5: Jak skonfigurować domenę dla aplikacji działającej w kontenerze Docker przez ServBay i reverse proxy? ​

Podsumowanie ​

FAQ: Współpraca ServBay i Docker na macOS

Q1: Dlaczego ServBay modyfikuje mój plik systemowy `hosts`? Czy mogę temu zapobiec?

Q2: Jak pozwolić kontenerowi Docker poprawnie uzyskać dostęp przez nazwę domeny do serwisu zarządzanego przez ServBay na macOS (np. `mysite.servbay.demo`)?

Q3: Jak połączyć kontener Docker z bazą danych zarządzaną przez ServBay (np. MySQL, PostgreSQL) lub inną usługą TCP?

Q4: Kontener Docker łączy się przez domenę (z użyciem `extra_hosts`) do strony HTTPS zarządzanej przez ServBay (z certyfikatem ServBay User CA). Jak sprawić, by kontener ufał temu CA?

Metoda 1: Systemowe zaufanie przy budowie (Dockerfile)

Metoda 2: Zaufanie aplikacyjne w czasie uruchomienia (volumes + env)

Metoda 3: Systemowe zaufanie w runtime (volumes + komenda startowa)

Q5: Jak skonfigurować domenę dla aplikacji działającej w kontenerze Docker przez ServBay i reverse proxy?

Podsumowanie