Kendi SearXNG Arama Motorunuzu Kurma Rehberi

Ne inşa ediyorsunuz

SearXNG'yi kendi sunucunuzda barındırmak, kendi sunucunuz üzerinde çalışan özel bir arama motoruna sahip olmanızı sağlar. SearXNG bir meta arama motorudur: sorgunuzu alır, Google, Bing, DuckDuckGo ve Wikipedia gibi diğer arama motorlarına iletir ve ardından gelen sonuçları tek bir sonuç sayfasında birleştirir. Sorgunuzu tutan tek makine sizin makineniz olduğu için herhangi bir profil oluşturulmaz ve izleme çerezi ayarlanmaz. Eğer sadece Searx olarak adlandırılan eski kılavuzlara denk geldiyseniz, bu kılavuzun temel aldığı proje odur; ancak o proje 2023 yılından beri herhangi bir commit almamıştır, bu yüzden birini takip etmeden önce her ikisinin durumunu kontrol edin.

Kullanılan yığın küçüktür. İki container, bir ayar dosyası ve bir reverse proxy. Her self-hosted servis için geçerli olmayan bir şekilde, küçük bir VPS üzerinde rahatlıkla çalışabilir: PhotoPrism ile Immich karşılaştırması içerisinde ele alınan fotoğraf kütüphaneleri, RAM kullanım alt sınırlarını web uygulamasından ziyade indeksleyici üzerinden belirler. Asıl karar, örneğin özel mi (sadece sizin ve kendi betiklerinizin erişebildiği) yoksa genel mi (internetteki herkesin sorgu yapabildiği) olacağıdır. Bu seçim güvenlik ayarlarını değiştireceğinden, herhangi bir işlem yapmadan önce kararınızı verin. Varsayılan yanıt özeldir.

Bunu çalıştırmanın ikinci bir nedeni daha vardır. Bir SearXNG örneği JSON ile iletişim kurar; bu sayede yazdığınız herhangi bir betik veya yapay zeka ajanı, anahtar gerektirmeyen, sorgu başına ücretlendirmesi olmayan ve kota uyarısı göndermeyen, tamamen size ait bir arama API'sine sahip olur.

Docker Compose ile SearXNG kurulumu

Proje, bir container imajı ve bir Compose dosyası yayınlamaktadır. Her ikisini de Docker Engine ve Compose eklentisi halihazırda kurulu olan temiz bir Ubuntu 24.04 sunucusuna çekin. Docker sizin için yeniyse, VPS üzerinde Docker Compose temelleri ile başlayıp geri dönün.

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

Compose dosyası iki servis tanımlar. core, SearXNG'nin kendisidir; valkey ise hız sınırlaması ve kısa süreli durum bilgisi için kullanılan bellek içi bir veri deposudur. Bu servis, ./core-config/ dizinini container içindeki /etc/searxng/ yoluna bağlar; böylece yapılandırdığınız her şey ana makinedeki bu tek dizinde barınır.

Şimdi .env dosyasını düzenleyin. Sunulan örnekteki her satır yorum satırı halindedir; bu nedenle container her adreste 8080 numaralı portta başlar. Yorum işaretlerini kaldırın ve şu üç ayarı yapılandırın.

SEARXNG_VERSION=latest
SEARXNG_HOST=127.0.0.1
SEARXNG_PORT=8080

SEARXNG_HOST=127.0.0.1 önemli olan ayardır. Bu ayar, yayınlanan portu [::]:8080:8080 yerine 127.0.0.1:8080:8080 yapar; böylece container yalnızca loopback adresi üzerinden yanıt verir ve internet üzerinden doğrudan erişilemez. Bu adımı atlarsanız, yayınlanan bir Docker portu güvenlik duvarı kurallarınızın önüne eklendiği için container başladığı anda dış dünyaya açılır. Bu tuzağı bütünüyle okumakta fayda vardır: yayınlanan Docker portları ufw'yi atlatır.

SEARXNG_VERSION=latest, öğrenme aşamasında uygundur. Önem verdiğiniz bir sunucuda ise etiketi sabitleyin. Temmuz 2026 itibarıyla sürüm etiketleri tarih bazlıdır ve 2026.3.25-541c6c3cb gibi görünür; böylece sabitlenmiş bir dağıtım, kayıt defterindeki değişikliklerle değil, sizin karar verdiğiniz zamanda güncellenir. Aynı disiplin, sunucudaki diğer uzun ömürlü servisler için de geçerlidir; bu yüzden kendi kendine barındırılan bir RustDesk relay servisi de imaj etiketlerini sabitler: uzak erişim servisine yapılacak denetimsiz bir güncelleme, en kötü anda sorun çıkarabilir.

settings.yml: önemli kısımlar

İlk başlatmadan önce core-config/settings.yml dosyasını oluşturun. use_default_settings: true, SearXNG'ye kendi varsayılan ayarlarını yüklemesini ve ardından yalnızca sizin yazdığınız anahtarları uygulamasını söyler; böylece dosyanız kısa kalır ve yeni seçenekler ekleyen yükseltmelerden etkilenmez.

Değer doğrudan dosyaya yazılacağı için önce gizli anahtarı oluşturun.

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, oturum ve token verilerini imzalar. Yazılım ile gelen varsayılan değer ultrasecretkey dizisidir ve bunu olduğu gibi bırakmak, bu varsayılanı bilen herkesin token'ları taklit edebileceği anlamına gelir. Bir kez değiştirin ve sonra dokunmayın: daha sonra değiştirmek, kaydedilmiş tüm tercihlerin silinmesine neden olur.

base_url, sonunda eğik çizgi (/) bulunan genel HTTPS adresi olmalıdır. Bu, SearXNG'nin oluşturduğu bağlantıların içine yazdığı adrestir. Bunu localhost olarak bırakırsanız, uzak bir tarayıcıdaki "sonraki sayfa" bağlantısı okuyucunun kendi makinesini işaret eder ve başarısız olur.

formats, web uç noktasının hangi çıktı türlerini üreteceğine karar verir. json varsayılan listede yer almaz, bu nedenle siz ekleyene kadar JSON istekleri 403 hatası döndürür. image_proxy: true, sonuç küçük resimlerini sunucunuz üzerinden yönlendirir; böylece bu resimleri barındıran siteler ziyaretçilerinizin adreslerini asla görmez.

valkey.url, valkey ana bilgisayar adını kullanır çünkü bu, Compose dosyasındaki servis adıdır ve Compose her iki container'ı da servis adlarının çözümlenebildiği tek bir ağa yerleştirir. Bunu localhost adresine yönlendirirseniz sınırlayıcı başarısız olur, çünkü core container'ı içinde localhost sadece o container'ın kendisidir.

Gizli anahtar düz bir dosyada durur, bu nedenle dosyadan ziyade bulunduğu dizini koruyun. chmod 750 /opt/searxng, diğer ana bilgisayar kullanıcılarını dışarıda tutar. core-config/settings.yml dizinini 600 moduna kadar sıkılaştırmayın: container kendi ayrıcalıksız kullanıcısı olarak çalışır ve okuyamadığı bir dosya SearXNG'nin hiç başlamamasına neden olur.

Stack'i başlatın ve kontrol edin.

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

docker compose ps, her iki container'ı da running durumunda göstermelidir. curl, HTTP/1.1 200 OK yanıtını vermelidir. Eğer hiçbir yanıt vermezse docker compose logs core dosyasını okuyun, çünkü settings.yml içindeki bir YAML hatası orada satır numarasını belirten bir ayrıştırma hatası (parse error) olarak görünür.

Nginx arkasına TLS ile yerleştirme

Konteyner yalnızca loopback üzerinde dinleme yapar, bu nedenle erişilebilirliği sağlayan ve taşıma katmanı güvenliğini (TLS) ekleyen Nginx'tir. /etc/nginx/sites-available/searxng dosyasını oluşturun.

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 komutu, yeniden yükleme yapmadan önce syntax is ok ve test is successful çıktılarını verir. Certbot, aynı dosyayı 443 numaralı portta bir sertifika ile dinleyecek şekilde yeniden yazar ve 80 numaralı porttan yönlendirme ekler. search.example.com için DNS kaydı halihazırda bu sunucuyu işaret etmelidir, çünkü sertifika yetkilisi sahipliği HTTP üzerinden bir dosya çekerek doğrular. Yenileme dahil tam izlenecek yol Ubuntu 24.04 için Certbot ve Nginx rehberi içindedir.

İki yönlendirme başlığı süsleme değildir. X-Forwarded-For ve X-Real-IP olmadan, SearXNG'ye ulaşan her istek proxy adresini taşır; bu durumda hız sınırlayıcı (rate limiter) tüm trafiği tek bir istemci yapıyormuş gibi görür ve ziyaretçileri birbirinden ayıramaz.

Betiklerin ve aracıların neden JSON arama API'sine ihtiyaç duyduğu

json içindeki formats ile, sayfayı oluşturan aynı uç nokta yapılandırılmış veri döndürür.

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

Her bir girdinin url, title, content ve onu sağlayan motorun yanı sıra answers, infoboxes ve suggestions bilgilerini taşıdığı bir results dizisine sahip bir nesne elde edersiniz. Bu, bir özetleyiciyi, bağlantı denetleyicisini veya araştırma döngüsünü beslemek için yeterlidir. Bu sonuçları bir dil modeline aktarmak göründüğünden daha büyük bir adımdır; çünkü arama sonuçları, kendi talimatlarını taşıyabilen güvenilmeyen metinlerdir ve bir yapay zeka aracısını SearXNG örneğinize yönlendirmek konusu bunu detaylıca ele alır.

Bu durum, aracı formundaki her şey için önemlidir. Bir dil modelinin eğitim kesim tarihi vardır, bu nedenle güncel soruları yanıtlamak için canlı aramaya ihtiyaç duyar; ticari arama API'leri ise sorgu başına ücret alır ve katı hız sınırları uygular. Yerel bir örnek, halihazırda ödemesini yaptığınız bir sunucudaki tek bir container maliyetine sahiptir ve sorgular asla bu sunucudan dışarı çıkmaz. Eğer araçları bir modele bağlıyorsanız, aynı mantık bir VPS üzerinde MCP sunucuları çalıştırmak için de geçerlidir; burada bir arama aracı genellikle insanların eklediği ilk araçtır.

API kullanımı için iki kural vardır. Örneği gizli tutun; bu nedenle API tarafını loopback adresine veya özel bir ağa bağlayın ve yalnızca kendi ana bilgisayarlarınızın erişmesine izin verin. Ardından sorguları nazikçe yapın. SearXNG isteğinizi gerçek arama motorlarına iletir, bu yüzden saniyede yüzlerce sorgu çalıştıran bir betik, Google'dan sunucunuzu engellemesini istemekle eşdeğerdir.

Sınırlayıcı ve herkese açık bir örnek için değişenler

Sınırlayıcı, SearXNG'nin bot savunma mekanizmasıdır. İstek başlıklarını, adresleri ve istek oranlarını izler; otomatik olduğu anlaşılan trafiği reddeder. Bu durum bilgisini tutmak için Valkey'e ihtiyaç duyar, Compose dosyasının onu içerme nedeni budur.

Özel bir örnekte limiter: false ayarını koruyun. Kendi betikleriniz tanım gereği otomatik trafiktir; bu nedenle sınırlayıcı, örneği tam olarak hangi JSON çağrıları için oluşturduysanız onları engelleyecektir. Erişim kontrolü bunun yerine reverse proxy'nin görevidir: nginx location dosyasında bir allow ve deny çifti, HTTP temel kimlik doğrulaması veya yalnızca diğer sunucularınıza izin veren bir güvenlik duvarı kullanın. Özel bir örneğe ağlar arasında geçiş yapan bir dizüstü bilgisayardan erişmeniz gerekiyorsa, önüne bir v3 onion adresi koymak dördüncü bir seçenektir; çünkü tor, internete yeni bir şey açmadan aynı loopback portuna bağlanır.

Örneği başkalarının kullanımına açacaksanız, her iki anahtarı da etkinleştirin.

server:
  limiter: true
  public_instance: true

Daha hassas kontrol, container'ın /etc/searxng/limiter.toml konumunda okuduğu core-config/limiter.toml dosyasında yer alır. Yalnızca değiştirmek istediğiniz anahtarları yazın. Bir proxy arkasında, proxy'yi tanımlamanız gerekir; aksi takdirde sınırlayıcı, nginx adresinizi tek bir kötü niyetli istemci olarak algılar.

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

[botdetection.ip_limit]
link_token = true

link_token = true, SearXNG'nin yalnızca gerçek bir tarayıcı oturumunun getireceği bir token yayınlamasını sağlar; bu da basit kazıyıcıların çoğunu durdurur. Herkese açık bir örneğin birkaç gün içinde bu tür botları çekeceğini varsayın. Motor hataları da bekleyin; çünkü ne kadar çok trafik yönlendirirseniz, yukarı akış motorları sunucu adresinize o kadar çabuk CAPTCHA döndürmeye başlar. Herkese açık bir SearXNG örneği sürekli devam eden bir iştir. Özel bir örnek ise öyle değildir; bu yüzden 2026 yılında kendi kendine barındırmaya değer şeyler listelerinin çoğunda yer alır. Bu listelerdeki her girdi altyapı ile ilgili değildir: bir Jellyfin kütüphanesini 90'ların gezilebilir bir kiralık video dükkanı gibi yeniden oluşturmak, aynı nginx bloğunun arkasındaki aynı container'dır; ancak bir iş akışından ziyade bir akşam keyfine yöneliktir.

Aramalar neden sonuç döndürmüyor

Örneğiniz üzerinde /stats dosyasını açın. Bu dosya, hata oranı ve yanıt süresiyle birlikte her motoru listeler; sonuçların yetersiz olduğunu hissettiğinizde bakmanız gereken ilk yer burasıdır.

"Access denied" veya "CAPTCHA" hatalarıyla görüntülenen bir engine, sunucu adresinizi engellemiştir. Bu durum, data center aralıklarındaki adreslerde yaygındır; çünkü arama motorları bu adreslerin scraper'lara ait olduğunu varsayar. SearXNG, başarısız olan engine'i yeniden denemek yerine belirli bir süre askıya alır. Bu nedenle engellenen bir engine, sonuçlarınızdan sessizce çıkar. Engine'i settings.yml içinde devre dışı bırakın veya bu kaybı kabul edin. Ancak yalnızca bu iki seçenek yoktur; çünkü bazı CAPTCHA engellemeleri yeniden başlatma sonrasında da geçerli kalan bir düzeltmeyle giderilebilir. Kalan engine'ler yanıt vermeye devam eder. 429, belirsiz olan durumdur; çünkü bu yanıt kendi limiter'ınızdan veya upstream engine'in sunucunuzu reddetmesinden kaynaklanabilir. Ayarları değiştirmeye başlamadan önce log satırı bu iki durumdan hangisiyle karşı karşıya olduğunuzu gösterir.

Tüm motorlar aynı anda başarısız oluyorsa, container'ın çalışan bir dışa dönük isim çözümlemesi veya internete giden bir rotası yoktur. Bunu container içinden test edin.

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

Sunucudaki hiçbir şey bu kontrolün ne zaman başarısız olmaya başladığını size bildirmez. Bu yüzden testi cron üzerinden çalıştırın ve sonuçların azaldığını fark etmeyi beklemeden, bir hata durumunda kendi ntfy sunucunuz üzerinden telefonunuza bir uyarı gönderilmesini sağlayın.

FAQ

SearXNG aramalarımı anonim hale getirir mi?

Sorgu gönderdiğiniz arama motorlarından kimliğinizi gizler; çünkü bu motorlar isteği tarayıcınız yerine sunucunuzun yaptığını görür. Sorguyu sunucunuzdan gizlemez ve sunucunuzu da onlardan gizlemez. Tek kullanıcılı bir örnekte (instance) o adresten gelen tüm trafik size aittir, dolayısıyla adresin kendisi bir tanımlayıcı haline gelir. Tarayıcınız ile örneğiniz arasındaki trafik TLS sertifikası ile korunur. Bunun sizi ISS'nize, herkese açık bir örneğin operatörüne ve arama motorlarının kendisine karşı nasıl bir konumda bıraktığı SearXNG'nin aslında neyi gizlediği bölümünde açıklanmıştır.

JSON isteği neden 403 Forbidden hatası döndürüyor?

İki nedeni vardır ve her ikisi de yapılandırma ile ilgilidir. Ya json, settings.yml içindeki search: altında bulunan formats listesinde eksiktir (varsayılan durum budur) ya da sınırlayıcı (limiter) açıktır ve betiğinizi bot olarak sınıflandırmıştır. Önce formatı ekleyin, docker compose restart core ile yeniden başlatın ve tekrar deneyin. Hata devam ederse limiter: false ayarını yapın ve erişimi reverse proxy üzerinden kontrol edin.

Sınırlayıcıyı kapalı tutarsam Valkey container'ına ihtiyacım var mı?

Çalışır durumda bırakın. SearXNG onsuz çalışır ancak sınırlayıcı daha sonra onsuz açılamaz; ayrıca diğer kısa ömürlü durum bilgilerini de tutar. Container küçüktür ve yalnızca önbelleğe alınmış verileri saklar, bu nedenle kaldırmak çok az yer kazandırır ancak seçeneklerinizi kısıtlar.

SearXNG'yi nasıl güncellerim?

/opt/searxng dizini içerisinde önce docker compose pull, ardından docker compose up -d komutlarını çalıştırın. Compose, imajı değişen her container'ı yeniden oluşturur ve core-config/ dizininize dokunmaz, bu sayede settings.yml korunur. use_default_settings: true, anahtarlarınızı varsayılan değerler üzerinde birleştirdiği için, yukarı akışta (upstream) eklenen seçenekler dosyayı bozmak yerine mantıklı değerlerle gelir.

Birden fazla kişi tek bir örneği paylaşabilir mi?

Evet, sınırlayıcıyı açıp public_instance: true ayarını yaptığınız durum budur. Tercihler her ziyaretçinin kendi tarayıcısında saklandığı için yönetilecek bir hesap yoktur. Erişime açtıktan sonra bir hafta boyunca /stats kayıtlarını izleyin; çünkü yukarı akış motorları, sonuçların eksik olduğunu fark etmenizden çok önce sunucunuzu reddetmeye başlayabilir.