feat: land dashboard groundwork

README.MD

@@ -0,0 +1,69 @@
+# Gradio Tunnel Dashboard
+
+Dashboard web per un server Linux che individua le porte in ascolto, permette di avviare e fermare tunnel tramite `gradio-tunneling` e mostra l'URL generato, tutto dal browser.
+
+## Funzionalità principali
+
+- **Scanner portale intelligente** con caching TTL, riconoscimento del protocollo, utente, comando completo e link al container Docker quando disponibile.
+- **Dashboard unificata**: la sezione Porte mostra lo stato di ciascun port, mentre la tabella Tunnel permette di leggere l'output, aprire i log e interrompere i tunnel attivi.
+- **Controllo dei tunnel**: pulsanti Avvia/Ferma sincronizzati con lo stato del tunnel, badge visivi per sapere se una porta è occupata e aggiornamenti automatici ogni 4 secondi.
+- **Debug integrato**: pannello log per ogni tunnel con pulsante dedicato, e l'URL pubblico viene estratto dai log del processo.
+
+## Scanner porte e metadati
+
+Il modulo `app/services.py` utilizza `psutil` per enumerare le connessioni `LISTEN`, deduce protocollo/utente/processo/comando e abbina i PID ai container Docker tramite `/proc/<pid>/cgroup`. I risultati vengono memorizzati per 2 secondi per ridurre la pressione sulla CPU.
+
+La risposta `/api/ports` include ora:
+
+- `port`, `protocol`, `service`, `user`, `pid`, `command`, `container`, `local_address`
+
+Questi campi alimentano la tabella Porte e aiutano nelle decisioni manuali prima di aprire un tunnel.
+
+## Interfaccia web
+
+- La tabella Porte mostra metadati completi e un badge Tunnel che indica se la porta è già in uso. Il pulsante **Avvia tunnel** rimane disabilitato quando un tunnel è presente.
+- La tabella Tunnel mostra il PID, lo stato, l'URL pubblico, l'ultimo log e il comando invocato. I pulsanti **Log** e **Ferma** permettono debug e cleanup rapidi.
+- Il pannello inferiore espone i log del tunnel selezionato per trovare errori di connessione o capire quando viene stampato l'URL pubblico.
+
+## Avvio rapido
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Apri `http://localhost:8000`.
+
+## Configurazione
+
+Il comando usato per avviare i tunnel è configurabile con la variabile d'ambiente `TUNNEL_COMMAND`.
+
+Esempio:
+
+```bash
+export TUNNEL_COMMAND="python -m gradio_tunneling --port {port}"
+```
+
+Se il comando `python -m gradio_tunneling` non funziona, usa la CLI installata dal pacchetto:
+
+```bash
+export TUNNEL_COMMAND="gradio-tunneling --port {port}"
+```
+
+L'URL viene rilevato dalla prima stringa che contiene un link HTTP/HTTPS nel log del tunnel.
+
+La dashboard aggiorna automaticamente lo stato dei tunnel e mostra l'ultimo log per aiutare il debug quando l'URL non è disponibile.
+
+## Debug
+
+Nella sezione dei tunnel puoi aprire il pannello Log per vedere le ultime righe prodotte dal processo `gradio_tunneling`. Questo aiuta a capire se il tunnel non parte o se l'URL non viene stampato.
+
+## Rilevamento servizi Docker
+
+La tabella delle porte mostra anche il nome del container Docker quando disponibile. Questo richiede che il processo abbia accesso al socket Docker locale.
+
+## Dipendenze tunneling
+
+Il progetto usa `gradio-tunneling` (installato da GitHub tramite `requirements.txt`). Se stai usando un ambiente offline, installa manualmente il pacchetto nella venv prima di avviare il servizio.