Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

AISRV

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Übersicht

AISRV ist der zentrale KI-Server, der eine GraphQL-API für die basebox-KI-Anwendung bereitstellt. Er übernimmt die Benutzerauthentifizierung über OpenID Connect (OIDC/Keycloak), verbindet sich mit einer PostgreSQL-Datenbank und integriert LLM-Provider, RAG-Dienste, Whisper-Transkription und weitere externe Dienste.

Wichtig: Der Server ist für den Betrieb hinter einem Reverse Proxy (z. B. nginx) ausgelegt und bietet selbst keine TLS-Unterstützung. Konfigurieren Sie Ihren Reverse Proxy oder Ingress-Controller für die TLS/SSL-Terminierung.

Deployment

AISRV wird per Helm-Chart in Kubernetes-Cluster bereitgestellt, mit einer integrierten, von CloudNativePG verwalteten PostgreSQL-Datenbank.

Helm-Chart-Konfiguration

Grundeinstellungen

Parameter	Standard	Beschreibung
`replicaCount`	`1`	Anzahl der AISRV-Pod-Replikate
`image.repository`	`gitea.basebox.health/basebox-distribution/aisrv`	Container-Image-Repository
`image.pullPolicy`	`IfNotPresent`	Image-Pull-Policy
`image.tag`	`latest`	Auszurollender Image-Tag
`fullnameOverride`	`aisrv`	Vollständigen Namen des Deployments überschreiben

Dienstkonfiguration

Parameter	Standard	Beschreibung
`service.type`	`ClusterIP`	Kubernetes-Service-Typ
`service.port`	`8888`	Service-Port

Ressourcenverwaltung

Parameter	Beschreibung
`resources.requests`	CPU-/Speicher-Requests
`resources.limits`	CPU-/Speicher-Limits
`autoscaling.enabled`	Horizontales Pod-Autoscaling aktivieren
`autoscaling.minReplicas`	Minimale Anzahl Replikate
`autoscaling.maxReplicas`	Maximale Anzahl Replikate
`autoscaling.targetCPUUtilizationPercentage`	Ziel-CPU für die Skalierung

Health-Checks

Parameter	Beschreibung
`livenessProbe`	Konfiguration der Liveness-Probe
`readinessProbe`	Konfiguration der Readiness-Probe

Datenbankkonfiguration

Datenbankeinstellungen

Parameter	Standard	Beschreibung
`database.enabled`	`true`	Datenbankerstellung aktivieren
`database.imageName`	`ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm`	PostgreSQL-Image
`database.host`	`aisrv-db-rw`	Datenbank-Host (Read-Write-Service)
`database.port`	`5432`	Datenbank-Port
`database.user`	`aisrv`	Datenbank-Benutzername
`database.password`	`<secure-password>`	Datenbank-Passwort
`database.name`	`aisrv`	Datenbankname
`database.sslMode`	`disable`	SSL-Modus der Datenbank (`disable`, `require`, `verify-full`)

CloudNativePG-Cluster-Einstellungen

Parameter	Standard	Beschreibung
`aisrv-db.cluster.instances`	`1`	Anzahl PostgreSQL-Instanzen
`aisrv-db.cluster.storage.size`	`10Gi`	Speichergröße der Datenbank
`aisrv-db.cluster.storage.storageClass`	`default`	Zu verwendende Storage Class
`aisrv-db.cluster.monitoring.enablePodMonitor`	`false`	Prometheus-Monitoring aktivieren

Migrationseinstellungen

Variable	Standard	Beschreibung
`AISRV_DB_MIGRATE`	`false`	Automatische Datenbankmigration beim Start
`AISRV_DB_MIGRATE_BACKUP`	`false`	Datenbank vor Migrationen sichern
`AISRV_DB_MIGRATE_BACKUP_DIR`	`migrations-backups`	Pfad des Backup-Verzeichnisses
`AISRV_DB_MIGRATE_RUN_ONLY`	`false`	Nur Migrationen ausführen, dann beenden

Umgebungsvariablen

Serverkonfiguration

Variable	Standard	Beschreibung
`AISRV_HOST`	`0.0.0.0`	Host oder IP-Adresse, auf der gelauscht wird
`AISRV_PORT`	`8888`	Port, auf dem gelauscht wird
`AISRV_LOG_LEVEL`	`info`	Log-Level (`trace`, `debug`, `info`, `warn`, `error`)
`AISRV_SET_CORS_HEADERS`	`true`	CORS-Header setzen (bei Reverse Proxy deaktivieren)
`AISRV_DEBUG_MODE`	`false`	Debug-Modus: Fehler unverändert an den Client senden
`AISRV_ON_PREMISE`	`false`	Server-Deployment-Modus (basebox Server)
`AISRV_DO_ON_PREMISE_INIT`	`false`	Initialisierung im Server-Modus
`AISRV_METRICS_PORT`	Keiner	Metrik-Port (Prometheus)

Datenbankverbindung (aus Secrets)

Variable	Quelle	Beschreibung
`AISRV_DB_HOST`	Secret `aisrv-database`	Datenbank-Hostname
`AISRV_DB_PORT`	Secret `aisrv-database`	Datenbank-Port
`AISRV_DB_USER`	Secret `aisrv-database`	Datenbank-Benutzername
`AISRV_DB_PASSWORD`	Secret `aisrv-database`	Datenbank-Passwort
`AISRV_DB_NAME`	Secret `aisrv-database`	Datenbankname
`AISRV_DB_SSL_MODE`	Konfiguration	SSL-Modus für die Datenbankverbindung

OIDC-/Authentifizierungskonfiguration

Variable	Beschreibung
`AISRV_OIDC_IDP_URL`	Basis-URL des IdP-Servers (Keycloak) (ohne Realm)
`AISRV_OIDC_ISSUER_URL`	Optionale Issuer-URL für die Token-Validierung
`AISRV_OIDC_AUD`	Inhalt des OIDC-Audience-Felds
`AISRV_OIDC_JWKS_FILEPATH`	Pfad zur OIDC-JWKS-Datei
`AISRV_OIDC_SUPER_ADMIN_USER`	Super-Admin-Benutzername
`AISRV_OIDC_SUPER_ADMIN_PASSWORD`	Super-Admin-Passwort
`AISRV_OIDC_SUPER_ADMIN_CLIENT_ID`	Super-Admin-Client-ID
`AISRV_OIDC_SUPER_ADMIN_CLIENT_SECRET`	Super-Admin-Client-Secret
`AISRV_BASE_DOMAIN`	Basis-Domain für Organisationen (z. B. `basebox.ai`)
`AISRV_USE_TLS`	HTTPS-URLs annehmen (true für Produktion)

GraphQL-Konfiguration

Variable	Standard	Beschreibung
`AISRV_QUERY_DEPTH_LIMIT`	`6`	Tiefenlimit für GraphQL-Queries
`AISRV_QUERY_COMPLEXITY_LIMIT`	`20`	Komplexitätslimit für GraphQL-Queries
`AISRV_GRAPHQL_ALLOW_INTROSPECTION`	`false`	Introspektions-Queries erlauben
`AISRV_GRAPHQL_APOLLO_TRACING`	`false`	Apollo-Tracing aktivieren
`AISRV_GRAPHQL_GRAPHIQL`	`false`	GraphiQL-Oberfläche aktivieren

LLM-Konfiguration

Variable	Beschreibung
`AISRV_LLM_URL`	URL des LLM-Servers
`AISRV_LLM_CHAT_ENDPOINT`	Pfad des Chat-Completions-Endpunkts
`AISRV_LLM_API_KEY`	API-Schlüssel für den LLM-Dienst
`AISRV_LLM_MODEL`	LLM-Modellbezeichner
`AISRV_LLM_PROVIDER`	LLM-Provider (bestimmt das Auth-Schema)
`AISRV_LLM_CONTEXT_SIZE`	Maximale Kontextgröße in Tokens
`AISRV_LLM_WORD_LIMIT`	Geschätztes Wortlimit je Anfrage
`AISRV_LLM_MAX_TOKENS`	Maximale Ausgabe-Tokens (Standard: 8000)
`AISRV_LLM_TEMPERATURE`	Sampling-Temperatur (0–1)
`AISRV_LLM_TOP_P`	Nucleus-Sampling-Parameter (0–1)
`AISRV_LLM_REPETITION_PENALTY`	Repetition Penalty (>1.0 hemmt Wiederholungen)

Für einen physisch getrennten vLLM-Server nutzen Sie die Secret-gestützte Konfiguration unter Deployment-Topologien. Aktuelle Releases benötigen zusätzlich zur allgemeinen AISRV-API-Key-Einstellung die provider-abgeleitete Variable VLLM_API_KEY.

RAG-Konfiguration

Variable	Beschreibung
`AISRV_ENABLE_RAG_API`	RAG-Endpunkte aktivieren
`AISRV_RAG_URL`	Basis-URL der RAG-Server-API
`AISRV_RAG_DOWNLOAD_URL`	URL, über die der RAG-Server Dateien herunterlädt
`AISRV_RAG_API_KEY`	API-Schlüssel für den RAG-Dienst
`AISRV_MAX_RAG_FILE_SIZE`	Maximale Dateigröße für Uploads
`AISRV_MAX_RAG_FILES_PER_APP`	Maximale Dateien je Anwendung

Whisper-Konfiguration

Variable	Standard	Beschreibung
`AISRV_WHISPER_URL`	`http://localhost:6000/inference`	Whisper-Dienst-Endpunkt
`AISRV_WHISPER_API_KEY`	Keiner	API-Schlüssel für den Whisper-Dienst

SMTP-Konfiguration

Variable	Beschreibung
`AISRV_SMTP_HOST`	SMTP-Server-Hostname
`AISRV_SMTP_PORT`	SMTP-Server-Port
`AISRV_SMTP_USERNAME`	SMTP-Benutzername
`AISRV_SMTP_PASSWORD`	SMTP-Passwort
`AISRV_SMTP_TLS_TYPE`	SMTP-Verbindungstyp (`tls`, `starttls`)
`AISRV_SENDER_EMAIL`	Absenderadresse

Medienspeicher-Konfiguration

Variable	Beschreibung
`AISRV_STORE_URL`	URL des Store-Servers
`AISRV_MEDIA_ROOT`	Wurzelverzeichnis für hochgeladene Dateien
`AISRV_MEDIA_URL`	URL zur Wurzel des Medienservers
`AISRV_ENABLE_STATIC_FILES`	Statischen Dateiserver aktivieren

API-Konfiguration

Variable	Standard	Beschreibung
`AISRV_ENABLE_REST_API`	`false`	REST-API und Token-Verwaltung aktivieren

Konfigurationsbeispiele

Produktivkonfiguration

# values-production.yaml
replicaCount: 3

image:
  repository: gitea.basebox.health/basebox-distribution/aisrv
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8888

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  hosts:
    - host: company.com
      paths:
        - path: /graphql
          pathType: Prefix
  tls:
    - secretName: aisrv-tls
      hosts:
        - company.com

resources:
  requests:
    cpu: 1000m
    memory: 2Gi
  limits:
    cpu: 2000m
    memory: 4Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 15
  periodSeconds: 5

database:
  enabled: true
  host: aisrv-db-rw
  port: 5432
  user: aisrv
  password: "<generate-secure-password>"
  name: aisrv
  sslMode: "require"

aisrv-db:
  cluster:
    instances: 3
    storage:
      size: 50Gi
      storageClass: fast-ssd
    monitoring:
      enablePodMonitor: true

env:
  # Server
  AISRV_HOST: "0.0.0.0"
  AISRV_PORT: "8888"
  AISRV_LOG_LEVEL: "info"
  AISRV_SET_CORS_HEADERS: "false"  # Using ingress
  AISRV_DEBUG_MODE: "false"
  AISRV_METRICS_PORT: "9090"
  AISRV_DO_ON_PREMISE_INIT: "true"
  AISRV_ON_PREMISE: "true"

  # Database (from secrets)
  AISRV_DB_HOST:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: host
  AISRV_DB_PORT:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: port
  AISRV_DB_USER:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: username
  AISRV_DB_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: password
  AISRV_DB_NAME:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: name
  AISRV_DB_SSL_MODE: "require"

  # Migrations
  AISRV_DB_MIGRATE: "true"
  AISRV_DB_MIGRATE_BACKUP: "true"
  AISRV_DB_MIGRATE_BACKUP_DIR: "/backups"

  # OIDC
  AISRV_OIDC_IDP_URL: "http://idp:8080"
  AISRV_OIDC_ISSUER_URL: "https://auth.company.com"
  AISRV_OIDC_AUD: "aisrv"
  AISRV_OIDC_SUPER_ADMIN_USER:
    valueFrom:
      secretKeyRef:
        name: aisrv-admin
        key: username
  AISRV_OIDC_SUPER_ADMIN_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: aisrv-admin
        key: password
  AISRV_BASE_DOMAIN: "company.com"
  AISRV_USE_TLS: "true"

  # GraphQL
  AISRV_QUERY_DEPTH_LIMIT: "8"
  AISRV_QUERY_COMPLEXITY_LIMIT: "50"
  AISRV_GRAPHQL_ALLOW_INTROSPECTION: "false"
  AISRV_GRAPHQL_GRAPHIQL: "false"

  # LLM
  AISRV_LLM_URL: "http://inference:8000"
  AISRV_LLM_CHAT_ENDPOINT: "/v1/chat/completions"
  AISRV_LLM_API_KEY:
    valueFrom:
      secretKeyRef:
        name: llm-credentials
        key: api-key
  AISRV_LLM_MODEL: "meta-llama/Llama-3.1-8B-Instruct"
  AISRV_LLM_PROVIDER: "openai-compatible"
  AISRV_LLM_CONTEXT_SIZE: "16000"
  AISRV_LLM_MAX_TOKENS: "4096"
  AISRV_LLM_TEMPERATURE: "0.7"

  # RAG
  AISRV_ENABLE_RAG_API: "true"
  AISRV_RAG_URL: "http://ragsrv:3001"
  AISRV_RAG_API_KEY:
    valueFrom:
      secretKeyRef:
        name: rag-credentials
        key: api-key

  # Whisper
  AISRV_WHISPER_URL: "http://whisper:6000/inference"

  # SMTP
  AISRV_SMTP_HOST: "smtp.company.com"
  AISRV_SMTP_PORT: "587"
  AISRV_SMTP_USERNAME:
    valueFrom:
      secretKeyRef:
        name: smtp-credentials
        key: username
  AISRV_SMTP_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: smtp-credentials
        key: password
  AISRV_SMTP_TLS_TYPE: "starttls"
  AISRV_SENDER_EMAIL: "noreply@company.com"

Installation

Voraussetzungen

Kubernetes-Cluster (1.23+)
Helm 3.x
CloudNativePG-Operator installiert
Storage-Provisioner
OIDC-/Keycloak-Instanz konfiguriert

CloudNativePG-Operator installieren

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg

AISRV installieren

# Install with custom values
helm install aisrv oci://gitea.basebox.health/basebox-distribution/helm/aisrv \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Verify installation
kubectl get pods -n basebox -l app.kubernetes.io/name=aisrv
kubectl get cluster -n basebox aisrv-db

Upgrade

helm upgrade aisrv oci://gitea.basebox.health/basebox-distribution/helm/aisrv \
  --values values-production.yaml \
  --namespace basebox

Deinstallation

helm uninstall aisrv --namespace basebox

# Delete PVCs if needed
kubectl delete pvc -n basebox -l cnpg.io/cluster=aisrv-db

Migrationen

Wie Migrationen funktionieren

Migrationsverfolgung: Die Tabelle _migrations_history verfolgt angewendete Migrationen
Nummeriertes Format: Vnnn__<migration_name> (doppelte Unterstriche)
Sequenzielle Ausführung: Migrationen laufen in numerischer Reihenfolge
Prüfsummenvalidierung: Erkennt Änderungen an Migrationsdateien
Eingebettet: Alle Migrationen sind in die Anwendungs-Binary eingebettet

Migrationen ausführen

Automatisch beim Start:

env:
  AISRV_DB_MIGRATE: "true"
  AISRV_DB_MIGRATE_BACKUP: "true"

Nur Migrationen (kein Serverstart):

env:
  AISRV_DB_MIGRATE: "true"
  AISRV_DB_MIGRATE_RUN_ONLY: "true"

Prüfung

Deployment prüfen

# Check pods
kubectl get pods -n basebox -l app.kubernetes.io/name=aisrv

# Check database
kubectl get cluster -n basebox aisrv-db

# View logs
kubectl logs -n basebox -l app.kubernetes.io/name=aisrv --tail=100

GraphQL-API testen

# Port forward
kubectl port-forward -n basebox svc/aisrv 8888:8888

# Test query
curl -X POST http://localhost:8888/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

Integration mit anderen Diensten

IDP (Keycloak)

env:
  AISRV_OIDC_IDP_URL: "http://idp:8080"

Inferenzserver

env:
  AISRV_LLM_URL: "http://inference:8000"
  AISRV_LLM_CHAT_ENDPOINT: "/v1/chat/completions"

RAGSRV

env:
  AISRV_ENABLE_RAG_API: "true"
  AISRV_RAG_URL: "http://ragsrv:3001"

STORESRV

env:
  AISRV_STORE_URL: "http://storesrv:8889"

Performance-Tuning

Ressourcenzuteilung

resources:
  requests:
    cpu: 1000m
    memory: 2Gi
  limits:
    cpu: 2000m
    memory: 4Gi

Datenbank-Performance

Lesereplikate nutzen (aisrv-db.cluster.instances erhöhen)
Schneller Speicher (SSD/NVMe)
Connection Pooling (in der Anwendung konfiguriert)

Monitoring

Metriken

Prometheus-Metriken aktivieren:

env:
  AISRV_METRICS_PORT: "9090"

Health-Checks

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 15
  periodSeconds: 5

Datenbank-Monitoring

CloudNativePG-Monitoring aktivieren:

aisrv-db:
  cluster:
    monitoring:
      enablePodMonitor: true