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

// installation

basebox.ai Helm

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Übersicht

Das basebox-Umbrella-Chart ist ein Helm-Chart, das alle Dienste der basebox-KI-Plattform in einem einzigen Deployment bündelt. Es orchestriert das Deployment von Frontend, Backend-Diensten, Datenbanken, Identitätsanbieter und Inferenzdiensten.

Nutzungsbedingungen

Mit der Nutzung dieser Software (d. h. dem Abrufen von Container-Images und/oder dem Deployment) akzeptieren Sie die Nutzungsbedingungen und die Datenschutzerklärung von basebox.ai.

Architektur

Das Umbrella-Chart stellt die folgenden Dienste bereit:

Dienst	Zweck	Port	Abhängigkeiten
Frontend	Vue-3-Webanwendung	3000	AISRV, IDP
IDP	Keycloak-Identitätsanbieter	8080	PostgreSQL (idp-db)
AISRV	Haupt-API-Server (GraphQL)	8888	PostgreSQL (aisrv-db), IDP, Inference, RAGSRV
STORESRV	Store-Server (GraphQL)	8889	PostgreSQL (storesrv-db), IDP
RAGSRV	RAG-Vektordatenbankdienst	3001	PostgreSQL (ragsrv-db), RAGSRV-Support, GPU
RAGSRV-Support	RAG-Modell-Inferenzdienst	8000	GPU
Inference	LLM-Inferenzserver	8000	GPU
CNPG Operator	CloudNativePG-Datenbank-Operator	–	–

Voraussetzungen

Anforderungen an den Kubernetes-Cluster

Kubernetes-Version: 1.23 oder neuer
Helm-Version: 3.x
GPU-Unterstützung: NVIDIA GPU Operator oder Vergleichbares (für Inferenz- und RAG-Dienste)
Ingress-Controller: beliebig
Speicher: Dynamische Volume-Bereitstellung mit einer Standard-Storage-Class

Ressourcenanforderungen

Minimales Produktiv-Deployment: - CPU: 5+ Kerne - Arbeitsspeicher: 12GB+ RAM - GPU: 1+ NVIDIA-GPUs (1 für Inferenz) - Speicher: 200GB+ für Datenbanken und Modell-Caching

Empfohlenes Produktiv-Deployment: - CPU: 10+ Kerne - Arbeitsspeicher: 32GB+ RAM - GPU: 2+ NVIDIA-GPUs (1 für Inferenz, 1 für RAGSRV) - Speicher: 500GB+ SSD/NVMe

Externe Abhängigkeiten

Image-Registry: Zugang zu gitea.basebox.health/basebox-distribution/
Domain/DNS: Konfiguriertes DNS für die Anwendungsdomain
TLS-Zertifikate: Gültige Zertifikate für HTTPS (über cert-manager, vorab erstellt oder anderweitig)

Globale Konfiguration

Dienstkonfiguration

CloudNativePG Operator

Parameter	Standard	Beschreibung
`cnpg-operator.fullnameOverride`	`cnpg`	Namensüberschreibung für den CNPG-Operator

IDP (Keycloak)

Parameter	Standard	Beschreibung
`idp.ingress.enabled`	`true`	Ingress für IDP aktivieren
`idp.ingress.className`	`nginx`	Name der Ingress-Klasse
`idp.ingress.hosts[].host`	Erforderlich	Hostname für IDP
`idp.ingress.hosts[].paths[].path`	`/auth`	Basispfad für Keycloak
`idp.ingress.tls`	`[]`	TLS-Konfiguration

Wichtige Annotationen: - Proxy-Puffergrößen für große Header konfiguriert - CORS für Cross-Origin-Anfragen aktiviert - Caching für Authentifizierungsabläufe deaktiviert - Lange Timeouts für SSO-Vorgänge (86400s)

AISRV

Parameter	Standard	Beschreibung
`aisrv.database.enabled`	`true`	PostgreSQL-Datenbank aktivieren
`aisrv.database.host`	`aisrv-db-rw`	Datenbank-Host
`aisrv.database.port`	`5432`	Datenbank-Port
`aisrv.database.user`	`aisrv`	Datenbank-Benutzername
`aisrv.database.password`	Erforderlich	Datenbank-Passwort (sicheren Wert verwenden)
`aisrv.database.dbname`	`aisrv`	Datenbankname
`aisrv.ingress.enabled`	`true`	Ingress aktivieren

Freigegebene Pfade: - /rest – Anwendungsendpunkte (u. a. Token-Verwaltung) - /graphql – GraphQL-API-Endpunkt - /subscriptions – GraphQL-Subscriptions (WebSocket) - /media – Auslieferung von Mediendateien - /stream/message-of-day – Stream der Tagesmeldungen - /v1 – Endpunkte der OpenAI-kompatiblen API

STORESRV

Parameter	Standard	Beschreibung
`storesrv.logLevel`	`trace`	Log-Level
`storesrv.host`	`0.0.0.0`	Bind-Adresse des Servers
`storesrv.port`	`8889`	Server-Port
`storesrv.oauth.IdpUrl`	`http://idp:8080/realms/master`	OAuth-IDP-URL
`storesrv.oauth.IdpAud`	`account`	OAuth-Audience
`storesrv.database.enabled`	`true`	PostgreSQL-Datenbank aktivieren
`storesrv.graphql.allowIntrospection`	`true`	GraphQL-Introspektion erlauben
`storesrv.graphql.graphiql`	`true`	GraphiQL-Oberfläche aktivieren

RAGSRV

Parameter	Standard	Beschreibung
`ragsrv.enabled`	`true`	RAGSRV-Dienst aktivieren
`ragsrv.resources.requests.nvidia.com/gpu`	`1`	Anzahl angeforderter GPUs
`ragsrv.resources.limits.nvidia.com/gpu`	`1`	Maximale GPUs
`ragsrv.env.COMPUTE`	`gpu`	Rechenmodus (`gpu` oder `cpu`)

Hinweis: RAGSRV-Support wird automatisch aktiviert, wenn RAGSRV aktiviert ist.

RAGSRV-Support

Parameter	Beschreibung

Dieser Dienst wird automatisch mit RAGSRV bereitgestellt.

Inference

Parameter	Standard	Beschreibung
`inference.enabled`	`true`	Inferenzdienst aktivieren
`inference.resources.requests.nvidia.com/gpu`	`1`	Anzahl angeforderter GPUs
`inference.resources.limits.nvidia.com/gpu`	`1`	Maximale GPUs

Frontend

Parameter	Standard	Beschreibung
`frontend.ingress.enabled`	`true`	Ingress aktivieren
`frontend.ingress.hosts[].path`	`/`	Frontend unter dem Wurzelpfad ausliefern

Das Frontend ist mit denselben Proxy- und CORS-Einstellungen wie die anderen Dienste konfiguriert.

Ingress-Konfiguration

Gemeinsame Ingress-Annotationen

Alle Dienste verwenden einheitliche nginx-Ingress-Annotationen:

Proxy-Konfiguration

nginx.ingress.kubernetes.io/proxy-body-size: "20m"
nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
nginx.ingress.kubernetes.io/proxy-busy-buffers-size: "256k"
nginx.ingress.kubernetes.io/client-header-buffer-size: "16k"
nginx.ingress.kubernetes.io/large-client-header-buffers: "4 16k"
nginx.ingress.kubernetes.io/proxy-read-timeout: "86400"
nginx.ingress.kubernetes.io/proxy-send-timeout: "86400"
nginx.ingress.kubernetes.io/proxy-buffering: "off"

Zweck: - Große Body-Größe (20MB) für Datei-Uploads - Große Puffer für Authentifizierungs-Header (JWT-Tokens) - Lange Timeouts (24h) für WebSocket-Verbindungen - Pufferung deaktiviert für Streaming-Antworten

Cache-Steuerung

nginx.ingress.kubernetes.io/Cache-Control: "no-store, no-cache, must-revalidate, proxy-revalidate"
nginx.ingress.kubernetes.io/Pragma: "no-cache"
nginx.ingress.kubernetes.io/Expires: "0"
nginx.ingress.kubernetes.io/Surrogate-Control: "no-store"

Zweck: Caching von API-Antworten und Authentifizierungsabläufen verhindern

CORS-Konfiguration

nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-origin: "*"
nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, OPTIONS"
nginx.ingress.kubernetes.io/cors-allow-headers: "Authorization, Content-Type, X-Realm"
nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
nginx.ingress.kubernetes.io/cors-max-age: "86400"

Zweck: Cross-Origin-Anfragen für das SPA-Frontend ermöglichen

Konfigurationsbeispiele

Minimale Produktivkonfiguration

global:
  domain: basebox.company.com
  tls:
    mode: cert-manager
    clusterIssuer: letsencrypt-prod
    secretName: basebox-company-tls

cnpg-operator:
  fullnameOverride: cnpg

idp:
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: basebox.company.com
        paths:
          - path: /auth
            pathType: Prefix

aisrv:
  database:
    enabled: true
    password: "<generate-secure-password>"
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: basebox.company.com
        paths:
          - path: /rest
            pathType: Prefix
          - path: /graphql
            pathType: Exact
          - path: /subscriptions
            pathType: Exact
          - path: /media
            pathType: Prefix
          - path: /stream/message-of-day
            pathType: Exact
          - path: /v1
            pathType: Prefix

storesrv:
  logLevel: info
  database:
    enabled: true
    password: "<generate-secure-password>"
  graphql:
    allowIntrospection: false
    graphiql: false

ragsrv:
  enabled: true
  resources:
    requests:
      nvidia.com/gpu: 1
    limits:
      nvidia.com/gpu: 1
  env:
    COMPUTE: gpu

ragsrv-support:

inference:
  enabled: true
  resources:
    requests:
      nvidia.com/gpu: 1
    limits:
      nvidia.com/gpu: 1

frontend:
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: basebox.company.com
        paths:
          - path: /
            pathType: Prefix

Installation

Values-Datei vorbereiten

Zwingend zu ändernde Werte: - Alle Datenbank-Passwörter - Domainnamen - TLS-Secret-Namen - Image-Pull-Secrets - GPU-Ressourcenzuteilungen - Storage-Class-Namen

Chart installieren

# Install basebox umbrella chart
helm install basebox ./basebox.ai \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace \
  --timeout 30m

# Watch the deployment
kubectl get pods -n basebox -w

Installation prüfen

# Check all pods are running
kubectl get pods -n basebox

# Check database clusters
kubectl get cluster -n basebox

# Check ingress
kubectl get ingress -n basebox

# Check GPU allocation
kubectl describe nodes | grep -A5 "Allocated resources"

Upgrade

Upgrades laufen mit helm upgrade gegen das OCI-Chart, mit denselben Values-Dateien wie bei der Installation und --reset-then-reuse-values; vorher die AISRV-Datenbank sichern. Den vollständigen Ablauf (Lesen, Sichern, Rendern, Aktualisieren, Migrationen, Prüfen, Rollback) beschreibt Updates; die Befehle und den Hinweis zur Migration V32 finden Sie unter Helm Charts verwenden → Bestehende Installation aktualisieren.

Deinstallation

Vollständige Entfernung

# Uninstall chart
helm uninstall basebox --namespace basebox

# Delete PVCs (databases - DATA LOSS!)
kubectl delete pvc -n basebox --all

# Delete namespace
kubectl delete namespace basebox

Daten erhalten

Um Datenbanken bei der Deinstallation zu erhalten:

# Uninstall chart
helm uninstall basebox --namespace basebox

# PVCs remain - do not delete them
# To reinstall with existing data:
helm install basebox ./basebox.ai \
  --values values-production.yaml \
  --namespace basebox

Backup

Was gesichert werden muss, Dumps, Wiederherstellung und Aufbewahrung beschreibt Backup & Wiederherstellung. Chart-spezifisch ist die Konfiguration automatischer CloudNativePG-Backups in den Values:

aisrv:
  aisrv-db:
    cluster:
      backup:
        barmanObjectStore:
          destinationPath: s3://backups/aisrv
          s3Credentials:
            accessKeyId:
              name: backup-s3-creds
              key: ACCESS_KEY_ID
            secretAccessKey:
              name: backup-s3-creds
              key: SECRET_ACCESS_KEY
        retentionPolicy: "30d"

Monitoring und Logs

Health-Endpunkte, Alarme und Log-Auswertung beschreiben Monitoring und Logging. Chart-spezifisch ist das Einschalten der Prometheus-Metriken in den Values:

aisrv:
  metrics:
    enabled: true
    port: 9090

idp:
  idp-db:
    cluster:
      monitoring:
        enablePodMonitor: true

Troubleshooting

Fehlerbilder und Debug-Befehle stehen unter Troubleshooting und in der FAQ.

Sicherheitsaspekte

Ressourcenzuteilung

Backend-Dienste (AISRV, STORESRV):

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

GPU-Dienste (Inference, RAGSRV):

resources:
  requests:
    cpu: 4000m
    memory: 32Gi
    nvidia.com/gpu: 1
  limits:
    cpu: 8000m
    memory: 64Gi
    nvidia.com/gpu: 1

Datenbanken:

cluster:
  instances: 3
  storage:
    size: 50Gi
    storageClass: fast-ssd

Datenbank-Performance

Lesereplikate nutzen (instances erhöhen)
Schnellen Speicher nutzen (SSD/NVMe)
PostgreSQL-Parameter tunen
Regelmäßig VACUUM und ANALYZE

Nächster Schritt: Helm Charts verwenden · Services: AISRV