Accesso Pubblico a Siti e Servizi Locali in ServBay con Pinggy

Pinggy è uno strumento di tunneling locale (reverse proxy) estremamente semplice ed efficace, che consente di esporre in modo sicuro su Internet i servizi web in esecuzione localmente (ad esempio nell'ambiente ServBay). Questa guida spiega passo a passo come utilizzare Pinggy su ServBay per permettere agli sviluppatori di rendere disponibili i propri servizi Web locali su Internet, facilitando presentazioni remote, collaborazione di squadra o la ricezione di richieste webhook senza complicazioni.

Principio Tecnico

Il nucleo di Pinggy è la creazione di un tunnel SSH sicuro. Instaurando una connessione SSH tra una porta del server locale (che potrebbe essere dietro NAT o firewall) e il server pubblico di Pinggy, il traffico diretto all'URL assegnato da Pinggy viene inoltrato in modo protetto verso il servizio locale.

Nello scenario ServBay, questo significa che puoi mappare un sito locale (ad esempio: https://myproject.servbay.demo) in esecuzione su ServBay su un URL pubblico grazie a Pinggy, senza la necessità di complesse configurazioni di port forwarding o firewall.

Preparazione dell'Ambiente

L'uso di Pinggy non richiede l'installazione di alcun software client aggiuntivo sul tuo computer. Sono necessari solo:

1. ServBay installato e funzionante: Assicurati che l'ambiente ServBay sia correttamente installato e il sito o servizio locale che vuoi esporre sia in esecuzione.
2. Sito attivo su ServBay: Devi aver configurato e avviato uno o più siti locali su ServBay. Normalmente, questi ascoltano sulle porte locali 80 (HTTP) o 443 (HTTPS) tramite i server integrati Caddy o Nginx.
3. Terminale con supporto SSH: Il Terminale di macOS o altri emulatori di terminale che utilizzano SSH sono perfetti.
4. Conoscenza base di SSH: È utile sapere come eseguire comandi SSH nel terminale.

Configurazione del Tunnel

Comando Principale

Stabilire un tunnel con Pinggy è davvero facile: basta una riga di comando SSH nel terminale. Ecco un esempio che mostra come esporre un sito configurato su ServBay e accessibile localmente sulla porta 443 (servbay.new) verso l'esterno:

ssh -p 443 -R0:localhost:443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -t [email protected] x:localServerTls:servbay.new "u:host:servbay.new"

Nota importante: Sostituisci XXXXXXXXXXX con il nome utente che ottieni dal sito Pinggy (di solito una stringa alfanumerica). servbay.new va sostituito con il dominio del sito locale che vuoi esporre tramite Pinggy (ad esempio: myproject.servbay.demo).

Ecco una spiegazione dettagliata dei parametri principali del comando:

Componente del parametro	Descrizione
-p 443	Specifica che la connessione SSH deve avvenire sulla porta 443 del server Pinggy. Usare la porta HTTPS migliora la probabilità di superare i firewall.
-R0:localhost:443	Cuore del port forwarding remoto. 0 fa sì che il server Pinggy assegni automaticamente una porta pubblica casuale. localhost:443 inoltra tutto il traffico ricevuto verso la porta 443 locale.
-o StrictHostKeyChecking=no	Disabilita il controllo della chiave host SSH. Comodo per la prima configurazione o test, ma in ambienti di produzione è consigliato abilitarlo e verificare le chiavi.
-o ServerAliveInterval=30	Invia ogni 30 secondi un segnale keep-alive per evitare che la connessione SSH scada per inattività.
-t [email protected]	Nome utente Pinggy e indirizzo del server. XXXXXXXXXXX è il tuo nome utente Pinggy.
x:localServerTls:servbay.new	Parametro custom di Pinggy: indica che il servizio locale supporta TLS (HTTPS) e il relativo dominio. Personalizzalo con il dominio del tuo sito locale ServBay.
"u:host:servbay.new"	Altro parametro personalizzato Pinggy per modificare l'header Host delle richieste HTTP inoltrate; è fondamentale se usi più siti (virtual host).

Al termine dell'esecuzione, Pinggy mostra in terminale l'URL pubblico per accedere al servizio locale, ad esempio:

http://rnirh-172-188-50-148.a.free.pinggy.link
https://rnirh-172-188-50-148.a.free.pinggy.link

Verifica dei Servizi

Una volta creato il tunnel, verifica subito la raggiungibilità pubblica con uno di questi metodi:

1. Verifica via curl (consigliato): Usa il comando curl con il parametro -I (solo header) per testare l'URL pubblico assegnato da Pinggy:

   curl -I https://rnirh-172-188-50-148.a.free.pinggy.link

   Se tutto funziona, otterrai un output simile a questo, con gli header restituiti dal tuo server web locale (Nginx, Caddy, ecc):

   HTTP/1.1 200 OK
   Connection: close
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Headers: Content-Type, Authorization
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
   Access-Control-Allow-Origin: *
   Cache-Control: max-age=0, must-revalidate, no-cache, no-store, private
   Connection: keep-alive
   Content-Type: text/html; charset=UTF-8
   Date: Tue, 18 Feb 2025 11:51:48 GMT # la data può variare
   Expires: Sun, 02 Jan 1990 00:00:00 GMT
   Pragma: no-cache
   Server: nginx # oppure caddy ecc., a seconda della configurazione ServBay
   Vary: Accept-Encoding
   X-Frame-Options: SAMEORIGIN
   X-Powered-By: PHP/8.4.3 # o altre info dipendenti dallo stack tecnologico

   La presenza di HTTP/1.1 200 OK e dell'header Server corretto indica che la connessione va e che ServBay sta rispondendo.

2. Accesso da browser: Apri l'URL HTTPS fornito da Pinggy (https://rnirh-172-188-50-148.a.free.pinggy.link) direttamente dal browser, anche da dispositivi fuori dalla rete locale: dovresti vedere esattamente il sito come in locale.

3. Cosa aspettarsi:

   • Gli utenti esterni raggiungono il tuo sito o servizio locale ServBay tramite l'URL Pinggy.
   • Se il servizio locale usa HTTPS (ServBay crea di default certificati autofirmati), Pinggy assicura l'accesso HTTPS pubblico fornendo certificati CA pubblici gratuiti, senza altra configurazione.
   • Tempi di risposta e stabilità possono variare in base alla rete locale, alle condizioni di collegamento verso Pinggy e al carico del servizio Pinggy stesso.

Best Practice e Suggerimenti Avanzati

1. Esporre porte o servizi diversi: Se il servizio locale non è web oppure è in ascolto su una porta diversa da 80/443, modifica semplicemente il parametro -R. Ad esempio, per pubblicare la porta 8000 (ad esempio una app Python o Node.js):

   ssh -p 443 -R0:localhost:8000 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -t [email protected]

   Nota: per servizi non web o web che non gestiscono l'header Host, i parametri x:localServerTls e u:host non sono necessari.

2. Dominio personalizzato (Pinggy Pro): Gli utenti Pinggy Pro possono collegare e utilizzare un proprio dominio personalizzato invece del sottodominio casuale assegnato, ottenendo indirizzi di accesso più professionali. Consulta la documentazione ufficiale Pinggy per la configurazione.

3. Tunnel persistente con autossh: Le connessioni SSH possono interrompersi per instabilità di rete. Se desideri mantenere il tunnel per lunghi periodi, si consiglia di usare lo strumento autossh, che monitora e riavvia automaticamente la connessione SSH se cade. (Su macOS, installalo ad es. con Homebrew: brew install autossh). Esempio d’uso:

   autossh -M 0 -t "ssh -p 443 -R0:localhost:443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -t [email protected] x:localServerTls:servbay.new \"u:host:servbay.new\""

   L'opzione -M 0 fa sì che autossh utilizzi solo l’heartbeat SSH (ServerAliveInterval) invece di porte di monitoraggio extra.

4. Comando senza token: Pinggy mette a disposizione anche comandi one-shot senza la necessità di inserire username/token (ottieni la riga direttamente dal sito web). Questo rende più sicura e facile la condivisione del comando senza rischi di diffusione del token.

Scenari d'Uso Comuni

• Demo remote: Mostra in tempo reale a clienti o colleghi ciò che sviluppi localmente in ServBay, senza dover fare deploy su un ambiente di staging o produzione.
• Debug di webhook: Ricevi e testa richieste webhook da terze parti (gateway di pagamento, GitHub, ecc.) direttamente nell’ambiente locale.
• Test cross-device: Prova la responsività e compatibilità dei tuoi siti locali su diversi dispositivi (cellulari, tablet), anche fuori dalla rete locale.
• Collaborazione di team: Collega i servizi ServBay in locale a distanza per test e revisione con altri membri del team.

Risoluzione dei Problemi

Problema	Soluzione
Timeout o fallimento della connessione SSH	Verifica la connessione di rete, assicurati che a.pinggy.io sia raggiungibile e che il firewall non blocchi le connessioni in uscita sulla porta 443. Ricontrolla anche username Pinggy.
URL Pinggy restituisce errori (es. 502 Bad Gateway)	Assicurati che il sito/servizio locale su ServBay sia attivo e ascolti su localhost:443 (o la porta specificata nel parametro -R). Controlla la corretta configurazione di Caddy/Nginx su ServBay.
Errore 404 o pagina di default di ServBay raggiunta	Per ambienti ServBay con più siti (virtual host), assicurati assolutamente che i parametri x:localServerTls e u:host siano impostati con il dominio giusto (ad es. myproject.servbay.demo) nell'SSH.
Disconnessioni intermittenti	Di solito dovute a rete instabile o timeout SSH. Puoi aumentare ServerAliveInterval o usare autossh per riconnessioni automatiche (vedi “Best Practice e Suggerimenti Avanzati”).
Errore certificato HTTPS	Se usi certificati autofirmati su ServBay, il browser locale può segnalare warning. Pinggy offre certificati CA pubblici anche per utenti gratuiti: verifica che il servizio esposto usi HTTPS (porta 443).

Conclusione della Soluzione

Pinggy permette agli utenti ServBay di aprire facilmente e con grande rapidità un canale sicuro verso l'esterno, esponendo siti e applicazioni locali al pubblico. I vantaggi principali includono:

• Nessuna installazione client: flusso di setup semplice e veloce.
• Operazioni one-click: il tunnel parte con un solo comando SSH.
• HTTPS automatico: Pinggy fornisce certificati CA pubblici gratuiti, eliminando i classici problemi dei certificati HTTPS per l’accesso pubblico.
• Supporto per tunnel HTTP e TCP: adatto a ogni tipo di servizio.
• Massima compatibilità con ServBay: la corretta impostazione dell’header Host semplifica l’esposizione di specifici siti locali ServBay.
• Comandi senza token: maggiore sicurezza nella condivisione temporanea con terzi.

Rispetto ad altri strumenti di tunneling locale più complessi, che richiedono l’installazione di software aggiuntivo o configurazioni pesanti, Pinggy offre una soluzione leggera e veloce—ideale per sviluppatori ServBay che vogliono testare, dimostrare o condividere rapidamente servizi locali. In progetti commerciali che richiedono stabilità a lungo termine o domini personalizzati, valuta i piani premium di Pinggy. L’unione della potenza ServBay come ambiente di sviluppo locale con l’accessibilità pubblica di Pinggy aumenterà notevolmente efficienza e produttività nel lavoro di sviluppo e collaborazione.