Come fare il self-hosting di Whoogle nel 2026: privacy, limiti di frequenza e impostazioni del proxy

Un container Whoogle può risultare operativo mentre la funzionalità che interessa agli utenti è guasta. Con Whoogle, questo problema nascosto consiste solitamente nel blocco dell'IP da parte del servizio upstream oppure in variabili d'ambiente del proxy errate. Questa guida considera come test di accettazione il seguente flusso: “inviare ricerche con impostazioni normali e di privacy, verificare i link dei risultati, testare un proxy upstream e attivare il limite di frequenza scelto”, quindi costruisce il deployment a ritroso partendo da questo risultato.

Whoogle svolge un ruolo specifico nello stack: offre risultati di ricerca Google senza annunci, tracking o JavaScript lato client. La domanda in produzione non è quindi se la porta 5000 risponde una volta, ma se stato, dipendenze e indirizzo pubblico continuano a essere coerenti dopo un riavvio, un aggiornamento e un ripristino.

Definisci prima il successo di Whoogle

Un diagramma utile di Whoogle mostra il percorso pubblico, la porta privata 5000, il confine dello stato e ogni requisito di supporto. Indica quali frecce trasportano credenziali e quali rappresentano il normale traffico degli utenti. Il requisito esterno di Whoogle è l'accesso HTTPS in uscita e un IP stabile del server accettato dai provider di ricerca. Testa DNS, TLS e comportamento del provider in uscita senza pubblicare un altro servizio in ingresso.

Dimostra il diagramma con un'azione reale: invia ricerche con impostazioni normali e di privacy, verifica i link dei risultati, testa un proxy upstream e attiva il limite di frequenza scelto. La pressione più probabile deriva dal blocco della ricerca upstream, dalla reputazione dell'IP del server, dalle query concorrenti e dalla latenza del proxy; monitora questo percorso invece di trattare tutte le richieste HTTP allo stesso modo.

Instrada Whoogle senza fingere che usi HTTPS

Evita origini pubbliche temporanee e permanenti per Whoogle. Pubblica invece l'interfaccia di ricerca tramite HTTPS con limiti di frequenza misurati, indirizza il nome DNS scelto verso il percorso della piattaforma e inoltra il traffico solo alla porta 5000.

Esegui questa azione dall'esterno dell'host: invia ricerche con impostazioni normali e di privacy, verifica i link dei risultati, testa un proxy upstream e attiva il limite di frequenza scelto. Se l'ingresso non funziona, la guida alla risoluzione dei problemi 502 tratta gli errori relativi a porte e listener. Se Whoogle riceve la richiesta ma il servizio upstream blocca l'IP oppure le variabili d'ambiente del proxy sono errate, gli indizi puntano ora oltre il proxy.

Rendi riproducibile l'avvio di Whoogle

Il primo container deve poter essere eliminato e ricreato facilmente. Mantieni i dati fuori dal writable layer, associa la porta 5000 solo dove il proxy può raggiungerla e passa la configurazione a runtime.

docker run -d \
  --name whoogle \
  --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  -v whoogle-data:/config \
  -e WHOOGLE_CONFIG_PASSWORD=replace-with-a-long-random-value \
  benbusby/whoogle-search:latest

Blocca la versione dell'immagine dopo il test iniziale. Leggi il primo errore di avvio invece del messaggio finale di riavvio, verifica ogni mount con docker inspect e segui i log mentre invii ricerche con impostazioni normali e di privacy, verifichi i link dei risultati, testi un proxy upstream e attivi il limite di frequenza scelto. Questa sequenza distingue un comando dell'immagine errato da un problema di dipendenze o permessi.

Log che rispondono alla domanda successiva

Per Whoogle, monitora una transazione anziché un processo: invia ricerche con impostazioni normali e di privacy, verifica i link dei risultati, testa un proxy upstream e attiva il limite di frequenza scelto. Combina latenza e tasso di errore con il blocco della ricerca upstream, la reputazione dell'IP del server, le query concorrenti e la latenza del proxy, così che un alert identifichi il componente sotto pressione.

La prova generale dell'aggiornamento deve tenere conto del fatto che il markup upstream e le release di Whoogle possono interrompere il parsing senza rendere il container non operativo. Esegui ripristino, migrazione e transazione prima della sostituzione in produzione. Se il servizio upstream blocca l'IP oppure le variabili d'ambiente del proxy sono errate, non cancellare i dati per far risultare corretto l'avvio; confronta nell'ordine versione, variabili, mount e raggiungibilità delle dipendenze.

Trasforma lo smoke test di Whoogle in un controllo di release

Crea un piccolo fixture Whoogle temporaneo e conservalo per ogni release. Il fixture deve eseguire il workflow reale: inviare ricerche con impostazioni normali e di privacy, verificare i link dei risultati, testare un proxy upstream e attivare il limite di frequenza scelto. Registra il digest dell'immagine, l'hostname esterno, l'indirizzo della dipendenza e il risultato atteso, così che un operatore possa ripetere il test in seguito senza dover interpretare questa guida.

Esegui il fixture tre volte. Prima, usa il deployment appena creato. Poi, sostituisci il container senza modificare lo stato persistente. Infine, ripristina il backup in un ambiente vuoto. La terza esecuzione supera il test solo quando la configurazione e le preferenze tornano disponibili e un set fisso di query continua a produrre link dei risultati utilizzabili. Durante ogni esecuzione, registra latenza e utilizzo delle risorse in relazione al blocco della ricerca upstream, alla reputazione dell'IP del server, alle query concorrenti e alla latenza del proxy; questi dati diventano la baseline per gli alert, invece di una percentuale arbitraria di CPU.

Infine, testa deliberatamente il percorso negativo: nega temporaneamente il percorso di test usato per l'accesso HTTPS in uscita e per un IP stabile del server accettato dai provider di ricerca. Conferma che Whoogle fallisca in modo evidente senza corrompere lo stato, ripristina la condizione corretta e ripeti la transazione completata con successo. Un record della release contenente questi quattro risultati offre prove più solide degli screenshot di una dashboard o della risposta ottenuta una sola volta con curl.

Individua ogni byte persistente in Whoogle

Crea un inventario di ogni elemento persistente: la configurazione e le eventuali preferenze degli utenti memorizzate su disco. Monta /config prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è realmente persistente. Includi anche la configurazione che modifica il modo in cui i dati memorizzati vengono interpretati, non solo la directory più grande.

Definisci la retention, copia i backup fuori dall'host ed esegui un ripristino in clean room. La verifica di Whoogle è completa quando la configurazione e le preferenze tornano disponibili e un set fisso di query continua a produrre link dei risultati utilizzabili. Se i tuoi piani includono gli snapshot, usa le indicazioni su PITR e snapshot per documentare cosa può recuperare ciascun meccanismo.

Proteggi la parte più importante di Whoogle

Un deployment sicuro di Whoogle inizia dalla riduzione dei privilegi. Evita di eseguire un proxy pubblico aperto e privo di controlli contro gli abusi; proteggi invece ogni istanza pubblica con autenticazione o controlli di frequenza e mantieni le credenziali del proxy fuori dall'immagine.

Sostituisci subito l'esempio WHOOGLE_CONFIG_PASSWORD, memorizzalo fuori dall'immagine e ruotalo come una credenziale amministrativa se viene esposto. Limita le route amministrative, usa DNS privato per le dipendenze e verifica ogni bind mount. Quando i log vengono inviati a un sistema centralizzato, filtra secret e contenuti privati prima che lascino il server.

Cosa dovrebbe automatizzare Dockup per Whoogle

Dockup elimina il lavoro manuale relativo a reverse proxy e lifecycle per Whoogle. Durante le sostituzioni, il servizio riceve un percorso HTTPS stabile verso la porta 5000, la configurazione iniettata e lo storage persistente. Un server del cliente collegato segue lo stesso modello del compute ospitato da Dockup.

Dopo il lancio, soddisfa il contratto dell'applicazione: pubblica l'interfaccia di ricerca tramite HTTPS con limiti di frequenza misurati, consenti e verifica l'accesso HTTPS in uscita e un IP stabile del server accettato dai provider di ricerca, quindi esegui questa prova: invia ricerche con impostazioni normali e di privacy, verifica i link dei risultati, testa un proxy upstream e attiva il limite di frequenza scelto. In questo modo l'esperienza one-click rimane utile senza appiattire i dettagli che rendono Whoogle ripristinabile e sicuro.

Domande frequenti

Di cosa ha bisogno Whoogle per un deployment in produzione?

Instrada il container Whoogle sulla porta 5000 attraverso un'unica origine HTTPS. Il requisito esterno per la distribuzione è l'accesso HTTPS in uscita e un IP stabile del server accettato dai provider di ricerca. Non considerare Whoogle pronto finché non puoi inviare ricerche con impostazioni normali e di privacy, verificare i link dei risultati, testare un proxy upstream e attivare il limite di frequenza scelto.

Quali dati di Whoogle devono essere inclusi in un backup?

Rendi persistente /config e includi la configurazione e le eventuali preferenze degli utenti memorizzate su disco nello stesso manifest di ripristino. Un ripristino pulito di Whoogle supera il test solo quando la configurazione e le preferenze tornano disponibili e un set fisso di query continua a produrre link dei risultati utilizzabili.

Whoogle richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Whoogle e mantieni la porta 5000 nel percorso interno. Applica correttamente l'impostazione di Whoogle: pubblica l'interfaccia di ricerca tramite HTTPS con limiti di frequenza misurati. Per Whoogle, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come si deve testare un aggiornamento di Whoogle?

Ripristina lo stato corrente di Whoogle in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione al fatto che il markup upstream e le release di Whoogle possono interrompere il parsing senza rendere il container non operativo. Mantieni l'immagine precedente di Whoogle finché non sono chiari i limiti della migrazione dei dati e del rollback.