FAQ sulla Collaborazione tra ServBay e Docker

Durante lo sviluppo web locale con ServBay, potresti voler utilizzare anche Docker per sfruttare l’ambiente containerizzato. Questa sezione FAQ risponde alle domande comunemente poste durante la collaborazione tra ServBay e Docker su macOS e Windows, comprese le modalità di accesso ai servizi ServBay dai container e la configurazione del proxy inverso di ServBay per le applicazioni Docker.

Q1: Perché ServBay modifica il file `hosts` di sistema? Posso impedirlo?

ServBay aggiunge voci al file hosts del sistema (ad esempio mysite.servbay.demo 127.0.0.1) per consentire l’accesso ai siti locali tramite nomi di dominio personalizzati (come mysite.servbay.demo). Questi siti vengono eseguiti sull’indirizzo locale 127.0.0.1.

Tuttavia, a causa del funzionamento di Docker, il file hosts del sistema (macOS o Windows) viene letto all’interno del container, dunque mysite.servbay.demo risulta risolto su 127.0.0.1, portando Docker a tentare di collegarsi al servizio errato (cioè se stesso, non la macchina host).

Meccanismo principale:

Quando crei un nuovo sito in ServBay specificando un dominio (ad esempio, example.servbay.demo), ServBay lo punta automaticamente a 127.0.0.1.
Questo è lo standard per utilizzare nomi di dominio personalizzati nello sviluppo locale. Senza la modifica al file hosts, il sito sarebbe accessibile solo tramite http://127.0.0.1:PORT e non tramite il dominio.

È possibile impedirlo?

In teoria potresti rimuovere manualmente le voci aggiunte da ServBay, ma così perderesti la comodità di accedere al sito tramite dominio. Ciò va contro lo scopo di ServBay, che è semplificare la creazione e l’accesso ai siti locali. Se non desideri che ServBay gestisca i record hosts di specifici domini, ti consigliamo di non creare siti per quei domini in ServBay.

Per la stragrande maggioranza degli sviluppatori, la gestione automatica del file hosts da parte di ServBay è la soluzione ideale e semplifica notevolmente il workflow.

Q2: Come può un container Docker accedere correttamente ai siti gestiti da ServBay sulla macchina host usando il dominio (ad esempio `mysite.servbay.demo`)?

Questa è una necessità frequente, ma va gestita correttamente. Quando ServBay esegue un sito sulla macchina host (ad esempio, mysite.servbay.demo che risolve su 127.0.0.1), nel container Docker 127.0.0.1 indica il container stesso, non la macchina host.

Soluzione errata: usare direttamente host.docker.internal come hostname nella URL per accedere ai siti ServBay

Anche se Docker Desktop per Mac (e Windows) fornisce il nome DNS speciale host.docker.internal che risolve nell’indirizzo IP della macchina host, è fortemente sconsigliato usarlo direttamente nella URL per accedere ai siti gestiti da ServBay (ad esempio, aspettarsi che http://host.docker.internal/ risolva in mysite.servbay.demo).

Questo perché la richiesta HTTP inviata al web server ServBay (Caddy, Nginx ecc.) conterrà host.docker.internal come campo Host, impedendo al server di riconoscere il sito desiderato o causando errori SNI (Server Name Indication) in HTTPS, poiché il certificato SSL è stato emesso per mysite.servbay.demo, non per host.docker.internal.

Soluzione corretta: aggiungere il dominio a /etc/hosts del container con extra_hosts

Per far sì che le applicazioni all’interno del container possano accedere al dominio (come mysite.servbay.demo) e inviare correttamente l’header Host, devi aggiungere una voce a /etc/hosts del container, facendo puntare il dominio all’indirizzo host tramite extra_hosts in docker-compose.yml oppure tramite --add-host con docker run, preferibilmente usando host-gateway.

Con docker run:
bash
```
docker run --add-host=mysite.servbay.demo:host-gateway ... your_image
```
1
(host-gateway è un valore speciale che Docker sostituisce con l’indirizzo IP interno dell’host; per Docker 20.10+ è una soluzione robusta simile a host.docker.internal.)

Con docker-compose.yml:

yaml

version: '3.8' # o superiore
services:
  myapp:
    image: your_image
    extra_hosts:
      - "mysite.servbay.demo:host-gateway" # oppure "mysite.servbay.demo:host.docker.internal"
    # ... altre configurazioni

Una volta configurato:

Le applicazioni nel container che chiamano http://mysite.servbay.demo (o https://mysite.servbay.demo) lo risolvono correttamente all’IP della macchina host.
La richiesta viene inviata al server web ServBay sulla host machine.
L’header HTTP Host sarà mysite.servbay.demo, consentendo a ServBay il corretto routing e l’invio del giusto certificato SSL (se HTTPS è abilitato).

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

Diversamente dai servizi web basati su dominio, per collegamenti a database o altri servizi TCP che non richiedono SNI, è consigliato e funzionale usare host.docker.internal come hostname del server.

Steps:

Assicurati che il database ServBay (o altro servizio) sia in esecuzione e configurato per accettare connessioni dalla macchina host (solitamente la configurazione predefinita è sufficiente).
Nel container Docker, quando configuri la connessione al database:
- Hostname/server: Usa host.docker.internal.
- Porta: Inserisci quella configurata sul database ServBay (ad esempio MySQL di solito è 3306, PostgreSQL è 5432).
- Username/password: Usa le credenziali impostate nel database ServBay.

Esempio (collegamento a MySQL gestito da ServBay): Se MySQL su ServBay è sulla porta 3306, nel container puoi configurare:

host: host.docker.internal
porta: 3306
utente: your_db_user
password: your_db_password

Q4: Come può un container Docker accedere tramite nome di dominio (usando `extra_hosts`) a un sito HTTPS su ServBay (protetto da ServBay User CA) e fidarsi di questa CA?

Supponiamo che, come descritto nella Q2, hai configurato secure.servbay.demo associato a host-gateway. Se il sito usa un certificato SSL generato dalla ServBay User CA, il container Docker potrebbe non fidarsi di questa CA e fallire la handshake SSL.

Percorsi file CA di ServBay:

Certificato root ServBay User CA:
- macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
File PEM con ServBay User CA, Public CA e root 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

Soluzioni possibili:

Tre metodi per far sì che il container Docker si fidi della ServBay User CA:

Metodo 1: Fiducia di sistema durante la build (tramite Dockerfile) – ideale se puoi personalizzare l’immagine e vuoi la CA fidata ovunque nel sistema.
Metodo 2: Fiducia applicativa a runtime (tramite mount del volume e variabili ambiente) – utile se serve solo per una specifica applicazione o non puoi modificare l’immagine.
Metodo 3: Fiducia di sistema a runtime (mount del volume e comando avvio personalizzato) – utile per fiducia a livello sistema senza rebuild dell’immagine.

Metodo 1: Fiducia di sistema durante la build (tramite Dockerfile)

Questa modalità integra il certificato CA nel trust store di sistema durante la build.

Prepara il certificato CA: Copia il root certificate ServBay User CA nella directory build del Dockerfile:
- macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
- Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt

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

Esempio di 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

Docker Compose build:

yaml

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

Metodo 2: Fiducia applicativa a runtime (mount volume e variabili ambiente)

Monti il certificato CA nel container e configurial’applicazione a usarlo tramite variabile ambiente.

Esempio docker-compose.yml:

yaml

version: '3.8'
services:
  myapp:
    image: some-base-image
    volumes:
      # Esempio macOS
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      # Esempio Windows (adatta il path)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
    environment:
      # Example per Node.js:
      - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
      # Example per Python (requests):
      # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
      # Example per variabile generica SSL_CERT_FILE:
      # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
    extra_hosts: ["secure.servbay.demo:host-gateway"]

Consulta la documentazione della tua applicazione per la variabile corretta.

Metodo 3: Fiducia di sistema a runtime (mount volume + comando di avvio personalizzato)

Monti il certificato e aggiorni il trust store di sistema all’avvio del container, senza rebuild.

Esempio docker-compose.yml (su images Debian/Ubuntu):

yaml

version: '3.8'
services:
  myapp:
    image: ubuntu:latest # o altra base con update-ca-certificates
    volumes:
      # Monta la CA nel trust store previsto dal sistema
      # macOS path
      - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      # Windows path (adatta il path)
      # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
    # Override del comando: update certificate e avvia applicazione originale
    command: >
      sh -c "
        echo 'Aggiornamento dei certificati 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 'Certificati CA aggiornati.'
        else
          echo 'Comando update-ca-certificates non trovato, salto aggiornamento CA.'
        fi &&
        echo 'Avvio applicazione...' &&
        exec your_original_application_command_here # Sostituisci con il CMD originale o il comando di avvio
      "
    extra_hosts: ["secure.servbay.demo:host-gateway"]
    # Se serve permessi root per update-ca-certificates, gestisci user/entrypoint di conseguenza
    # user: root # modalità temporanea o con script entrypoint ad hoc

Nota:

Complessità: modificare command o entrypoint può essere complicato su immagini ufficiali con setup di avvio complessi; assicurati di avviare correttamente l’app.
Permessi: spesso serve essere root per aggiornare le CA.
Pacchetti: il container deve avere installato ca-certificates e update-ca-certificates; lo script li installa se mancano (sistemi apt).
Avvio: ogni restart del container esegue questi step e può aumentare il tempo di startup.
Alpine Linux: su Alpine usa apk add --no-cache ca-certificates && update-ca-certificates.

Quale metodo scegliere?

Se puoi personalizzare l’immagine e vuoi la CA fidata ovunque, il Met. 1 è il migliore.
Se serve solo all'applicazione o non puoi modificare l’immagine, scegli il Met. 2.
Se non puoi rebuildare, vuoi fiducia di sistema runtime, usa il Met. 3.

Per certificati pubblici (es. Let's Encrypt): Se il sito ServBay usa certificati di CA pubbliche ottenuti via ACME (es. Let's Encrypt), la maggior parte delle immagini base Docker già li riconosce e non saranno necessarie azioni aggiuntive.

Q5: Come assegnare un dominio e impostare ServBay come proxy inverso per un’applicazione che gira dentro Docker?

Supponiamo di avere un’applicazione (es. Node.js su porta 3000) in un container e voler collegarci tramite un dominio amichevole (es. myapp.servbay.demo) dalla macchina host, sfruttando la gestione SSL di ServBay.

Steps:

Avvia il container e mappa la porta sull’host in ascolto su 127.0.0.1: Assicurati che il container Docker mappi la porta dell’app sull’host, bindando a 127.0.0.1 (così la porta è accessibile solo localmente, non da remoto).
bash
```
# Esempio: container ascolta su 3000, mappato su host `127.0.0.1:3001`
docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image
```
1
2
Così l’app interna al container diventa raggiungibile tramite http://127.0.0.1:3001 sulla macchina host.
Aggiungi un nuovo sito in ServBay e configura il proxy inverso:
- Accedi alla dashboard ServBay.
- Seleziona “Aggiungi sito”.
- Dominio: Inserisci il dominio voluto, esempio myapp.servbay.demo.
- Tipo di sito: Seleziona “Proxy inverso” dal menu.
- Indirizzo IP: Inserisci 127.0.0.1.
- Porta: Inserisci la porta mappata dal container, esempio 3001.
- Salva la configurazione.
(Opzionale) Configura SSL: Dopo la creazione del sito, puoi attivare SSL tramite dashboard ServBay. ServBay può ottenere automaticamente certificati da CA pubbliche tramite ACME (es. Let’s Encrypt), oppure usare ServBay User CA / ServBay Public CA. Il proxy SSL viene gestito da ServBay; la comunicazione con il container Docker resta HTTP (es. http://127.0.0.1:3001).
Test di accesso: Dopo la configurazione, puoi accedere dal browser a http://myapp.servbay.demo o https://myapp.servbay.demo (se SSL abilitato). ServBay proxyerà le richieste verso l’app in container.

Workflow: Browser utente -> https://myapp.servbay.demo -> ServBay (SSL termination, regole proxy) -> http://127.0.0.1:3001 (porta locale) -> applicazione nel container Docker.

Riepilogo

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

Per accedere ai siti ServBay dai container Docker, usa extra_hosts o --add-host per mappare il dominio su host-gateway, assicurando una corretta gestione dell’header Host ed evitando problemi SNI.
Per accedere ai database o servizi non HTTP di ServBay dai container Docker, usa host.docker.internal come hostname.
Per fiducia dei certificati SSL ServBay User CA nei container Docker, copia il certificato root della CA nell’immagine o container e aggiorna il trust store.
Per assegnare un dominio e usare ServBay come proxy inverso verso app Docker, crea un sito Proxy Inverso in ServBay puntando la porta mappata su 127.0.0.1.

Assicurati sempre che i relativi componenti ServBay (web server, database, ecc.) e il tuo container Docker siano correttamente configurati e avviati.

FAQ sulla Collaborazione tra ServBay e Docker ​

Q1: Perché ServBay modifica il file hosts di sistema? Posso impedirlo? ​

Q2: Come può un container Docker accedere correttamente ai siti gestiti da ServBay sulla macchina host usando il dominio (ad esempio mysite.servbay.demo)? ​

Q3: Come può un container Docker collegarsi a database gestiti da ServBay (come MySQL, PostgreSQL) o altri servizi non HTTP? ​

Q4: Come può un container Docker accedere tramite nome di dominio (usando extra_hosts) a un sito HTTPS su ServBay (protetto da ServBay User CA) e fidarsi di questa CA? ​

Metodo 1: Fiducia di sistema durante la build (tramite Dockerfile) ​

Metodo 2: Fiducia applicativa a runtime (mount volume e variabili ambiente) ​

Metodo 3: Fiducia di sistema a runtime (mount volume + comando di avvio personalizzato) ​

Q5: Come assegnare un dominio e impostare ServBay come proxy inverso per un’applicazione che gira dentro Docker? ​

Riepilogo ​

FAQ sulla Collaborazione tra ServBay e Docker

Q1: Perché ServBay modifica il file `hosts` di sistema? Posso impedirlo?

Q2: Come può un container Docker accedere correttamente ai siti gestiti da ServBay sulla macchina host usando il dominio (ad esempio `mysite.servbay.demo`)?

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

Q4: Come può un container Docker accedere tramite nome di dominio (usando `extra_hosts`) a un sito HTTPS su ServBay (protetto da ServBay User CA) e fidarsi di questa CA?

Metodo 1: Fiducia di sistema durante la build (tramite Dockerfile)

Metodo 2: Fiducia applicativa a runtime (mount volume e variabili ambiente)

Metodo 3: Fiducia di sistema a runtime (mount volume + comando di avvio personalizzato)

Q5: Come assegnare un dominio e impostare ServBay come proxy inverso per un’applicazione che gira dentro Docker?

Riepilogo