Kubernetes (Helm)

Bir kümede çalıştırıyorsanız nivq'nun resmi bir Helm chart'ı var. Chart yalnızca uygulamayı kurar — PostgreSQL'i (pgvector eklentili) ve Redis/Valkey'i siz getirirsiniz; chart veri depolarını paketlemez. Yönetilen servisler de, küme içinde çalıştırdıklarınız da olur.

Başlamadan önce

• kubectl'in yönlendirildiği bir Kubernetes kümesi (1.27+) ve Helm 3.
• Erişilebilir bir PostgreSQL 16+ (pgvector eklentili) ve bir Redis 7+ / Valkey.
• Bir registry token'ı (ya da internet çıkışı olmayan kümeler için çevrimdışı imaj tarball'ı).
• Helm chart'ına erişim — oci://ghcr.io/nivorbit/charts/nivq adresinde özel bir OCI artefaktı olarak yayınlanır ve imajla aynı kimlik bilgilerini kullanır.

1. Pull secret'ı oluşturun

İmaj özel olduğu için kümenin onu çekmek üzere kimlik bilgilerine ihtiyacı var. Kuracağınız namespace'te bir pull secret oluşturun:

kubectl create secret docker-registry ghcr-pull \
  --docker-server=ghcr.io \
  --docker-username=<kullanıcı-adı> \
  --docker-password=<token>

Token'ınız yoksa Nivorbit ekibinden isteyin ya da [email protected]'a yazın. Değerler dosyasında bu secret'a imagePullSecrets ile referans vereceksiniz (3. adım).

2. Değerler dosyasını yazın

Yapılandırmanız nivq-values.yaml'a girer. Aşağıdakiler en sık kullanılan alanlar; her birinin chart'ta makul bir varsayılanı var, yani yalnızca size gerekenleri yazarsınız.

replicaCount: 2

image:
  repository: ghcr.io/nivorbit/images/nivq
  tag: "1.4.0"            # üretimde gerçek bir sürüme sabitleyin
imagePullSecrets:
  - name: ghcr-pull

# --- Veri depoları (sizin getirdikleriniz) ---
postgres:
  url: jdbc:postgresql://my-postgres:5432/nivqdb
  username: nivq
  password: "guclu-bir-deger"         # → Kubernetes Secret
redis:
  host: my-redis
  port: 6379

# --- Güvenlik (zorunlu) ---
# 32 baytlık base64 anahtar (openssl rand -base64 32). Kaybetmek saklanan
# kimlik bilgilerini kurtarılamaz yapar — yedekleyin. Boşsa chart kurulumu reddeder.
encryptionKeyV1: "buraya-base64-32-bayt"

# --- Platform-yönetimli LLM ---
platformLlm:
  provider: anthropic
  model: claude-haiku-4-5-20251001
  apiKey: "sk-..."                    # → Secret
  # İsteğe bağlı öz-öğrenme embedding'leri — ya üçü birden ya hiçbiri (bkz. Yapılandırma).
  embeddingProvider: ""
  embeddingModel: ""
  embeddingApiKey: ""

# --- Kimlik ---
oauth:
  google:
    clientId: "..."
    clientSecret: "..."               # → Secret

# --- Genel URL'ler (tarayıcıdan erişilen) ---
urls:
  backend: https://api.example.com
  frontend: https://app.example.com

# --- Lisanslama ---
licensing:
  # İsteğe bağlı: pod VALID açılsın diye lisansı tohumlayın. Boş bırakıp rollout sonrası etkinleştirebilirsiniz.
  seedLicense: ""

# --- Ingress (isteğe bağlı) ---
ingress:
  enabled: true
  className: nginx
  host: api.example.com
  tls:
    - secretName: nivq-tls
      hosts: [api.example.com]

# --- Web istemcisi (tarayıcı arayüzü) ---
# Varsayılan olarak dağıtılır. API URL'i urls.backend'den alınır; urls.frontend'de servis edin.
web:
  enabled: true
  ingress:
    enabled: true
    className: nginx
    host: app.example.com               # urls.frontend ile eşleşmeli
    tls:
      - secretName: nivq-web-tls
        hosts: [app.example.com]

Değer olarak sunulmayan her şeyi extraEnv ile ({name, value} listesi) Yapılandırma'daki değişken adlarıyla geçirebilirsiniz.

3. Kurun

Chart registry'sine giriş yapın (imajla aynı kimlik bilgileri), sonra sürümü sabitleyerek doğrudan OCI'dan kurun:

echo "<token>" | helm registry login ghcr.io -u <kullanıcı-adı> --password-stdin

helm install nivq oci://ghcr.io/nivorbit/charts/nivq --version 0.2.4 \
  -n nivq --create-namespace -f nivq-values.yaml

Bu; bir Deployment, bir Service (8080'de ClusterIP), yapılandırma için bir ConfigMap ile bir Secret ve — etkinse — bir Ingress oluşturur. web.enabled ile (varsayılan) ayrıca web istemcisini de kendi Deployment, Service ve Ingress'i olarak dağıtır; açılışta urls.backend'den yapılandırılır — ayrı bir build yok. Uygulama sizin için üretim modunda çalışır — yapılandıracak bir şey yoktur.

Web istemcisini tam olarak urls.frontend'de servis edin: API, OIDC redirect URI'sini <urls.frontend>/auth/callback olarak otomatik kaydeder, dolayısıyla web ingress.host bununla eşleşmeli. Tüm resim için bkz. Web istemcisi.

4. Rollout'u izleyin

kubectl -n nivq rollout status deploy/nivq

Helm, kurulumdan sonra sürümünüze özel kesin lisans komutları dahil sonraki-adım notlarını basar.

5. Lisansı etkinleştirin

Lisansı tohumladıysanız (licensing.seedLicense), nivq VALID açılır — hazırsınız. Aksi halde activation-pending açılır; bir kez etkinleştirin:

kubectl -n nivq port-forward deploy/nivq 8080:8080

# başka bir kabukta
curl http://localhost:8080/v1/license/fingerprint     # → NIVQ-FP-...
curl -F "[email protected]" http://localhost:8080/v1/license/upload

Alternatif olarak licensing.seedLicense'ı ayarlayıp helm upgrade çalıştırın. Tam yaşam döngüsü Lisanslama ve etkinleştirme'de.

6. Dışarı açın

Service varsayılan olarak ClusterIP'tir. En kolay yol chart'ın yerleşik ingress'i (yukarıda): ingress.enabled: true, controller'ınızın className'i, genel host ve bir tls secret'ı. TLS'i ingress'te sonlandırın ve urls.backend / urls.frontend'in genel HTTPS adresleri olduğundan emin olun — OAuth yönlendirmeleri ve bağlantılar buna göre çözülür.

Ölçeklenme ve yükseltme

• replicaCount ile ölçekleyin (ya da kubectl -n nivq scale deploy/nivq --replicas=N). Her replika aynı sunucu parmak izine çözülür, bu yüzden ölçeklenme, rolling update ve yeniden çizelgeleme lisansı ekstra ayar olmadan geçerli tutar.
• Yeni bir sürüme yükseltin: helm upgrade nivq oci://ghcr.io/nivorbit/charts/nivq --version 0.2.4 -n nivq -f nivq-values.yaml. Yapılandırma ya da secret değişiklikleri pod'ları otomatik yeniler.

Yedekleme, TLS ve gözlemlenebilirlik için Üretim sertleştirme'ye bakın.