Jinsi ya kujiendeshea SearXNG kwenye VPS na Docker

Unachojenga

Kujiendeshea SearXNG kunakupa injini ya utafutaji ya faragha inayofanya kazi kwenye seva yako mwenyewe. SearXNG ni injini ya metasearch: huchukua ombi lako, huuliza injini nyingine kama Google, Bing, DuckDuckGo na Wikipedia, kisha huunganisha matokeo yanayorudi kwenye ukurasa mmoja. Hakuna wasifu unaoundwa na hakuna tracking cookie inayowekwa, kwa sababu mashine pekee inayohifadhi ombi lako ni yako. Ikiwa umepata miongozo ya zamani ya kitu kinachoitwa Searx pekee, huo ndio mradi ambao huu umetoka (forked). Hujashughulikiwa tangu Septemba 2023, wakati repository yake ilipotangaza kuwa Searx haishughulikiwi tena, na commit moja tangu wakati huo, dokezo la nyaraka mnamo Mei 2026, haikubadili hali hiyo. Kwa hivyo kagua hali ya yote mawili kabla ya kufuata mmoja.

Stack hii ni ndogo. Containers mbili, faili moja ya settings, na reverse proxy moja. Itashiriki VPS ndogo kwa urahisi, jambo ambalo si kweli kwa kila huduma ya self-hosted: maktaba za picha zilizolinganishwa katika PhotoPrism dhidi ya Immich huweka kiwango cha chini cha RAM kupitia indexer badala ya web app. Uamuzi wa kweli ni kama instance hiyo ni ya faragha, ikimaanisha wewe na scripts zako pekee ndio mnaifikia, au ya umma, ikimaanisha yeyote kwenye Internet anaweza kuitumia. Chaguo hilo hubadili mipangilio ya usalama, kwa hivyo lifanye kabla ya kuandika chochote. Jibu chaguo-msingi ni faragha.

Kuna sababu ya pili ya kuendesha moja. Instance ya SearXNG huzungumza JSON, kwa hivyo script yoyote au AI agent unayoandika hupata search API unayomiliki, bila key, bila malipo kwa kila ombi na bila barua pepe za quota.

Kusakinisha SearXNG kwa kutumia Docker Compose

Mradi huu huchapisha image ya container na faili ya Compose. Vuta vyote viwili kwenye seva mpya ya Ubuntu 24.04 ambayo tayari ina Docker Engine na plugin ya Compose. Ikiwa Docker ni ngeni kwako, anza na misingi ya Docker Compose kwenye VPS kisha urudi hapa.

sudo install -d -o "$USER" -g "$USER" -m 750 /opt/searxng
cd /opt/searxng
mkdir -p core-config
curl -fsSL \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
cp -i .env.example .env

Faili ya Compose hufafanua huduma mbili. core ni SearXNG yenyewe, na valkey ni hifadhi ya data ya ndani ya kumbukumbu (in-memory) inayotumika kwa ajili ya rate limiting na hali ya muda mfupi. Inapachika (mount) ./core-config/ kwenye /etc/searxng/ ndani ya container, kwa hivyo kila kitu unachosanidi hukaa kwenye saraka hiyo moja kwenye host.

Sasa hariri .env. Kila mstari katika mfano uliotolewa umewekewa alama ya maoni (commented out), ndiyo maana container huanza kwenye port 8080 katika kila anwani. Ondoa alama ya maoni na uweke hizi tatu.

SEARXNG_VERSION=latest
SEARXNG_HOST=127.0.0.1
SEARXNG_PORT=8080

SEARXNG_HOST=127.0.0.1 ndiyo muhimu zaidi. Inafanya port iliyochapishwa kuwa 127.0.0.1:8080:8080 badala ya 8080:8080 tupu, ambayo Docker huchapisha kwenye kila anwani, kwa hivyo container hujibu tu kwenye anwani ya loopback na Internet haiwezi kuifikia moja kwa moja. Ikiwa utaruka hatua hii, container itakuwa wazi mara tu inapoanza, kwa sababu port ya Docker iliyochapishwa huwekwa mbele ya sheria zako za firewall. Mtego huo unastahili kusomwa kikamilifu: published Docker ports bypass ufw.

SEARXNG_VERSION=latest ni sawa wakati unajifunza. Kwenye seva unayoijali, funga (pin) tag. Kufikia Oktoba 2026, tag za toleo hutegemea tarehe na huonekana kama 2026.10.4-d48c4b555, kwa hivyo deployment iliyofungwa huboreshwa (upgrade) wakati wewe unapoamua, si wakati registry inapobadilika bila wewe kujua. Nidhamu hiyo hiyo inalipa kwa kitu kingine chochote cha muda mrefu kwenye mashine, ndiyo maana a self-hosted RustDesk relay hufunga tag zake za image pia: uboreshaji wa huduma ya ufikiaji wa mbali (remote access) usiofuatiliwa hujitangaza wakati mbaya zaidi.

settings.yml: sehemu muhimu

Unda core-config/settings.yml kabla ya kuanza kwa mara ya kwanza. use_default_settings: true huambia SearXNG kupakia mipangilio chaguo-msingi iliyokuja na programu, kisha kutumia funguo ulizoandika wewe pekee. Hivyo, faili yako inabaki fupi na haiharibiki wakati wa upgrades zinazoongeza chaguzi mpya.

Tengeneza secret kwanza, kwa sababu thamani hiyo huwekwa moja kwa moja kwenye faili.

openssl rand -hex 32

use_default_settings: true

general:
  instance_name: "search.example.com"

server:
  base_url: "https://search.example.com/"
  secret_key: "paste-the-openssl-output-here"
  limiter: false
  public_instance: false
  image_proxy: true

valkey:
  url: valkey://valkey:6379/0

search:
  safe_search: 0
  autocomplete: "duckduckgo"
  formats:
    - html
    - json

secret_key husaini data ya session na token. Thamani chaguo-msingi iliyokuja na programu ni mfuatano wa herufi ultrasecretkey. Ukiacha thamani hiyo, mtu yeyote anayeijua anaweza kughushi token hizo. Ibadilishe mara moja, kisha usiiguse tena: kuibadilisha baadaye kutafuta mapendeleo yote yaliyohifadhiwa.

base_url lazima iwe anwani ya umma ya HTTPS, ikifuatiwa na slash. Hii ndiyo anwani ambayo SearXNG huiandika kwenye viungo inavyozalisha. Ukiacha ikielekeza kwenye localhost, kiungo cha "ukurasa unaofuata" kwenye kivinjari cha mbali kitajaribu kuelekeza kwenye mashine ya mtumiaji mwenyewe na kitafeli.

formats huamua aina za matokeo ambayo endpoint ya wavuti itazalisha. json haipo kwenye orodha chaguo-msingi, kwa hivyo ombi la JSON litarudisha 403 hadi utakapoiingiza. image_proxy: true hupitisha picha ndogo (thumbnails) kupitia seva yako, ili tovuti zinazohifadhi picha hizo zisijue anwani za wageni wako.

valkey.url hutumia hostname valkey kwa sababu hilo ndilo jina la huduma katika faili ya Compose. Compose huweka container zote mbili kwenye mtandao mmoja ambapo majina ya huduma hutambulika. Ukiielekeza kwenye localhost, limiter itafeli, kwa sababu ndani ya container ya core, localhost ni container hiyo yenyewe.

Secret huhifadhiwa kwenye faili ya kawaida, kwa hivyo linda saraka inayozunguka faili hiyo pia. chmod 750 /opt/searxng huwazuia watumiaji wengine wa seva kuingia. Unaweza pia kukaza core-config/settings.yml hadi mode 600 bila kuvunja chochote: entrypoint ya container rasmi huanza kama root, na kwa FORCE_OWNERSHIP ikiachwa kwenye thamani yake chaguo-msingi ya true, hukabidhi saraka ya usanidi iliyopachikwa (mounted) kwa mtumiaji wa searxng wa container kabla SearXNG haijaanza. Hivyo, faili inabaki kusomeka kwake. Athari yake huonekana kwenye seva: hatua hiyo hiyo hubadilisha mmiliki wa core-config/ kuwa kitambulisho cha mtumiaji wa container, kwa hivyo tarajia kuhariri faili hiyo kwa kutumia sudo baadaye.

Anzisha stack na uikague.

cd /opt/searxng
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080/

docker compose ps inapaswa kuonyesha container zote mbili zikiwa katika hali ya running. curl inapaswa kujibu HTTP/1.1 200 OK. Ikiwa haijibu chochote, soma docker compose logs core, kwa sababu kosa la YAML katika settings.yml litaonekana hapo kama hitilafu ya uchanganuzi (parse error) inayotaja mstari husika.

Iweke nyuma ya nginx ikiwa na TLS

Container husikiliza kwenye loopback pekee, kwa hivyo nginx ndiyo inayofanya iweze kufikika, na pia ndiyo inayoongeza usalama wa safu ya usafirishaji (TLS). Andika /etc/nginx/sites-available/searxng.

server {
    listen 80;
    server_name search.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/searxng /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d search.example.com

nginx -t huchapisha syntax is ok na test is successful kabla hujapakia upya. Certbot huandika upya faili hiyo hiyo ili isikilize kwenye 443 ikiwa na cheti na huongeza uelekezaji (redirect) kutoka port 80. Rekodi ya DNS ya search.example.com lazima iwe tayari inaelekeza kwenye seva hii, kwa sababu mamlaka ya utoaji vyeti (certificate authority) huthibitisha umiliki kwa kuchota faili kupitia HTTP. Mwongozo kamili, ikijumuisha usasishaji, uko kwenye mwongozo wa Certbot na nginx kwa Ubuntu 24.04.

Vichwa viwili vya uelekezaji (forwarding headers) si mapambo. Bila X-Forwarded-For na X-Real-IP, kila ombi linalofika kwenye SearXNG hubeba anwani ya proxy, kwa hivyo kizuizi cha kasi (rate limiter) huona mteja mmoja akifanya trafiki yote na hakiwezi kutofautisha wageni.

Kwa nini hati na wakala wanahitaji API ya utafutaji ya JSON

Kwa json katika formats, endpoint ileile inayotoa ukurasa hurudisha data iliyopangiliwa.

curl -s 'http://127.0.0.1:8080/search?q=wireguard+mtu&format=json' \
  | jq -r '.results[0:5][] | .url'

Unapata kitu chenye array ya results, ambapo kila ingizo hubeba url, title, content na injini iliyolitoa, pamoja na answers, infoboxes na suggestions. Hiyo inatosha kulisha kifupishi, kikagua viungo, au mzunguko wa utafiti. Kukabidhi matokeo hayo kwa modeli ya lugha ni hatua kubwa kuliko inavyoonekana, kwa sababu matokeo ya utafutaji ni maandishi yasiyoaminika ambayo yanaweza kubeba maelekezo yao wenyewe, jambo ambalo kuelekeza wakala wa AI kwenye instance yako ya SearXNG hulifafanua kwa kina.

Hili ni muhimu kwa chochote chenye umbo la wakala. Modeli ya lugha ina kikomo cha mafunzo, kwa hivyo inahitaji utafutaji wa moja kwa moja ili kujibu maswali kuhusu wakati wa sasa, na API za utafutaji za kibiashara hutoza kwa kila ombi na kuweka vikwazo vikali vya kasi. Instance ya ndani inagharimu container moja kwenye seva unayolipia tayari, na maombi hayo hayaiachi seva hiyo. Ikiwa unaunganisha zana kwenye modeli, hoja hiyo hiyo ndiyo inayoongoza kuendesha seva za MCP kwenye VPS, ambapo zana ya utafutaji kwa kawaida ndiyo ya kwanza watu kuongeza.

Sheria mbili za matumizi ya API. Weka instance hiyo kuwa ya faragha, kwa hivyo funga upande wa API kwenye loopback address au kwenye mtandao wa faragha na uruhusu hosts zako pekee ndizo ziifikie, ambayo ni hatua sawa na ile tracker ya eneo inayojiendesha inahitaji kwa endpoint ambayo simu yako huripoti eneo lake. Kisha, tuma maombi kwa upole. SearXNG husambaza ombi lako kwa injini halisi za utafutaji, kwa hivyo hati inayoendesha maombi mia moja kwa sekunde inaiomba Google kuizuia seva yako.

Limiter, na mabadiliko kwa instance ya umma

Limiter ni mfumo wa ulinzi dhidi ya bot katika SearXNG. Hufuatilia vichwa vya maombi (request headers), anwani, na kasi ya maombi, kisha huzuia trafiki inayoonekana kama ya kiotomatiki. Inahitaji Valkey kuhifadhi hali hiyo, ndiyo maana faili ya Compose inaijumuisha.

Kwenye instance ya faragha, weka limiter: false. Script zako mwenyewe ni trafiki ya kiotomatiki kwa ufafanuzi, kwa hivyo limiter ingezuia hasa maombi ya JSON ambayo uliijengea instance hiyo. Udhibiti wa ufikiaji ni jukumu la reverse proxy badala yake: jozi ya allow na deny katika location ya nginx, HTTP basic authentication, au firewall inayoruhusu seva zako nyingine pekee. Ikiwa unahitaji kufikia instance ya faragha kutoka kwenye laptop inayohama kati ya mitandao, kuweka v3 onion address mbele yake ni chaguo la nne, kwa sababu tor huunganisha kwenye port ileile ya loopback bila kufichua chochote kipya kwenye mtandao.

Ikiwa utachapisha instance hiyo kwa watu wengine, washa swichi zote mbili.

server:
  limiter: true
  public_instance: true

Udhibiti wa kina unapatikana katika core-config/limiter.toml, ambayo container huisoma katika /etc/searxng/limiter.toml. Andika funguo unazotaka kubadilisha pekee. Nyuma ya proxy lazima utangaze proxy hiyo, vinginevyo limiter itachukulia anwani yako ya nginx kama mteja mmoja anayefanya matumizi mabaya.

[botdetection]
trusted_proxies = [
  '127.0.0.0/8',
  '::1',
]

[botdetection.ip_limit]
link_token = true

link_token = true huifanya SearXNG kutoa token ambayo ni session ya kivinjari halisi pekee itakayoipakua, jambo linalozuia scrapers rahisi nyingi. Tarajia instance ya umma kuvutia scrapers ndani ya siku chache. Tarajia pia makosa ya injini, kwa sababu kadiri unavyosambaza trafiki nyingi, ndivyo injini za juu (upstream engines) zinavyoanza kurejesha CAPTCHA kwenye anwani ya seva yako mapema zaidi. Instance ya umma ya SearXNG ni kazi endelevu. Instance ya faragha si hivyo, ndiyo maana inakaa kwenye orodha nyingi fupi za vitu vinavyofaa kujihostia mwaka 2026. Sio kila kitu kwenye orodha hizo ni miundombinu pia: kujenga upya maktaba ya Jellyfin kama duka la kukodisha la miaka ya 90 linalotembeleka ni container ileile moja nyuma ya block ileile ya nginx, iliyoelekezwa kwenye burudani ya jioni badala ya mtiririko wa kazi.

Kwa nini utafutaji haurejeshi matokeo yoyote

Fungua /stats kwenye instance yako. Inataja kila engine pamoja na kiwango chake cha makosa na muda wa majibu, na ndipo mahali pa kwanza pa kuangalia wakati matokeo yanapokuwa haba.

Engine inayoonyesha makosa ya "Access denied" au "CAPTCHA" imezuia anwani ya seva yako. Hili ni jambo la kawaida kwa anwani zilizo kwenye data centre ranges, kwa sababu search engines hudhani anwani hizo ni za scrapers. SearXNG kisha husimamisha engine inayofeli kwa muda badala ya kujaribu tena, hivyo engine moja iliyozuiwa huacha kutoa matokeo kimyakimya. Izime kwenye settings.yml au ukubali kupoteza matokeo hayo. Hizo si hatua mbili pekee, kwa sababu baadhi ya vizuizi vya CAPTCHA vina suluhisho linalodumu hata baada ya kuanzisha upya. Engine zilizobaki bado zitajibu. 429 ni hali isiyo na uhakika, kwa sababu inaweza kutoka kwa limiter yako mwenyewe au kutoka kwa upstream engine inayokataa seva yako, na mstari wa logi hukuambia ni ipi kati ya hizo mbili unayoiona kabla hujaanza kubadilisha mipangilio.

Ikiwa kila engine itafeli kwa wakati mmoja, container haina utatuzi wa majina (name resolution) wa nje unaofanya kazi au haina njia ya kufikia Internet. Jaribu hilo ukiwa ndani ya container.

docker compose exec core wget -qO- https://duckduckgo.com > /dev/null && echo ok

Hakuna kitu kwenye mashine kitakachokuambia wakati ukaguzi huo unapoanza kufeli, kwa hivyo uendeshe kupitia cron na uruhusu hitilafu kutuma tahadhari kwenye simu yako kutoka kwa ntfy server yako mwenyewe badala ya kusubiri hadi utambue kuwa matokeo yamepungua.

FAQ

Je, SearXNG inafanya utafutaji wangu kuwa wa siri?

Inaficha utambulisho wako kwa injini za utafutaji inazozitumia, kwa sababu zinaona seva yako ikituma ombi badala ya kivinjari chako. Hata hivyo, haifichi ombi lako kutoka kwa seva yako, wala haifichi seva yako kutoka kwa injini hizo. Kwenye instance ya mtumiaji mmoja, trafiki yote kutoka kwa anwani hiyo ni yako, hivyo anwani yenyewe inakuwa kitambulisho. Trafiki kati ya kivinjari chako na instance yako inalindwa na cheti cha TLS. Hali yako dhidi ya ISP, mwendeshaji wa instance ya umma, na injini za utafutaji zenyewe imefafanuliwa katika kile ambacho SearXNG inaficha kihalisi.

Kwa nini ombi la JSON linarudisha 403 Forbidden?

Kuna sababu mbili, na zote zinahusu usanidi. Aidha json haipo kwenye orodha ya formats chini ya search: katika settings.yml, hali ambayo ni ya kawaida (default), au limiter imewashwa na imetambua script yako kama bot. Ongeza format hiyo kwanza, anzisha upya kwa kutumia docker compose restart core, kisha jaribu tena. Ikiwa bado inafeli, weka limiter: false na udhibiti ufikiaji kupitia reverse proxy badala yake.

Je, ninahitaji container ya Valkey ikiwa nitazima limiter?

Iache iendelee kufanya kazi. SearXNG inafanya kazi bila hiyo, lakini limiter haiwezi kuwashwa baadaye bila hiyo, na pia inahifadhi hali nyingine za muda mfupi. Container hiyo ni ndogo na inahifadhi data ya akiba (cache) pekee, hivyo kuiondoa hakutaleta faida kubwa na kutakuondolea chaguo hilo.

Ninawezaje kusasisha SearXNG?

Tekeleza docker compose pull kisha docker compose up -d katika /opt/searxng. Compose inatengeneza upya container yoyote ambayo image yake imebadilika na kuacha saraka yako ya core-config/ bila kuguswa, hivyo settings.yml inabaki salama. Kwa sababu use_default_settings: true inaunganisha funguo zako juu ya zile za kawaida (defaults), chaguo zilizoongezwa na watengenezaji wa programu hiyo hufika zikiwa na thamani zinazofaa badala ya kuharibu faili yako.

Je, watu kadhaa wanaweza kutumia instance moja?

Ndiyo, na hiyo ndiyo hali ambapo unawasha limiter na kuweka public_instance: true. Mapendeleo (preferences) yanahifadhiwa kwenye kivinjari cha kila mtumiaji, hivyo hakuna akaunti za kusimamia. Fuatilia /stats kwa wiki moja baada ya kuifungua kwa umma, kwa sababu injini za utafutaji huanza kukataa seva yako muda mrefu kabla hujagundua kuwa matokeo fulani hayapo.