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 unaojengwa 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 (fork), na haujapokea commit yoyote tangu 2023, kwa hivyo kagua hali ya miradi yote miwili kabla ya kufuata mwongozo mmoja.

Stack hii ni ndogo. Container 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 script zako pekee ndio mnaoweza kuifikia, au ya umma, ikimaanisha mtu yeyote kwenye Internet anaweza kuitumia. Chaguo hilo hubadilisha mipangilio ya usalama, kwa hivyo lifanye kabla ya kuandika chochote. Jibu chaguo-msingi ni faragha.

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

Kusakinisha SearXNG kwa 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 inayotumika kwa ajili ya kuzuia kasi ya maombi (rate limiting) na kwa hali ya muda mfupi. Inapachika ./core-config/ kwenye /etc/searxng/ ndani ya container, kwa hivyo kila kitu unachosanidi hukaa kwenye saraka hiyo moja kwenye seva mwenyeji.

Sasa hariri .env. Kila mstari katika mfano uliotolewa umewekewa alama ya maoni, ndiyo sababu 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, ili container ijibu tu kwenye anwani ya loopback na mtandao wa Internet usiweze kuifikia moja kwa moja. Ukiruka 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: port za Docker zilizochapishwa hupita ufw.

SEARXNG_VERSION=latest ni sawa wakati unajifunza. Kwenye seva unayojali, funga (pin) tag hiyo. Kufikia Julai 2026, tag za toleo hutegemea tarehe na huonekana kama 2026.3.25-541c6c3cb, kwa hivyo usakinishaji uliopangwa hupata maboresho wakati unapoamua wewe, si wakati registry inapobadilika bila taarifa. Nidhamu hiyo hiyo hulipa kwa kitu kingine chochote cha muda mrefu kwenye seva, ndiyo sababu relay ya RustDesk inayojiendesha hufunga tag zake za image pia: uboreshaji wa huduma ya ufikiaji wa mbali usiosimamiwa 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 chaguo-msingi zake zilizokuja na programu kisha kutumia funguo ulizoandika pekee, hivyo faili lako hubaki fupi na litaendelea kufanya kazi hata baada ya upgrades zinazoongeza chaguo 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 hutumika kusaini data ya session na token. Chaguo-msingi lililokuja na programu ni mfuatano wa herufi ultrasecretkey, na kuliacha hivyo humaanisha mtu yeyote anayejua chaguo-msingi hilo anaweza kughushi tokens hizo. Libadilishe mara moja, kisha usiliguse tena: kulibadilisha baadaye kutafuta mapendeleo yote yaliyohifadhiwa.

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

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

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

Secret hukaa kwenye faili la kawaida, kwa hivyo linda saraka inayozunguka faili hilo badala ya faili lenyewe. chmod 750 /opt/searxng huwazuia watumiaji wengine wa host kuingia. Usikaze core-config/settings.yml hadi mode 600: container huendeshwa kama mtumiaji wake asiye na upendeleo (unprivileged user), na faili ambalo haliwezi kusoma litazuia SearXNG kuanza kabisa.

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 containers 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 kosa la uchanganuzi (parse error) linalotaja mstari husika.

Iweke nyuma ya nginx 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 ya kufanya reload. Certbot huandika upya faili hiyo hiyo ili isikilize kwenye 443 ikiwa na cheti na huongeza redirect kutoka port 80. Rekodi ya DNS ya search.example.com lazima iwe tayari inaelekeza kwenye seva hii, kwa sababu mamlaka ya utoaji vyeti huthibitisha umiliki kwa kuchota faili kupitia HTTP. Mwongozo kamili, ikijumuisha ufanyaji upya (renewal), uko kwenye mwongozo wa Certbot na nginx kwa Ubuntu 24.04.

Header mbili za usambazaji 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 akizalisha trafiki yote na hakiwezi kutofautisha wageni.

Kwa nini hati na mawakala wanahitaji API ya utafutaji ya JSON

Kwa json katika formats, endpoint ileile inayotoa ukurasa inarudisha data iliyopangwa.

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

Unapata kitu chenye safu ya results, ambapo kila ingizo lina url, title, content na injini iliyolitoa, pamoja na answers, infoboxes na suggestions. Hiyo inatosha kulisha kifaa cha kufupisha, 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 yake yenyewe, jambo ambalo kuelekeza wakala wa AI kwenye instance yako ya SearXNG linachambua 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 ada kwa kila swali na kuweka vikwazo vikali vya kasi. Instance ya ndani inagharimu container moja kwenye seva unayolipia tayari, na maswali 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 uwaruhusu wenyeji wako pekee kuifikia. Kisha itumie kwa upole. SearXNG husambaza ombi lako kwa injini halisi za utafutaji, kwa hivyo hati inayoendesha mamia ya maswali kwa sekunde inaiomba Google kuizuia seva yako.

Kizuizi, na mabadiliko kwa ajili ya instance ya umma

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

Kwenye instance ya faragha, weka limiter: false. Hati zako (scripts) ni trafiki ya kiotomatiki kwa ufafanuzi, kwa hivyo kizuizi kingezuia hasa maombi ya JSON ambayo ulijenga instance hiyo kwa ajili yake. 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 kwa laptop inayohama kati ya mitandao, kuweka anwani ya v3 onion mbele yake ni chaguo la nne, kwa sababu tor huunganisha kwenye port ileile ya loopback bila kufichua chochote kipya kwenye Internet.

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

server:
  limiter: true
  public_instance: true

Udhibiti wa kina zaidi upo 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 kizuizi kitachukulia 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 itakayoichukua, jambo linalozuia wadukuzi (scrapers) wengi rahisi. Tarajia instance ya umma kuwavutia ndani ya siku chache. Tarajia pia hitilafu za 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

Fungua /stats kwenye instance yako. Inataja kila injini pamoja na kiwango chake cha makosa na muda wa majibu, na ndipo mahali pa kwanza pa kuangalia wakati matokeo yanapoonekana kuwa machache.

Engine inayoonyesha makosa ya "Access denied" au "CAPTCHA" imezuia anwani ya seva yako. Hili ni jambo la kawaida kwa anwani zilizo kwenye range za vituo vya data, kwa sababu search engines hudhani kuwa anwani hizo ni za scrapers. Kisha SearXNG husitisha engine iliyoshindwa kwa muda badala ya kuijaribu tena, hivyo engine moja iliyozuiwa huondoka kimya kwenye matokeo yako. Izime katika settings.yml au ukubali kupoteza matokeo yake. Hizo si hatua mbili pekee, kwa sababu baadhi ya vizuizi vya CAPTCHA vina suluhisho linaloendelea kufanya kazi baada ya kuwasha upya. Engines zilizobaki bado hujibu. 429 ni hali isiyo wazi, kwa sababu inaweza kusababishwa na limiter yako au engine ya upstream inayokataa seva yako, na mstari wa log unaonyesha ni hali gani kati ya hizo mbili unayokabili kabla hujaanza kubadilisha mipangilio.

Ikiwa kila injini 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 kutoka kwenye cron na uruhusu hitilafu kutuma tahadhari kwenye simu yako kutoka kwa seva yako ya ntfy badala ya kusubiri hadi utambue kuwa matokeo yamepungua.

FAQ

Je, SearXNG hufanya utafutaji wangu kuwa wa siri?

Inaficha utambulisho wako kwa injini za utafutaji inazozitumia, kwa sababu zinaona seva yako ndiyo inayotuma ombi badala ya kivinjari chako. Hii 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, kwa 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 huficha kihalisi.

Kwa nini ombi la JSON hurejesha 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 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 hufanya kazi bila hiyo, lakini limiter haiwezi kuwashwa baadaye bila hiyo, na pia inashikilia hali nyingine za muda mfupi (short-lived state). Container hiyo ni ndogo na huhifadhi data iliyocheshwa (cached data) pekee, kwa hivyo kuiondoa hakukupi faida kubwa na kunakuondolea chaguo hilo.

Ninawezaje kusasisha SearXNG?

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

Je, watu kadhaa wanaweza kutumia instance moja?

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