Come eseguire il self-hosting di SearXNG nel 2026: Search API, rate limit e TLS

La maggior parte delle note sull'installazione di SearXNG si ferma al primo caricamento della pagina. È troppo presto: gli engine possono bloccare l'IP del server oppure i formati possono omettere json per i client API. Un test di produzione utile è più rigoroso: invia ricerche sia HTML sia JSON, verifica che diversi engine contribuiscano ai risultati e attiva il limiter configurato da un client di test.

Il ruolo di SearXNG è semplice: un motore di metasearch orientato alla privacy e una Search API. Il suo perimetro operativo comprende più del solo processo web, quindi dipendenza, stato persistente e route pubblica devono essere identificati esplicitamente prima che arrivino dati reali.

Definisci prima i criteri di successo per SearXNG

Non lasciare che l'immagine di SearXNG determini per caso l'architettura di produzione. L'immagine fornisce un processo sulla porta 8080; storage, routing e requisiti esterni richiedono comunque cicli di vita definiti intenzionalmente. Il contratto di rete di SearXNG prevede Redis o Valkey quando sono abilitate le funzionalità di limiter e rilevamento dei bot. Mantieni gli endpoint privati sul DNS interno, consenti solo le chiamate in uscita necessarie e assegna a SearXNG credenziali di servizio con ambito limitato.

Il deployment è pronto per test più approfonditi quando può inviare ricerche sia HTML sia JSON, verificare che diversi engine contribuiscano ai risultati e attivare il limiter configurato da un client di test. Segui la transazione nei log e monitora la latenza degli engine upstream, le query simultanee, il parsing dei risultati e i ban applicati all'IP del server. Queste osservazioni mostrano se la topologia attuale isola il componente corretto.

Separa i container sostituibili dai dati persistenti

Prepara un manifest di recovery per SearXNG: settings.yml, configurazione del limiter ed eventuali plugin locali. Monta /etc/searxng prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per verificare che il percorso sia effettivamente persistente. Controlla subito ownership e spazio libero, perché un percorso montato ma non scrivibile equivale, di fatto, a nessuna persistenza.

Esegui il backup in un failure domain separato dal server in esecuzione. Ricrea SearXNG dalla sua immagine fissata a una versione specifica e verifica che engine personalizzati, formati, regole del limiter e impostazioni del proxy vengano ripristinati e che una query nota produca risultati da più engine. La guida ai persistent volume aiuta a trasformare questo esercizio in una policy di snapshot e retention.

Chiudi l'accesso temporaneo di configurazione

Le credenziali di bootstrap sono temporanee; il modello di trust è permanente. Con SearXNG, fai attenzione a non distribuire il secret_key di esempio o a disabilitare i controlli sul rate limit su un endpoint pubblico; mantieni invece una secret key non predefinita, abilita i controlli anti-abuso ed esponi JSON solo quando è richiesto da un agent o da un'applicazione.

Gestisci SEARXNG_SECRET in base al suo ruolo in SearXNG: mantieni i valori sensibili fuori da Git, documenta gli effetti della rotazione e non sostituire mai un esempio pubblico in produzione. Esegui l'immagine senza capacità Linux non necessarie ed esponi solo la route applicativa pubblica. Mantieni visibile l'attività amministrativa senza registrare i valori segreti.

Registra un deployment di SearXNG noto come funzionante

Trasforma lo smoke test di SearXNG in un comando di release ripetibile o in un breve runbook. Il suo output deve dimostrare questo risultato: inviare ricerche sia HTML sia JSON, verificare che diversi engine contribuiscano ai risultati e attivare il limiter configurato da un client di test. Registra insieme al risultato la versione dell'applicazione, il digest del container, l'hostname della route e l'identificativo dei dati di test.

Esegui lo stesso controllo dopo una normale sostituzione del container e dopo aver ripristinato settings.yml, la configurazione del limiter e gli eventuali plugin locali in un'altra posizione. Il restore è riuscito quando engine personalizzati, formati, regole del limiter e impostazioni del proxy vengono ripristinati e una query nota produce risultati da più engine. Confronta i tempi e il consumo legati alla latenza degli engine upstream, alle query simultanee, al parsing dei risultati e ai ban applicati all'IP del server; una variazione significativa merita un'indagine anche quando l'azione finale continua ad avere esito positivo.

Esegui poi un failure test sicuro: nega temporaneamente all'identità di test l'accesso a Redis o Valkey quando sono abilitate le funzionalità di limiter e rilevamento dei bot. Verifica che SearXNG mostri l'errore e torni alla normalità senza modifiche manuali distruttive. Conserva solo l'estratto di log necessario e con i dati sensibili oscurati. Questo controllo in quattro parti copre avvio, persistenza, recovery e gestione dei guasti.

Esegui la prima istanza con caratteristiche simili alla produzione

Usa il container come runtime sostituibile, non come fonte dei dati.

docker run -d \
  --name searxng \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v searxng-data:/etc/searxng \
  -e SEARXNG_SECRET=replace-with-a-long-random-value \
  searxng/searxng:latest

Aggiungi le impostazioni di connessione verificate per Redis o Valkey quando sono abilitate le funzionalità di limiter e rilevamento dei bot; usa nomi privati per i servizi privati. Controlla l'utente del container, i percorsi scrivibili e il listener associato prima di esporlo. Esegui l'azione completa — invia ricerche sia HTML sia JSON, verifica che diversi engine contribuiscano ai risultati e attiva il limiter configurato da un client di test — e salva l'esatto riferimento all'immagine che ha prodotto il risultato.

Impedisci che il successo del proxy mascheri un errore dell'applicazione

Esponi un solo hostname HTTPS per SearXNG; mantieni privata la porta 8080 esposta direttamente. Imposta server base_url e gli header del proxy trusted per HTTPS. In questo modo impedisci a browser e client API di apprendere due indirizzi in competizione.

Da un client pulito, esegui la transazione nota come funzionante e analizza la prima richiesta che fallisce. Usa la guida ai custom domain quando DNS o TLS non sono configurati correttamente. Considera “gli engine bloccano l'IP del server oppure i formati omettono json per i client API” una diagnosi applicativa separata, da eseguire solo dopo aver verificato la route.

Log che rispondono alla domanda successiva

La prima metrica operativa utile per SearXNG indica se può inviare ricerche sia HTML sia JSON, verificare che diversi engine contribuiscano ai risultati e attivare il limiter configurato da un client di test. Affiancala ai segnali di saturazione relativi alla latenza degli engine upstream, alle query simultanee, al parsing dei risultati e ai ban applicati all'IP del server. Una probe limitata al processo non dovrebbe chiamare dipendenze costose né riavviare il container perché un upstream è temporaneamente non disponibile.

Considera gli aggiornamenti come modifiche ai dati, perché la sintassi delle impostazioni, le definizioni degli engine e il comportamento del limiter possono cambiare; esegui quindi il deployment della configurazione e delle modifiche all'immagine nell'ambito della stessa review. Fissa le versioni, fai una prova sullo stato ripristinato e mantieni disponibile l'immagine precedente finché il rollback non sarà più garantito. Quando gli engine bloccano l'IP del server oppure i formati omettono json per i client API, conserva i log precedenti al riavvio; di solito contengono il messaggio che spiega la causa.

Collega SearXNG al ciclo di vita di Dockup

Il platform layer di SearXNG comprende la porta 8080, l'ingress, TLS, la configurazione del runtime, lo storage e la raggiungibilità delle dipendenze. Dockup può riprodurre questi componenti per la propria infrastruttura o per un server collegato dal cliente.

A quel punto l'operatore completa il product layer: imposta server base_url e gli header del proxy trusted per HTTPS; applica questa regola di accesso — mantieni una secret key non predefinita, abilita i controlli anti-abuso ed esponi JSON solo quando è richiesto da un agent o da un'applicazione —; quindi esegue “invia ricerche sia HTML sia JSON, verifica che diversi engine contribuiscano ai risultati e attiva il limiter configurato da un client di test”. Registrare questo test insieme al deployment evita di confondere il provisioning automatico con la readiness dell'applicazione.

Domande frequenti

Di cosa ha bisogno SearXNG per un deployment di produzione?

Instrada il container SearXNG sulla porta 8080 attraverso un'unica origin HTTPS. Il requisito di rete di supporto è Redis o Valkey quando sono abilitate le funzionalità di limiter e rilevamento dei bot. Non considerare SearXNG pronto finché non puoi inviare ricerche sia HTML sia JSON, verificare che diversi engine contribuiscano ai risultati e attivare il limiter configurato da un client di test.

Quali dati di SearXNG devono essere inclusi in un backup?

Rendi persistente /etc/searxng e includi settings.yml, la configurazione del limiter e gli eventuali plugin locali nello stesso manifest di recovery. Un restore pulito di SearXNG ha esito positivo solo quando engine personalizzati, formati, regole del limiter e impostazioni del proxy vengono ripristinati e una query nota produce risultati da più engine.

SearXNG richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origin pubblico di SearXNG e mantieni la porta 8080 sulla route interna. Applica correttamente l'impostazione di SearXNG: imposta server base_url e gli header del proxy trusted per HTTPS. Per SearXNG, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento dei client sensibile all'origin.

Come si deve testare un aggiornamento di SearXNG?

Ripristina lo stato attuale di SearXNG in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione perché la sintassi delle impostazioni, le definizioni degli engine e il comportamento del limiter possono cambiare; esegui quindi il deployment della configurazione e delle modifiche all'immagine nell'ambito della stessa review. Mantieni l'immagine precedente di SearXNG finché non saranno chiari i limiti della migrazione dei dati e del rollback.