Bare metal (JAR + systemd)

Politikanız bir konteyner motorunu dışlıyorsa, nivq; Java 25 çalışma zamanı bulunan bir Linux sunucusunda sade bir çalıştırılabilir JAR'ı olarak çalışır. Yönetilen PostgreSQL ('pgvector' eklentili) ve Redis/Valkey'i kendiniz getirirsiniz (bkz. Gereksinimler); nivq, systemd ile yönettiğiniz tek bir süreçtir. Varsayılan olarak üretim modunda çalışır — ayarlanacak bir profil ya da mod bayrağı yoktur.

1. Bir Java 25 çalışma zamanı kurun

Herhangi bir dağıtım uygundur; resmi imaj Eclipse Temurin kullanır.

# Debian/Ubuntu örneği — dağıtımınızdan ya da Adoptium'dan JDK/JRE 25 kurun
java -version    # → openjdk version "25"

2. JAR'ı indirin ve dizinleri hazırlayın

JAR, container imajıyla aynı registry'de: ghcr.io/nivorbit/jars/nivq. oras ile giriş yapıp çekin:

oras login ghcr.io -u <kullanıcı-adı> -p <token>
oras pull ghcr.io/nivorbit/jars/nivq:0.2.4        # → nivq-0.2.4.jar

Token'ınız yoksa Nivorbit ekibinden isteyin ya da [email protected]'a yazın. İnternete kapalıysanız JAR'ı dosya olarak alıp sunucuya kopyalayın; bu adımı atlayın.

Sonra bunun için özel bir kullanıcı ve bir yer oluşturun:

sudo useradd --system --home /opt/nivq --shell /usr/sbin/nologin nivq
sudo mkdir -p /opt/nivq /etc/nivq
sudo cp nivq-0.2.4.jar /opt/nivq/nivq.jar
sudo chown -R nivq:nivq /opt/nivq /etc/nivq

3. Veri depolarını hazırlayın

nivq'yu erişilebilir bir pgvector eklentili PostgreSQL 16+ ve bir Redis 7+ / Valkey'e yönlendirin. Aynı sunucuda ya da başka bir yerde yönetilen olabilirler — nivq'nun yalnızca bağlantı bilgilerine ihtiyacı vardır; bunlar bir sonraki adımda env dosyasına girilir.

4. Ortam dosyasını oluşturun

nivq tamamen ortam değişkenleriyle yapılandırılır. Bunları /etc/nivq/nivq.env içine koyun (gizler içerdiği için root sahipliğinde, yalnızca servis kullanıcısı tarafından okunabilir):

# veri depoları
NIVQ_DATASOURCE_URL=jdbc:postgresql://localhost:5432/nivqdb
NIVQ_DATASOURCE_USERNAME=nivq
NIVQ_DATASOURCE_PASSWORD=guclu-bir-deger
NIVQ_REDIS_HOST=localhost
NIVQ_REDIS_PORT=6379

# 32 baytlık base64 anahtar (AES-256) — yedekleyin; kaybı kurtarılamaz
NIVQ_ENCRYPTION_KEY_V1=buraya-base64-32-bayt

# platform-yönetimli LLM
NIVQ_PLATFORM_LLM_PROVIDER=anthropic
NIVQ_PLATFORM_LLM_API_KEY=sk-...

# IdP'siz ilk giriş — OAuth/OIDC'yi sonra bağlayın, bkz. Kimlik doğrulama
NIVQ_BOOTSTRAP_ADMIN_USERNAME=admin@example.com
NIVQ_BOOTSTRAP_ADMIN_PASSWORD=uzun-bir-parola

# genel URL'ler
BACKEND_URL=https://api.example.com
FRONTEND_URL=https://app.example.com

# isteğe bağlı: lisansı sonradan yüklemek yerine bir dosyadan tohumlayın
# NIVQ_LICENSING_LICENSE_FILE=/etc/nivq/license.jwt

sudo chown nivq:nivq /etc/nivq/nivq.env
sudo chmod 600 /etc/nivq/nivq.env

Değişkenlerin tamamı — SSO, ajan başına LLM, embedding'ler, ödemeler, gözlemlenebilirlik — Yapılandırma'da.

5. Doğrudan çalıştırın

Hepsi bu kadar — nivq doğrudan JAR'dan çalışır:

sudo -u nivq env $(grep -v '^#' /etc/nivq/nivq.env | xargs) \
  java -XX:+UseZGC -XX:MaxRAMPercentage=75.0 --enable-native-access=ALL-UNNAMED \
  -jar /opt/nivq/nivq.jar

İlk açılış veritabanı göçlerini çalıştırır. Başka bir kabukta, curl http://localhost:8080/actuator/health komutu {"status":"UP"} döndürür. Bu, ön planda çalışır — ilk kontrol için ideal. Hata durumunda yeniden başlayan ve sunucuyla birlikte açılan kalıcı bir servis için aşağıdaki systemd'yi kurun (önce Ctrl-C ile ön plandaki çalıştırmayı durdurun).

6. systemd servisi olarak çalıştırın

/etc/systemd/system/nivq.service oluşturun:

[Unit]
Description=NivQ API
After=network-online.target
Wants=network-online.target

[Service]
User=nivq
Group=nivq
EnvironmentFile=/etc/nivq/nivq.env
ExecStart=/usr/bin/java -XX:+UseZGC -XX:MaxRAMPercentage=75.0 --enable-native-access=ALL-UNNAMED -jar /opt/nivq/nivq.jar
SuccessExitStatus=143
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Sonra etkinleştirip başlatın:

sudo systemctl daemon-reload
sudo systemctl enable --now nivq
sudo systemctl status nivq
journalctl -u nivq -f          # logları izle

7. Lisansı etkinleştirin

NIVQ_LICENSING_LICENSE_FILE'ı ayarlamadıysanız nivq activation-pending durumdadır. Parmak izini okuyup Nivorbit'in döndürdüğü lisansı yükleyin:

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

Lisans veritabanında saklanır; bu yüzden yeniden başlatmalara ve JAR yükseltmelerine dayanır. Tam yaşam döngüsü için Lisanslama ve etkinleştirme'ye bakın.

8. Önüne TLS koyun

nivq, 8080 portunda düz HTTP dinler. TLS'i bir ters proxy'de (nginx, Caddy) sonlandırın ve BACKEND_URL / FRONTEND_URL'i genel HTTPS URL'lerine ayarlayın. Sonradan yükseltmek için servisi durdurun, JAR'ı değiştirin ve yeniden başlatın. Proxy, yedekleme ve gözlemlenebilirlik için Üretim sertleştirme'ye bakın.

9. Web istemcisini servis edin

JAR yalnızca API'dir; kullanıcılarınızın web istemcisine (tarayıcı arayüzü) ihtiyacı var. Bare metal'de iki seçeneğiniz var:

• Konteyneri çalıştırın — sadece bunun için bir konteyner çalışma zamanı varsa, statik arayüz imajını API'ye yönlendirerek çalıştırın:

  docker run -d --name nivq-web -p 3000:8080 \
    -e NIVQ_API_BASE_URL=https://api.example.com \
    ghcr.io/nivorbit/images/nivq-web:0.2.2

• Statik dosyaları servis edin — hiç konteyner olmadan: dist/ paketini alın, yanına API'nize işaret eden bir config/default.json koyun ve zaten çalıştırdığınız nginx/Apache'den servis edin. Başlangıç config'leri deploy/nginx.conf ve deploy/apache.conf'ta gelir.

Girişin çalışması için tam olarak API'nin FRONTEND_URL'inde servis edin. Tüm ayrıntılar — config alanları ve auth bağlantısı — Web istemcisi'nde.