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 – REST-API-Endpunkte - /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

Standard-Upgrade

# Update values file
vim values-production.yaml

# Upgrade chart
helm upgrade --install basebox basebox/basebox.ai \
  --values values-production.yaml \
  --namespace basebox \
  --timeout 30m

Rolling-Upgrade-Strategie

Für Upgrades ohne Ausfallzeit:

Datenbanken zuerst aktualisieren (bei Schemaänderungen)
Backend-Dienste aktualisieren (AISRV, STORESRV, RAGSRV)
IDP aktualisieren (Authentifizierungsdienst)
Inferenzdienste aktualisieren
Frontend zuletzt 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

Datenbankverwaltung

Alle Datenbanken sichern

# IDP database
kubectl exec -n basebox idp-db-1 -- \
  pg_dump -U idp idp > idp-backup.sql

# AISRV database
kubectl exec -n basebox aisrv-db-1 -- \
  pg_dump -U aisrv aisrv > aisrv-backup.sql

# STORESRV database
kubectl exec -n basebox storesrv-db-1 -- \
  pg_dump -U storesrv storesrv > storesrv-backup.sql

# RAGSRV database
kubectl exec -n basebox ragsrv-db-1 -- \
  pg_dump -U ragsrv ragsrv > ragsrv-backup.sql

CloudNativePG-Backups

Automatisierte Backups in den Values konfigurieren:

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

Health-Checks

# Check all service health endpoints
kubectl get pods -n basebox -o wide

# Port-forward and test endpoints
kubectl port-forward -n basebox svc/aisrv 8888:8888
curl http://localhost:8888/health

kubectl port-forward -n basebox svc/inference 8000:8000
curl http://localhost:8000/health

Metriken

Prometheus-Monitoring aktivieren:

aisrv:
  metrics:
    enabled: true
    port: 9090

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

Logs

# View logs from all AISRV pods
kubectl logs -n basebox -l app.kubernetes.io/name=aisrv --tail=100 -f

# View logs from inference service
kubectl logs -n basebox -l app.kubernetes.io/name=inference --tail=100 -f

# View logs from specific pod
kubectl logs -n basebox <pod-name> -f

Troubleshooting

Häufige Probleme

Pods bleiben in Pending: - GPU-Verfügbarkeit prüfen: kubectl describe nodes | grep nvidia.com/gpu - Speicher prüfen: kubectl get pvc -n basebox - Ressourcen-Requests gegen Cluster-Kapazität prüfen

Datenbankverbindung schlägt fehl: - Prüfen, dass Datenbank-Pods laufen: kubectl get pods -n basebox | grep db - Datenbank-Secrets prüfen: kubectl get secrets -n basebox - Datenbank-Logs prüfen: kubectl logs -n basebox <db-pod-name>

Ingress funktioniert nicht: - Prüfen, dass der Ingress-Controller läuft - Ingress-Ressourcen prüfen: kubectl get ingress -n basebox - Prüfen, dass DNS auf den Ingress-Controller zeigt - TLS-Zertifikate prüfen: kubectl get certificates -n basebox

GPU nicht verfügbar: - GPU-Operator prüfen: kubectl get pods -n gpu-operator - Knoten-Labels prüfen: kubectl get nodes -L nvidia.com/gpu - GPU-Scheduling prüfen: kubectl describe nodes | grep -A5 "nvidia.com/gpu"

Debug-Befehle

# Get all resources in namespace
kubectl get all -n basebox

# Describe pod for events and status
kubectl describe pod -n basebox <pod-name>

# Check resource usage
kubectl top pods -n basebox
kubectl top nodes

# View events
kubectl get events -n basebox --sort-by='.lastTimestamp'

# Test internal connectivity
kubectl run -it --rm debug --image=busybox --restart=Never -n basebox -- sh
# Inside pod:
wget -O- http://aisrv:8888/health
wget -O- http://inference:8000/health

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