Guida alla Configurazione di un Servizio Proxy Inverso Ngrok in ServBay

Ngrok è un potente strumento di tunneling sicuro basato su tecnologia di proxy inverso, che permette di superare firewall e NAT, mappando i servizi in esecuzione in locale su un dominio pubblico. Questa guida illustra dettagliatamente come integrare e configurare Ngrok nell’ambiente di sviluppo locale ServBay, consentendo l’accesso via Internet a servizi web locali, API o altri servizi — ideale per demo remote, collaborazione di team o test di callback di servizi di terze parti.

Principi Tecnici

Il principio alla base di Ngrok è l’instaurazione di una connessione tunnel crittografata tra il tuo computer locale e i server di Ngrok. Quando utenti esterni accedono tramite il dominio pubblico assegnato da Ngrok, la richiesta raggiunge prima i server Ngrok e poi, attraverso il tunnel sicuro, viene inoltrata al servizio corrispondente attivo sul tuo ServBay locale. Questo consente di fornire servizi esternamente anche se il tuo computer non dispone di un IP pubblico o si trova protetto da firewall. Nel caso di ServBay, significa che puoi condividere istantaneamente con il mondo siti web locali, API backend o qualsiasi servizio basato su HTTP/HTTPS per test e presentazioni.

Preparazione dell’Ambiente

Prima di configurare Ngrok, assicurati di aver completato i seguenti passaggi:

1. ServBay installato e attivo: Assicurati che l’applicazione ServBay sia installata correttamente e che il servizio web che desideri esporre tramite Ngrok (ad esempio un sito web) sia configurato in ServBay e regolarmente funzionante. Puoi visualizzare e gestire le configurazioni dei siti locali nel pannello “Siti web” di ServBay.
2. Installazione del client Ngrok: Segui questi passaggi per installare l’interfaccia CLI di Ngrok:
   1. Vai alla pagina download ufficiale di Ngrok per scaricare il pacchetto adatto al tuo sistema operativo.
   2. Dopo il download, estrai i file. Sposta o copia l’eseguibile ngrok in una cartella presente nel PATH di sistema (ad esempio /usr/local/bin su macOS), così da poter lanciare il comando ngrok da qualsiasi finestra terminale.

      # Esempio per architettura ARM64 su macOS
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. Verifica la corretta installazione controllando che il comando ngrok version sia eseguibile e mostri la versione:

      ngrok version
      # Esempio output: ngrok version 3.5.0

3. Account Ngrok (opzionale ma consigliato): Possedere un account Ngrok (gratuito o a pagamento) rende più semplice gestire i tunnel e usufruire di funzionalità avanzate come i domini fissi. Registrati su Ngrok, reperisci il tuo token di autenticazione (ngrok config add-authtoken <YOUR_AUTH_TOKEN>) così da rimuovere i limiti di durata delle connessioni e accedere a più opzioni.
4. Sito locale configurato: In ServBay dev’essere già configurato almeno un sito web che desideri esporre su Internet tramite Ngrok, ad esempio con dominio locale servbay.local o yourproject.servbay.demo.

Configurazione Pratica del Tunnel

Spiegazione dei Parametri Principali

La struttura base del comando per mappare un servizio è la seguente:

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

Componente	Descrizione Funzione
http	Avvia un tunnel basato su protocollo HTTP. Ngrok gestisce così le richieste HTTP/HTTPS in arrivo.
--domain <NGROK_DOMAIN>	Specifica il dominio fisso assegnato a te da Ngrok (da sostituire col dominio effettivo configurato nella dashboard Ngrok). Nei piani gratuiti, spesso non è necessario: Ngrok attribuisce automaticamente un sottodominio casuale.
<LOCAL_ENDPOINT>	L’indirizzo del servizio locale su ServBay. Di solito è il dominio locale della tua virtual host (es. https://servbay.local). Può essere anche http://localhost:porta.
--request-header-add='host: <VIRTUAL_HOST>'	[IMPORTANTE] Sovrascrive l’header Host della richiesta. ServBay usa di norma l’header Host per gestire siti diversi (virtual host): questo parametro fa sì che le richieste dall’esterno arrivino con l’header impostato sul dominio del sito virtuale corrispondente in ServBay (es. servbay.local), garantendo l’instradamento corretto al sito desiderato.

Esempio di Configurazione

Supponiamo di aver configurato in ServBay un sito locale dal dominio servbay.local e di volerlo esporre su Internet via Ngrok. Se usi il piano gratuito di Ngrok, puoi mappare direttamente l’indirizzo locale:

# Mappa il sito locale ServBay servbay.local su un dominio casuale assegnato da Ngrok
ngrok http https://servbay.local --request-header-add='host: servbay.local'

Se hai configurato nella tua Dashboard Ngrok un dominio fisso, ad esempio your-servbay-demo.ngrok-free.app o un dominio personalizzato per account a pagamento, usa il parametro --domain:

# Mappa il sito locale ServBay servbay.local su un dominio specifico Ngrok
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

Dopo aver lanciato con successo questi comandi, il client Ngrok mostrerà nel terminale lo stato del tunnel, l’indirizzo pubblico assegnato (come https://xxxx.ngrok-free.app o il dominio che hai impostato) e l’indirizzo locale della dashboard di monitoraggio traffico in tempo reale (di solito http://127.0.0.1:4040).

Verifica del Servizio

Al termine della configurazione e con il tunnel Ngrok avviato correttamente, segui questi passaggi per verificare l’accessibilità del servizio dal web:

1. Recupera l’indirizzo pubblico: Individua la riga Forwarding nella finestra terminale di Ngrok e annota l’URL pubblico che inizia con https://.
2. Accedi dal browser: Da qualsiasi dispositivo collegato a Internet, visita tramite browser l’URL pubblico fornito da Ngrok (es. https://cunning-lacewing-fresh.ngrok-free.app oppure il tuo dominio fisso).
3. Verifica l’esito:
   • Assicurati che il browser carichi correttamente i contenuti del sito ospitato localmente su ServBay.
   • Controlla che nella barra degli indirizzi del browser compaia il simbolo della connessione HTTPS sicura. Ngrok fornisce di default certificati SSL validi per i tunnel.
   • Puoi consultare nel terminale Ngrok o tramite la sua interfaccia web locale (di solito http://127.0.0.1:4040) i log e le statistiche delle richieste per confermare che queste sono correttamente ricevute e gestite da ServBay.

Illustrazione: accesso con successo al tunnel Ngrok tramite browser web

Suggerimenti Avanzati e Avvertenze

1. Gestione dei domini:
   • Con il piano gratuito, Ngrok assegna normalmente un sottodominio casuale .ngrok-free.app e pone un limite alla durata delle connessioni.
   • Registrando un account Ngrok e accedendo alla Dashboard Ngrok, puoi configurare domini fissi ed evitare che l’indirizzo pubblico cambi a ogni avvio del tunnel.
   • I piani a pagamento Ngrok permettono il collegamento di domini personalizzati, maggiore banda, più connessioni simultanee e molte funzionalità aggiuntive.
2. Mappatura di più servizi: Se devi esporre su Internet più servizi o porte diversi in esecuzione su ServBay, puoi lanciare più processi Ngrok oppure definire e gestire più tunnel tramite il file di configurazione Ngrok (di solito ~/.config/ngrok/ngrok.yml). Ad esempio, per mappare sia un sito su ServBay, sia una app Node.js su una porta diversa:

   # Mappa servbay.local (via HTTPS 443, routing tramite Host header)
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # In un altro terminale o tramite file di configurazione, mappa la app Node.js in ascolto sulla porta 3000
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   Nota: Per le virtual host su ServBay è consigliabile mappare https://[dominio locale] con --request-header-add piuttosto che direttamente le porte 80/443 di ServBay, dato che questi ingressi gestiscono tutte le richieste di virtual host.
3. Comandi di diagnostica:
   • ngrok config check: Verifica la correttezza sintattica del file di configurazione Ngrok (tipicamente ~/.config/ngrok/ngrok.yml).
   • ngrok logs: Visualizza in tempo reale i log dettagliati del client Ngrok, utili per individuare problemi di connessione o di routing delle richieste.
4. Sicurezza: Esporre servizi locali a Internet comporta rischi di sicurezza. Assicurati che i servizi pubblicati siano sicuri e attiva il tunnel solo quando necessario. I piani a pagamento Ngrok offrono funzionalità di whitelist IP, restrizioni di accesso e altre opzioni di sicurezza avanzata.

Risoluzione dei Problemi

Problema	Soluzione
Timeout di connessione o pagina non caricata	Conferma che il sito in ServBay sia attivo e accessibile dal dominio locale (es. nel browser locale su https://servbay.local). Verifica che il web server usato da ServBay (Caddy, Nginx...) sia operativo. Ricontrolla anche che il firewall locale consenta le connessioni del client Ngrok.
Errore certificato HTTPS (avviso browser)	Ngrok fornisce di default certificati HTTPS validi per i suoi domini. Se riscontri un errore di certificato accedendo al dominio pubblico Ngrok, il problema di solito è legato alla configurazione di Ngrok o a restrizioni di rete, non a ServBay. Assicurati di usare sempre l’indirizzo https:// fornito da Ngrok. Se invece l’errore si presenta solo sugli indirizzi locali ServBay, verifica la configurazione SSL di ServBay.
Disconnessioni occasionali o lentezza	Controlla la stabilità della tua connessione Internet. Fluttuazioni di rete possono interrompere il tunnel. Preferisci, se possibile, una connessione cablata. Per esigenze di alta affidabilità valuta i servizi a pagamento di Ngrok che offrono maggiore stabilità e banda.
Accesso alla pagina di default ServBay invece che al sito desiderato	Verifica che in ngrok http l’indirizzo locale <LOCAL_ENDPOINT> sia corretto e che il parametro --request-header-add='host: <VIRTUAL_HOST>' abbia esattamente il dominio locale che hai configurato su ServBay. Questo è fondamentale per l’instradamento corretto delle richieste al sito giusto.

Domande Frequenti (FAQ)

• D: Posso mappare anche i servizi database di ServBay?

  R: Ngrok è pensato principalmente per tunnel HTTP/HTTPS. Anche se supporta tunnel TCP (utili per database), questi vanno oltre la presente guida focalizzata sui tunnel HTTP e non si raccomanda di esporre direttamente i database su Internet per motivi di sicurezza. Per accesso remoto ai database valuta SSH tunnel o soluzioni più sicure.

• D: A ogni avvio di Ngrok l’indirizzo pubblico cambia?

  R: Con il piano gratuito di Ngrok, il sottodominio .ngrok-free.app è in genere casuale. Per ottenere un dominio fisso devi registrare un account Ngrok e configurarlo in dashboard o optare per un piano a pagamento.

• D: Ngrok rallenta le performance di ServBay?

  R: Ngrok introduce una certa latenza poiché le richieste transitano dai server Ngrok, ma per sviluppo, test e demo questo è generalmente accettabile. Le prestazioni del tuo servizio locale restano legate all’efficienza della tua macchina e delle tue applicazioni.

Conclusione

Integrando Ngrok, gli utenti ServBay possono condividere in modo semplice, sicuro ed efficiente i propri sviluppi web locali online. La soluzione non richiede configurazioni di rete avanzate ed è ideale per collaborazione remota, demo con clienti, test su mobile o integrazioni di servizi esterni. Ngrok fornisce monitoraggio del traffico in tempo reale e opzioni di sicurezza avanzate (alcune disponibili solo nei piani a pagamento). Per scenari professionali o nei casi in cui sia fondamentale disporre di domini fissi, è consigliato considerare i servizi a pagamento Ngrok per un’esperienza più stabile e completa.