Paano mag-self-host ng SearXNG gamit ang Docker
Magpatakbo ng pribadong SearXNG sa VPS gamit ang Docker Compose, settings.yml, limiter, nginx na may TLS, at JSON search API para sa sarili mong scripts.
Ano ang binubuo mo
Ang pag-self-host ng SearXNG ay nagbibigay sa iyo ng pribadong search engine na tumatakbo sa sarili mong server. Ang SearXNG ay isang metasearch engine: ipinapadala nito ang query mo sa iba pang engine gaya ng Google, Bing, DuckDuckGo, at Wikipedia, pagkatapos ay pinagsasama ang mga resulta sa isang result page. Walang profile na binubuo at walang tracking cookie na itinatakda, dahil ang sarili mong machine lamang ang nag-iingat ng query mo. Kung nakakita ka ng mga lumang guide para sa tinatawag na Searx, iyon ang project na pinagmulan ng fork na ito. Hindi na ito mina-maintain mula September 2023, nang ipahayag ng sarili nitong repository na hindi na mina-maintain ang Searx. Hindi rin iyon nabago ng nag-iisang commit mula noon, isang documentation note noong May 2026. Kaya suriin ang status ng dalawa bago ka sumunod sa alinman sa mga ito.
Simple ang stack. Dalawang container, isang settings file, at isang reverse proxy. Madali itong tatakbo sa isang maliit na VPS. Hindi ito totoo para sa bawat self-hosted service: ang mga photo library na inihambing sa PhotoPrism laban sa Immich ay nagtatakda ng minimum na RAM batay sa indexer, hindi sa web app. Ang tunay na pagpapasya ay kung pribado ang instance, ibig sabihin ikaw at ang sarili mong scripts lamang ang makaka-access dito, o public, ibig sabihin kahit sino sa internet ay maaaring magpadala rito ng query. Binabago ng pagpiling ito ang security settings, kaya magpasya muna bago ka mag-type ng anuman. Ang default na sagot ay pribado.
May isa pang dahilan para magpatakbo nito. JSON ang ginagamit ng isang SearXNG instance, kaya anumang script o AI agent na isusulat mo ay magkakaroon ng search API na pagmamay-ari mo. Hindi nito kailangan ng key, per-query billing, o quota notification.
Mag-install ng SearXNG gamit ang Docker Compose
Naglalabas ang project ng container image at Compose file. I-pull ang dalawang ito sa isang bagong Ubuntu 24.04 server na mayroon nang Docker Engine at Compose plugin. Kung bago sa iyo ang Docker, magsimula sa Mga batayan ng Docker Compose sa isang VPS at bumalik dito.
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 .envTinutukoy ng Compose file ang dalawang service. Ang core ay ang SearXNG mismo, at ang valkey ay isang in-memory data store na ginagamit para sa rate limiting at panandaliang state. Imo-mount nito ang ./core-config/ sa /etc/searxng/ sa loob ng container, kaya nasa iisang directory lang sa host ang lahat ng iko-configure mo.
Ngayon, i-edit ang .env. Naka-comment out ang bawat linya sa example na kasama sa release, kaya nagsisimula ang container sa port 8080 sa lahat ng address. I-uncomment at itakda ang tatlong ito.
SEARXNG_VERSION=latest
SEARXNG_HOST=127.0.0.1
SEARXNG_PORT=8080Mahalaga ang SEARXNG_HOST=127.0.0.1. Ginagawa nitong 127.0.0.1:8080:8080 ang published port sa halip na isang simpleng 8080:8080, na ipinapublish ng Docker sa bawat address. Dahil dito, sa loopback address lamang sumasagot ang container at hindi ito direktang maaabot ng internet. Kapag nilaktawan mo ito, malalantad ang container sa sandaling magsimula ito, dahil ipinapasok ang published Docker port bago ang iyong firewall rules. Mahalagang basahin nang buo ang pitfall na ito: nilalampasan ng published Docker ports ang ufw.
Ayos ang SEARXNG_VERSION=latest habang nag-aaral ka. Sa server na mahalaga sa iyo, i-pin ang tag. Noong October 2026, date based ang release tags at ganito ang hitsura ng 2026.10.4-d48c4b555, kaya mag-a-upgrade ang pinned deployment kapag ikaw ang nagpasya, hindi kapag nagbago ang registry. Kapaki-pakinabang din ang parehong disiplina sa iba pang matagal na tumatakbo sa server, kaya nagpi-pin din ng image tags ang isang self-hosted na RustDesk relay: lumalabas ang unattended upgrade ng remote access service sa pinakamasamang pagkakataon.
settings.yml: mahahalagang bahagi
Gawin ang core-config/settings.yml bago ang unang pagsisimula. Sinasabi ng use_default_settings: true sa SearXNG na i-load ang sarili nitong shipped defaults at ilapat lamang ang mga key na isinulat mo. Dahil dito, maikli ang iyong file at mananatili itong gumagana sa mga upgrade na nagdaragdag ng mga bagong option.
I-generate muna ang secret dahil direktang ilalagay ang value sa file.
openssl rand -hex 32use_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
- jsonAng secret_key ang pumipirma sa session at token data. Ang shipped default nito ay ang literal na string na ultrasecretkey. Kapag iniwan mo ito, maaaring i-forge ng sinumang nakaaalam ng default na iyon ang mga token. Palitan ito nang isang beses at huwag nang baguhin: kapag binago mo ito sa ibang pagkakataon, mabubura ang lahat ng naka-save na preference.
Ang base_url ay dapat ang public HTTPS address, kasama ang trailing slash. Ito ang address na isinusulat ng SearXNG sa mga link na nire-render nito. Kapag iniwan itong tumuturo sa localhost, ang "next page" link sa remote browser ay tuturo sa sariling machine ng user at mabibigo.
Tinutukoy ng formats kung aling output type ang gagawin ng web endpoint. Wala ang json sa default list, kaya magbabalik ng 403 ang JSON request hanggang idagdag mo ito. Ipinapadaan ng image_proxy: true ang result thumbnail sa iyong server, kaya hindi makikita ng mga site na nagho-host ng mga larawang iyon ang mga address ng iyong mga user.
Ginagamit ng valkey.url ang hostname na valkey dahil iyon ang service name sa Compose file. Inilalagay ng Compose ang dalawang container sa iisang network kung saan nagre-resolve ang mga service name. Kapag itinuro mo ito sa localhost, mabibigo ang limiter dahil sa loob ng core container, ang localhost ay ang container mismo.
Nasa plain file ang secret, kaya protektahan din ang directory na naglalaman nito. Pinipigilan ng chmod 750 /opt/searxng na ma-access ito ng ibang host user. Maaari mo ring higpitan ang core-config/settings.yml sa mode na 600 nang walang masisirang functionality. Nagsisimula bilang root ang entrypoint ng official container. Kapag nananatili sa default nitong true ang FORCE_OWNERSHIP, ipinapasa nito ang mounted config directory sa sariling searxng user ng container bago magsimula ang SearXNG. Dahil dito, nananatiling readable sa user na iyon ang file. Makikita ang side effect sa host: binabago ng hakbang na iyon ang owner ng core-config/ sa user ID ng container, kaya asahan mong gagamitin mo ang sudo kapag ine-edit ang file pagkatapos nito.
Simulan ang stack at suriin ito.
cd /opt/searxng
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080/Dapat ipakita ng docker compose ps ang dalawang container na nasa state na running. Dapat sumagot ang curl ng HTTP/1.1 200 OK. Kung walang sagot, basahin ang docker compose logs core dahil lalabas doon bilang parse error na may tinukoy na line ang YAML mistake sa settings.yml.
Ilagay ito sa likod ng nginx na may TLS
Ang container ay nakikinig lamang sa loopback, kaya nginx ang nagpapahintulot na maabot ito. Ito rin ang nagdaragdag ng transport layer security (TLS). Isulat ang /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.comIpinapakita ng nginx -t ang syntax is ok at test is successful bago ka mag-reload. Isusulat muli ng Certbot ang parehong file upang makinig sa 443 gamit ang certificate, at magdaragdag ito ng redirect mula sa port 80. Dapat nakaturo na sa server na ito ang DNS record para sa search.example.com, dahil pinatutunayan ng certificate authority ang pagmamay-ari sa pamamagitan ng pagkuha ng file gamit ang HTTP. Makikita ang kumpletong walkthrough, kasama ang renewal, sa gabay sa Certbot at nginx para sa Ubuntu 24.04.
Hindi palamuti lamang ang dalawang forwarding header. Kung wala ang X-Forwarded-For at X-Real-IP, dala ng bawat request na dumarating sa SearXNG ang address ng proxy. Dahil dito, nakikita ng rate limiter na iisang client ang gumagawa ng lahat ng traffic at hindi nito matukoy ang pagkakaiba ng mga bisita.
Bakit kailangan ng mga script at agent ng JSON search API
Sa json gamit ang formats, nagbabalik ng structured data ang parehong endpoint na nagre-render ng page.
curl -s 'http://127.0.0.1:8080/search?q=wireguard+mtu&format=json' \
| jq -r '.results[0:5][] | .url'Makakakuha ka ng object na may results array. Bawat entry ay naglalaman ng url, title, content, at ng engine na nagbigay nito, kasama ang answers, infoboxes, at suggestions. Sapat na ito para gamitin bilang input ng summariser, link checker, o research loop. Mas malaking hakbang ang pagpapasa ng mga resultang ito sa isang language model kaysa sa unang tingin, dahil untrusted text ang search results at maaaring may sarili itong mga instruction. Detalyadong ipinapakita ito ng pagkonekta ng AI agent sa iyong SearXNG instance.
Mahalaga ito sa anumang agent-based na workflow. May training cutoff ang isang language model, kaya kailangan nito ng live search para makasagot sa mga tanong tungkol sa kasalukuyang kalagayan. Naniningil ang commercial search API sa bawat query at mahigpit ang rate limit nito. Isang container lang sa server na binabayaran mo na ang gastos ng local instance, at hindi lumalabas dito ang mga query. Kung nagkokonekta ka ng mga tool sa isang model, pareho ang batayan sa pagpapatakbo ng MCP servers sa isang VPS, kung saan kadalasang search tool ang unang idinadagdag.
May dalawang panuntunan sa paggamit ng API. Panatilihing private ang instance. I-bind ang API side sa loopback address o sa private network, at payagan lamang ang sarili mong hosts na maka-access dito. Pareho ito sa setup na kailangan ng self-hosted location tracker para sa endpoint na pinapadalhan ng phone mo ng lokasyon nito. Pagkatapos, mag-query nang maingat. Ipinapasa ng SearXNG ang request mo sa aktuwal na search engines, kaya kapag nagpapatakbo ang script ng 100 query bawat segundo, hinihiling nitong i-block ng Google ang server mo.
Ang limiter at ang mga pagbabago para sa public instance
Ang limiter ang bot defence ng SearXNG. Sinusubaybayan nito ang request headers, mga address, at request rate, at ibinabagsak nito ang traffic na mukhang automated. Kailangan nito ng Valkey para mag-imbak ng state, kaya kasama ito sa Compose file.
Sa private instance, panatilihing naka-limiter: false. Awtomatikong traffic ang sarili mong scripts, kaya iba-block ng limiter ang mismong JSON calls na ginawa mo ang instance para rito. Sa reverse proxy dapat gawin ang access control: isang allow at deny pair sa nginx location, HTTP basic authentication, o firewall na tumatanggap lamang ng access mula sa iba mong server. Kung kailangan mong i-access ang private instance mula sa laptop na lumilipat-lipat ng network, ilagay sa harap nito ang isang v3 onion address bilang ikaapat na opsyon, dahil kumokonekta ang tor sa parehong loopback port nang walang inilalantad na bago sa internet.
Kung ipo-publish mo ang instance para sa ibang tao, i-on ang parehong switch.
server:
limiter: true
public_instance: trueNasa core-config/limiter.toml ang mas detalyadong control. Binabasa ito ng container mula sa /etc/searxng/limiter.toml. Isulat lamang ang mga key na gusto mong baguhin. Kapag nasa likod ito ng proxy, dapat mong ideklara ang proxy; kung hindi, ituturing ng limiter na ang address ng nginx ang abusive client.
[botdetection]
trusted_proxies = [
'127.0.0.0/8',
'::1',
]
[botdetection.ip_limit]
link_token = trueDahil sa link_token = true, magpapalabas ang SearXNG ng token na makukuha lamang ng totoong browser session. Napipigilan nito ang karamihan sa mga simpleng scraper. Asahan mong aatake ang mga ito sa public instance sa loob ng ilang araw. Asahan din ang mga engine error, dahil habang mas maraming traffic ang ipinapasa mo, mas maagang magsisimulang magbalik ang upstream engine ng CAPTCHA sa address ng server mo. Patuloy na gawain ang pagpapatakbo ng public SearXNG instance. Hindi ganoon ang private instance, kaya kabilang ito sa karamihan ng maiikling listahan ng mga sulit i-self-host sa 2026. Hindi rin infrastructure ang bawat entry sa mga listahang iyon: ang pagbuo muli ng Jellyfin library bilang isang 90s rental store na maaaring lakarin ay parehong isang container sa likod ng parehong nginx block, ngunit nakatuon sa isang gabi at hindi sa isang workflow.
Bakit walang ibinabalik ang mga search
Buksan ang /stats sa iyong instance. Inililista nito ang bawat engine kasama ang error rate at response time nito. Ito ang unang dapat suriin kapag kakaunti ang lumalabas na resulta.
Ang engine na may error na "Access denied" o "CAPTCHA" ay nag-block sa address ng iyong server. Karaniwan ito sa mga address na nasa data centre range, dahil ipinapalagay ng mga search engine na ginagamit ang mga ito ng mga scraper. Pagkatapos, sinasuspinde ng SearXNG ang engine na nagfa-fail sa loob ng isang panahon sa halip na subukan itong muli. Dahil dito, tahimik na nawawala sa iyong mga resulta ang isang naka-block na engine. I-disable ito sa settings.yml o tanggapin ang pagkawala nito. Hindi lamang ang dalawang opsyong iyon ang maaari mong gawin, dahil may ilang CAPTCHA block na may solusyong nananatili kahit mag-restart. Patuloy pa ring sasagot ang mga natitirang engine. Ang 429 ang hindi tiyak na kaso, dahil maaaring mula ito sa sarili mong limiter o sa upstream engine na tumatanggi sa iyong server. Ipinapakita ng log line kung alin sa dalawang iyon ang nangyayari bago ka magsimulang magbago ng mga setting.
Kung sabay-sabay na nagfa-fail ang lahat ng engine, walang gumaganang outbound name resolution ang container o wala itong route papunta sa internet. Subukan ito mula sa loob ng container.
docker compose exec core wget -qO- https://duckduckgo.com > /dev/null && echo okWalang magsasabi sa iyo sa server kapag nagsimulang mag-fail ang check na iyon. Kaya patakbuhin ito mula sa cron at hayaang magpadala ng alert sa iyong phone mula sa sarili mong ntfy server kapag may failure, sa halip na hintaying mapansin mong kakaunti na ang mga resulta.
FAQ
Ginagawa ba ng SearXNG na anonymous ang mga paghahanap ko?
Itinatago nito ang pagkakakilanlan mo sa mga search engine na tinatanungan nito, dahil server mo ang nakikita nilang gumagawa ng request sa halip na browser mo. Hindi nito itinatago ang query sa server mo, at hindi rin nito itinatago ang server mo sa mga search engine. Sa isang instance na iisang user lang ang gumagamit, sa iyo nagmumula ang lahat ng traffic mula sa address na iyon, kaya ang address mismo ang nagiging identifier. Pinoprotektahan ng TLS certificate ang traffic sa pagitan ng browser mo at ng instance mo. Ang mga limitasyon nito laban sa ISP mo, operator ng public instance, at mismong mga search engine ay ipinaliwanag sa kung ano talaga ang itinatago ng SearXNG.
Bakit nagbabalik ng 403 Forbidden ang isang JSON request?
May dalawang sanhi, at parehong configuration ang problema. Maaaring wala ang json sa listahan ng formats sa ilalim ng search: sa settings.yml, na siyang default na configuration, o naka-on ang limiter at na-classify nito bilang bot ang script mo. Idagdag muna ang format, mag-restart gamit ang docker compose restart core, pagkatapos ay subukan ulit. Kung hindi pa rin gumana, itakda ang limiter: false at kontrolin ang access sa reverse proxy sa halip.
Kailangan ko ba ang Valkey container kung naka-off ang limiter?
Iwan itong tumatakbo. Gumagana ang SearXNG nang wala ito, pero hindi ma-i-on ang limiter sa hinaharap kung wala ito, at naglalaman din ito ng iba pang panandaliang state. Maliit ang container at cached data lang ang iniimbak nito, kaya kakaunti lang ang matitipid sa pag-alis nito at mawawala naman ang opsyon na gamitin ito.
Paano ko ia-update ang SearXNG?
Patakbuhin ang docker compose pull at pagkatapos ay docker compose up -d sa /opt/searxng. Gagawa muli ang Compose ng anumang container na nagbago ang image at hindi gagalawin ang core-config/ directory mo, kaya mananatili ang settings.yml. Dahil pinagsasama ng use_default_settings: true ang mga key mo sa mga default na inilalabas kasama ng software, dumarating ang mga option na idinagdag upstream na may maayos na value sa halip na masira ang file.
Maaari bang magbahagi ng isang instance ang ilang tao?
Oo, at ito ang sitwasyong dapat mong i-on ang limiter at itakda ang public_instance: true. Naka-store ang preferences sa sariling browser ng bawat visitor, kaya walang accounts na kailangang i-manage. I-monitor ang /stats sa loob ng isang linggo matapos itong gawing available, dahil nagsisimulang mag-reject ang upstream search engine sa server mo bago mo pa mapansin na may nawawalang resulta.