2026'da Typesense'i Self-Host Etme: API Anahtarları, Koleksiyonlar ve Yedekler

En kısa Typesense demosu, bir işlemin 8108 portunu dinlediğini kanıtlar. Production ortamı ise daha güçlü kanıtlar gerektirir. Container değiştirildikten sonra bile şu senaryoyu başarıyla tamamlamalıdır: bir koleksiyon şeması tanımlamak, örnek belgeleri içe aktarmak, typo search, facet ve filter işlemlerini çalıştırmak, ardından health endpoint'ini test etmek.

Typesense, net bir amaç için devreye alınır: anlaşılır bir HTTP API'ye sahip anlık arama motoru. En yaygın deployment tuzağı, komutun --data-dir seçeneğini atlaması veya health check'lerin yanlış path'e yönelmesidir. Bu nedenle public URL yönetimi ve kalıcı state, image başlangıcı kadar dikkatle ele alınmalıdır.

Typesense'in sahip olduğu yetkiyi azaltın

Uygulamaya özgü güvenlik riski, bootstrap admin API anahtarını browser koduna gömmektir. Operasyonel çözüm, bootstrap administrator anahtarını hiçbir zaman browser'a göndermemek ve public client'lar için kapsamı sınırlandırılmış search key'ler oluşturmaktır. Bootstrap işlemini kısıtlanmış bir route üzerinden tamamlayın ve geçici setup erişimini hemen ardından kaldırın.

TYPESENSE_API_KEY değerini Typesense içindeki rolüne göre ele alın: hassas değerleri Git dışında tutun, rotation etkilerini belgeleyin ve production ortamında hiçbir zaman public bir örnek kullanmayın. Typesense process'ine yalnızca belgelenmiş mount'ları ve dependency route'larını verin; host root ve Docker socket erişiminden kaçının. Başarısız authentication ve configuration hatalarını log'layın, ancak token'ları, connection string'lerini ve kullanıcı içeriğini redact edin.

Typesense'in production mimarisi

Typesense HTTP process'i 8108 portunu dinler; bu portu application network üzerinde tutun ve yalnızca platform route'unu public hale getirin. Local runtime gereksinimi, koleksiyonlar için disk ve aktif dataset için yeterli bellektir. Bunu image default'u olarak bırakmak yerine beklenen kapasiteyi, sahipliği ve failure mode'u belgeleyin.

Sınırı kısa bir contract olarak yazılı hale getirin: gereksinimin sahibi kim, hangi credential kullanılacak, kabul edilebilir timeout ne ve hata nasıl görünecek? Ardından şu transaction'ı çalıştırın: bir koleksiyon şeması tanımlayın, örnek belgeleri içe aktarın, typo search, facet ve filter işlemlerini çalıştırın, ardından health endpoint'ini test edin. Çalışma sırasında aktif index'ler için gereken RAM'i, bulk import boyutunu, disk kalıcılığını ve cluster replication trafiğini gözlemleyin; çünkü bu workload, boşta duran bir container'dan daha faydalı bir başlangıç boyutu sağlar.

İncelenmeye değer container ayarları

İlk container kolayca silinip yeniden oluşturulabilmelidir. Verileri writable layer dışında tutun, 8108 portunu yalnızca proxy'nin erişebileceği yerde bind edin ve configuration'ı runtime sırasında aktarın.

docker run -d \
  --name typesense \
  --restart unless-stopped \
  -p 127.0.0.1:8108:8108 \
  -v typesense-data:/data \
  -e TYPESENSE_API_KEY=replace-with-a-long-random-value \
  -e TYPESENSE_DATA_DIR=/data \
  typesense/typesense:latest

İlk testten sonra image sürümünü sabitleyin. Son restart mesajı yerine en erken startup hatasını okuyun, her mount'ı docker inspect ile doğrulayın ve bir koleksiyon şeması tanımlarken, örnek belgeleri içe aktarırken, typo search, facet ve filter işlemlerini çalıştırırken, ardından health endpoint'ini test ederken log'ları takip edin. Bu sıra, hatalı bir image komutunu dependency veya permission probleminden ayırır.

Typesense release gate'i

Typesense için release candidate, sabit bir senaryoyu tamamlayarak trafiği hak eder: bir koleksiyon şeması tanımlayın, örnek belgeleri içe aktarın, typo search, facet ve filter işlemlerini çalıştırın, ardından health endpoint'ini test edin. Bu senaryo için image digest'ini, secret olmayan etkin configuration'ı, public origin'i ve zaman damgalarını kaydedin. Test verileri silinebilir olmalı, ancak kullanıcıların izlediği aynı path'i çalıştıracak kadar gerçekçi olmalıdır.

Runtime'ı değiştirdikten sonra testi yeniden çalıştırın; ardından servisi data directory'den, cluster'lar içinse her node'un tutarlı snapshot'larından yeniden oluşturun. Recovery, koleksiyonlar, alias'lar, override'lar ve synonym'ler geri geldiğinde ve aynı query eşdeğer bir ranked result ürettiğinde başarılı kabul edilir. Aktif index'ler için gereken RAM'i, bulk import boyutunu, disk kalıcılığını ve cluster replication trafiğini önceki release ile karşılaştırın; promotion öncesinde anlamlı sapmaları araştırın.

Son olarak şu kontrollü hatayı çalıştırın: bu sınırla ilişkili kaynak veya format limitine yakın, zararsız bir input gönderin: komut --data-dir seçeneğini atlıyor veya health check'ler yanlış path'e yöneliyor. Typesense'in hatayı açıklayabildiğini, mevcut state'e zarar vermediğini ve geçerli koşul geri geldiğinde devam ettiğini doğrulayın. Redact edilmiş bir log alıntısını ve recovery süresini kaydedin. Bu kontroller birlikte yalnızca process uptime'ını değil, davranışı, kalıcılığı ve işletilebilirliği de kapsar.

HTTPS konusunda yanıltmadan Typesense'e route verin

Typesense için public boundary; tek bir canonical hostname, automatic TLS ve 8108 üzerinde tek bir internal target olmalıdır. HTTP API'yi route ederken peering port'larını private tutun; böylece client'lar servisin tanıdığı bir adrese geri döner.

Acceptance transaction başarısız olursa ilk hatayı sınıflandırın. DNS, certificate ve 502 problemleri TLS doğrulama kontrol listesine girer. “Komut --data-dir seçeneğini atlıyor veya health check'ler yanlış path'e yöneliyor” koşulu ise bir request Typesense'e başarıyla ulaştıktan sonra application tarafına aittir.

Riskli Typesense değişikliğini prova edin

Her deployment sonrasında Typesense smoke test'i olarak bir koleksiyon şeması tanımlayın, örnek belgeleri içe aktarın, typo search, facet ve filter işlemlerini çalıştırın, ardından health endpoint'ini test edin. Bu testin destekleyici metrikleri, aktif index'ler için gereken RAM, bulk import boyutu, disk kalıcılığı ve cluster replication trafiğidir; bu kaynaklar kullanıcı aksiyonunu yavaşlatacak bir noktaya yaklaştığında alert üretin.

Temel değişiklik riski, collection schema değişiklikleri ve snapshot'ların prova gerektirmesidir; çünkü image rollback'i bir data-format değişikliğini geri alamaz. Güvenli bir release, geri yüklenebilir bir snapshot ile başlar ve trafiği taşımadan önce tek yönlü state değişikliklerini doğrular. Komut --data-dir seçeneğini atladığında veya health check'ler yanlış path'e yöneldiğinde, configuration'ını ve ilk hatayı okuyabilmek için başarısız container'ı yeterince uzun süre koruyun.

Typesense'in değişimden sağ çıktığını kanıtlayın

İlk gerçek kayıt oluşturulmadan önce state'i listeleyin: data directory ve cluster'lar için her node'un tutarlı snapshot'ları. Bootstrap işleminden önce /data'yı mount edin, zararsız örnek veriler yazın ve bu path'in gerçekten kalıcı olduğunu kanıtlamak için container'ı değiştirin. Zararsız veriler yazarak, Typesense'i değiştirerek ve verileri yeniden okuyarak mount'ı doğrulayın.

Snapshot'lar hızlı rollback için değerlidir, ancak host veya volume ortadan kalktığında bağımsız bir backup gerekir. Pinned image ile boş bir environment'a restore edin ve koleksiyonların, alias'ların, override'ların ve synonym'lerin geri geldiğini; aynı query'nin eşdeğer bir ranked result ürettiğini doğrulayın. Bu iki recovery mekanizmasını birbirinden ayrı tutmak için kalıcı volume'ları ve snapshot'ları kullanın.

Dockup deployment'ı yine de bir Typesense acceptance testi gerektirir

Routing, certificate'lar, service replacement ve bağlı storage makul automation hedefleridir. Dockup bunları Typesense için yönetebilir ve ilgili managed database'i provision edebilir veya müşterinin kendi server'ındaki servislere bağlanabilir.

Ancak icat etmemesi gereken şey Typesense trust policy'sidir. Deployment sonrasında HTTP API'yi route ederken peering port'larını private tutun, şu sınırı uygulayın — bootstrap administrator anahtarını hiçbir zaman browser'a göndermeyin; public client'lar için kapsamı sınırlandırılmış search key'ler oluşturun — ve şu senaryonun sonucunu doğrulayın: bir koleksiyon şeması tanımlayın, örnek belgeleri içe aktarın, typo search, facet ve filter işlemlerini çalıştırın, ardından health endpoint'ini test edin. Sonuç, uygulamaya özgü bir acceptance testiyle desteklenen tek tıklamalı infrastructure'dır.

Sık sorulan sorular

Production deployment için Typesense neye ihtiyaç duyar?

Typesense container'ını 8108 portu üzerinden tek bir HTTPS origin'e route edin. Local runtime gereksinimi, koleksiyonlar için disk ve aktif dataset için yeterli bellektir. Bir koleksiyon şeması tanımlayamadığınız, örnek belgeleri içe aktaramadığınız, typo search, facet ve filter işlemlerini çalıştıramadığınız ve health endpoint'ini test edemediğiniz sürece Typesense'i hazır kabul etmeyin.

Hangi Typesense verileri backup'a dahil edilmelidir?

/data'yı kalıcı hale getirin ve data directory'yi; cluster'lar içinse her node'un tutarlı snapshot'larını aynı recovery manifest'ine dahil edin. Temiz bir Typesense restore'u yalnızca koleksiyonlar, alias'lar, override'lar ve synonym'ler geri geldiğinde ve aynı query eşdeğer bir ranked result ürettiğinde başarılı olur.

Reverse proxy arkasında Typesense HTTPS gerektirir mi?

Public Typesense origin'i için HTTPS kullanın ve 8108 portunu internal route üzerinde tutun. Typesense ayarını doğru uygulayın: HTTP API'yi route ederken peering port'larını private tutun. Typesense için HTTPS, credential'ları veya kullanıcı içeriğini transit sırasında korur ve origin'e duyarlı client davranışının tutarlı kalmasını sağlar.

Typesense yükseltmesi nasıl test edilmelidir?

Mevcut Typesense state'ini izole bir deployment'a restore edin, candidate sürümü uygulayın ve acceptance transaction'ını tekrarlayın. Collection schema değişiklikleri ve snapshot'lar prova gerektirdiğinden özellikle dikkatli olun; image rollback'i bir data-format değişikliğini geri alamaz. Data migration ve rollback sınırları anlaşılana kadar önceki Typesense image'ını saklayın.