FAQ – Collaborazione tra ServBay e Docker su macOS

Quando utilizzi ServBay per lo sviluppo web locale, potresti voler combinare l'ambiente con Docker per la containerizzazione. Questa FAQ risponde alle domande più comuni relative all'uso integrato di ServBay e Docker su macOS, comprese le modalità per accedere ai servizi ServBay da Docker e per utilizzare ServBay come reverse proxy per applicazioni all'interno dei container.

Q1: Perché ServBay modifica il file hosts del mio sistema? Posso impedirlo?

ServBay aggiunge voci personalizzate nel file hosts del sistema (ad esempio mysite.servbay.demo 127.0.0.1) per consentirti di accedere ai siti in sviluppo tramite nomi di dominio locali personalizzati come mysite.servbay.demo. Questi siti risiedono effettivamente sull'indirizzo 127.0.0.1 della tua macchina.

Tuttavia, a causa del funzionamento di Docker, il file hosts viene caricato anche nei container da macOS—quindi mysite.servbay.demo verrà risolto in 127.0.0.1 all'interno del container, portando Docker a puntare verso se stesso, non verso ServBay sulla macchina host.

Dettagli tecnici:

• Quando crei un nuovo sito in ServBay e assegni un dominio (es. example.servbay.demo), ServBay reindirizza automaticamente quel dominio a 127.0.0.1.
• Questa è la prassi standard per consentire l'accesso tramite nome di dominio ai siti in sviluppo. Se non si modificasse il file hosts, saresti costretto ad accedere tramite http://127.0.0.1:PORT, senza la comodità di un dominio personalizzato.

È possibile impedirlo?

In teoria puoi rimuovere manualmente le voci aggiunte da ServBay, ma perderesti la possibilità di accedere al sito tramite i domini configurati, andando contro lo scopo di ServBay di semplificare lo sviluppo locale. Funzionalità come la gestione automatica dei domini tramite il file hosts sono uno dei pilastri di ServBay. Se vuoi evitare la gestione delle voci hosts per un determinato dominio, ti consigliamo di non creare quel sito su ServBay.

Per la maggior parte degli sviluppatori web locali, la gestione automatica del file hosts da parte di ServBay è desiderata e rende il flusso di lavoro molto più fluido.

Q2: Come può un container Docker accedere correttamente al sito gestito da ServBay su macOS tramite dominio (es. mysite.servbay.demo)?

Questa è una richiesta comune, ma va gestita con attenzione per evitare problemi. Quando ServBay esegue un sito sulla macchina host macOS (ad es. mysite.servbay.demo, che punta a 127.0.0.1), il container Docker interpreta 127.0.0.1 come il proprio loopback—non quello della macchina host.

Soluzione errata: usare direttamente host.docker.internal nel campo dominio dell'URL

Anche se Docker Desktop per Mac (e Windows) fornisce il DNS host.docker.internal per accedere all'IP della macchina host dal container, non è raccomandato usarlo come host direttamente nell'URL per accedere ai siti ServBay (cioè, non tentare di accedere a http://host.docker.internal/ sperando che richiami mysite.servbay.demo).

Il motivo è che così facendo, l'header Host inviato al web server (Caddy o Nginx gestito da ServBay) sarà host.docker.internal e non mysite.servbay.demo. ServBay si basa proprio sull'header Host per instradare correttamente la richiesta. Un errore nel campo Host può impedire il corretto instradamento o generare errori SNI (Server Name Indication) con i certificati SSL, dato che il certificato sarà valido per mysite.servbay.demo e non per host.docker.internal.

Soluzione corretta: aggiungere la voce con extra_hosts al lancio del container

Per far sì che le applicazioni in container possano accedere tramite il vero dominio (es. mysite.servbay.demo) con l'header corretto, occorre aggiungere una voce nel file /etc/hosts del container che punti quel dominio verso l'IP della macchina host. Puoi farlo mediante extra_hosts (in docker-compose.yml) o --add-host (con docker run), indirizzando a host.docker.internal oppure, meglio ancora, a host-gateway.

• Con docker run:

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

  (host-gateway è un valore speciale: Docker lo sostituisce con l’IP interno dell’host, dal Docker 20.10+ è preferito rispetto a host.docker.internal.)

• Con docker-compose.yml:

  version: '3.8' # o superiore
  services:
    myapp:
      image: your_image
      extra_hosts:
        - "mysite.servbay.demo:host-gateway" # Oppure "mysite.servbay.demo:host.docker.internal"
      # ... altri parametri

Una volta configurato, all'interno del container:

1. Le richieste verso http://mysite.servbay.demo o https://mysite.servbay.demo verranno risolte via /etc/hosts all'IP della macchina host.
2. La richiesta giungerà sul web server ServBay in esecuzione su macOS.
3. L'header HTTP Host sarà correttamente impostato su mysite.servbay.demo, permettendo il corretto instradamento e la consegna del certificato SSL adeguato (se in HTTPS).

Q3: Come può un container Docker connettersi ai database (come MySQL, PostgreSQL) o ad altri servizi non-HTTP gestiti da ServBay?

A differenza dei servizi web, per database o servizi TCP che non richiedono SNI, è consigliato e funziona usare host.docker.internal come host nella stringa di connessione.

Procedura:

1. Assicurati che il database ServBay o altro servizio sia in esecuzione e con configurazione predefinita che consenta connessioni dalla macchina host.

2. Nel container Docker, configura la connessione usando:

   • Host/server: host.docker.internal
   • Porta: quella configurata su ServBay per il database (ad es. MySQL 3306, PostgreSQL 5432)
   • Credenziali: usa username e password impostati su ServBay.

   Esempio (connessione a MySQL gestito da ServBay): Se MySQL ServBay è sulla porta 3306:

   • host: host.docker.internal
   • porta: 3306
   • user: your_db_user
   • password: your_db_password

Q4: Come può un container Docker fidarsi del certificato ServBay User CA quando accede tramite dominio (usando extra_hosts) a un sito HTTPS gestito da ServBay?

Se hai seguito la procedura della Q2, aggiungendo ad esempio secure.servbay.demo tramite extra_hosts o --add-host, e il sito HTTPS usa un certificato rilasciato da ServBay User CA, il container Docker, per impostazione predefinita, non si fiderà di questa CA. Questo può causare il fallimento delle connessioni SSL/TLS.

Percorsi file CA sulla macchina host (macOS):

• Certificato radice ServBay User CA: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
• File PEM contenente CA User/Public + Mozilla root:
  • Mac ARM: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
  • Mac Intel: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

Strategie per affidare la CA al container:

1. Metodo 1: Sistema di fiducia a livello di immagine (via Dockerfile) – Ideale quando puoi modificare l'immagine.
2. Metodo 2: Fiducia applicativa a runtime (via volume + variabile d'ambiente) – Più flessibile, non richiede rebuild.
3. Metodo 3: Fiducia di sistema a runtime (via volume + comando custom d'avvio) – Utile quando vuoi l'affidamento di sistema senza rebuild.

Metodo 1: Fiducia di sistema già in fase di build (via Dockerfile)

Integra il certificato CA direttamente nella trust store dell'immagine durante la build.

• Prepara il file CA: Copia /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt nella directory di build.
• Esempio Dockerfile (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/*

• Esempio Dockerfile (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

• Costruzione con Docker Compose:

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

Metodo 2: Fiducia applicativa a runtime (volume + variabile d'ambiente)

Monta il file CA come volume e specifica via variabile d’ambiente l’uso per una certa applicazione (es. Node.js, Python, ecc.).

• Esempio di docker-compose.yml:

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

  Consulta la documentazione della tua applicazione per conoscere la variabile corretta.

Metodo 3: Fiducia di sistema a runtime (volume + comando custom)

Monta il certificato e al lancio aggiorna la trust store con uno script, senza build custom.

• Esempio di docker-compose.yml (Debian/Ubuntu):

  version: '3.8'
  services:
    myapp:
      image: ubuntu:latest # O altra immagine con supporto update-ca-certificates
      volumes:
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      command: >
        sh -c "
          echo 'Aggiornamento 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 'CA aggiornata.'
          else
            echo 'Comando update-ca-certificates non trovato, salto update.'
          fi &&
          echo 'Avvio applicazione...' &&
          exec your_original_application_command_here # Sostituisci con il comando originale della tua app
        "
      extra_hosts: ["secure.servbay.demo:host-gateway"]
      # Potresti dover avviare come root o gestire i permessi nell'entrypoint

  Nota:
  • Complessità: Attenzione se l’immagine ha una logica di avvio complessa; potresti dover adattare entrypoint.
  • Permessi: Serve normalmente l’utente root per aggiornare la CA.
  • Dipendenze: Il pacchetto ca-certificates e il relativo comando devono essere disponibili nell’imgine.
  • Tempo di avvio: Ogni avvio comporta l’update della CA, che può rallentare il boot del container.
  • Alpine Linux: Il comando equivalente è apk add --no-cache ca-certificates && update-ca-certificates.

Quale metodo scegliere?

• Se puoi modificare l'immagine e vuoi la fiducia di sistema totale, metodo 1 è il più efficace.
• Se non vuoi rebuildare e vuoi fiducia solo in una specifica applicazione, metodo 2 va benissimo.
• Se vuoi fiducia globale di sistema ma eviti la build personalizzata, metodo 3 è un buon compromesso.

Per certificati di CA pubbliche (es. Let's Encrypt): Se ServBay usa certificati da CA pubbliche (ottenuti tramite ACME, es. Let's Encrypt), la maggior parte delle immagini di base Docker li considera affidabili di default e non richiedono operazioni particolari.

Q5: Come posso assegnare un dominio e configurare il reverse proxy con ServBay per un'app in esecuzione su Docker?

Potresti avere un'applicazione, ad esempio Node.js che ascolta sulla porta 3000 nel container, e desiderare di accedervi via browser con un dominio amichevole (es. myapp.servbay.demo) sfruttando anche la gestione automatica dei certificati SSL di ServBay.

Procedura:

1. Esegui il container Docker e mappa la porta verso 127.0.0.1 sull'host: Assicurati che la porta del container sia mappata su una porta della macchina host legata a 127.0.0.1 (così sarà accessibile solo localmente).

   # Esempio: esponi 3000 del container come 127.0.0.1:3001 sull'host
   docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image

   In questo modo, la tua app sarà disponibile all'host su http://127.0.0.1:3001.

2. Configura su ServBay un nuovo sito con reverse proxy:

   • Accedi all'interfaccia di amministrazione di ServBay.
   • Clicca su "Aggiungi sito".
   • Dominio: inserisci il dominio desiderato, ad esempio myapp.servbay.demo.
   • Tipo sito: scegli "Reverse Proxy" dal menu a tendina.
   • Indirizzo IP: inserisci 127.0.0.1.
   • Porta: inserisci la porta del mapping Docker, es. 3001.
   • Clicca su “Salva” o “Aggiungi”.

3. (Opzionale) Configura SSL: Dopo aver aggiunto il sito, puoi abilitarne il supporto SSL direttamente dalla relativa sezione. ServBay può gestire certificati Let's Encrypt in modalità automatica tramite ACME, oppure puoi utilizzare CA locali gestite da ServBay. Il reverse proxy terminerà la connessione SSL su ServBay e inoltrerà le richieste in HTTP semplice al container Docker su 127.0.0.1:3001.

4. Testa l’accesso: Dopo la configurazione, puoi accedere a http://myapp.servbay.demo o https://myapp.servbay.demo (se abilitato SSL) e ServBay si occuperà di inoltrare le richieste verso l'applicazione containerizzata.

Flusso operativo: Browser dell’utente -> https://myapp.servbay.demo -> ServBay (gestisce SSL e routing) -> http://127.0.0.1:3001 (porta host) -> applicazione nel container Docker.

Conclusioni

ServBay semplifica notevolmente lo sviluppo web locale su macOS. In combinazione con Docker:

• Per accedere ai siti ServBay dai container: aggiungi il dominio al container tramite extra_hosts o --add-host e punta a host-gateway per il corretto inoltro dell’header Host ed evitare problemi SNI.
• Per accedere ai database o servizi non HTTP gestiti da ServBay dal container: usa semplicemente host.docker.internal come host per una connessione efficace.
• Per fare in modo che il container si fidi dei certificati SSL firmati da ServBay User CA: includi la CA nel trust store del container, scegliendo la strategia più adatta tra build, volume o comando all’avvio.
• Per pubblicare un’app del container dietro proxy con dominio servito da ServBay: configura un sito di tipo "Reverse Proxy" su ServBay verso la porta mappata locale.

Assicurati sempre che tutti i servizi ServBay coinvolti (web server, database, ecc.) e i relativi container Docker siano attivi e correttamente configurati.