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

// installation

basebox installieren

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Installation des basebox-Umbrella-Charts mit Ihrer Values-Datei. Diese Seite ordnet die Schritte in den Bare-Metal-Pfad ein; der kanonische Leitfaden mit allen Optionen ist Helm Charts verwenden, die Chart-Referenz die Helm-Chart-Übersicht.

Aktuelles stabiles Release

Chart basebox.ai 0.3.32 stellt basebox 1.8.8 bereit.

Voraussetzungen aus den vorigen Schritten

Cluster bereit: Knoten Ready, Ingress-Controller, Standard-Storage-Class, CloudNativePG, GPU Operator mit angebotenen GPU-Ressourcen
DNS zeigt auf die Ingress-IP; TLS-Modus entschieden (Secret oder ClusterIssuer vorhanden)
kubectl und helm auf der Workstation, KUBECONFIG gesetzt
Registry-Zugang geprüft; Zugangsdaten für den OCI-Login unter Helm Charts verwenden → Voraussetzungen

1. Values-Datei anlegen

Minimal für Produktion – Domain, TLS, Admin-E-Mail:

# values.customer.yaml
global:
  domain: basebox.customer.internal
  tls:
    mode: existing-secret          # oder cert-manager / local
    secretName: customer-tls       # bei cert-manager: Name des zu erzeugenden Secrets
    # clusterIssuer: letsencrypt-prod   # nur bei cert-manager

quickstart:
  adminEmail: admin@basebox.customer.internal

Ergänzen Sie nach Bedarf – jeweils in eigenen Dateien, damit Sie sie beim Upgrade wieder anwenden:

Ergänzung	Datei	Seite
GPU-Ressourcen der Dienste (komplette GPU vs. MIG), Storage Class, Datenbankgrößen	`values.customer.yaml`	Service-Modelle bereitstellen · Speicher
Externe Inferenz statt gebündeltem vLLM	`values.external-inference.yaml`	Inferenz anbinden
MCP-Konnektoren	`values.mcp.yaml`	MCP-Konnektoren mit Helm
SMTP, Frontend-Optionen (Support-Link, Übersetzungs-App)	`values.customer.yaml`	AISRV · Frontend

Zwingend zu ändern gegenüber Standardwerten: Domain, TLS, Passwörter (das Chart erzeugt Bootstrap-Secrets automatisch – nutzen Sie sie, statt eigene Klartextwerte zu setzen), GPU-Zuteilungen, Storage Class. Zugangsdaten gehören in Kubernetes-Secrets, referenziert per valueFrom.secretKeyRef, nicht in die Values.

helm registry login gitea.basebox.health -u pacman

Funktioniert der anonyme OCI-Pull, ist der Schritt optional.

3. Rendern und prüfen

Vor der Installation rendern – so sehen Sie Ingress-Host, TLS-Secret, GPU-Requests und ob ein inference-Deployment enthalten ist:

helm template basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  --namespace basebox \
  -f values.customer.yaml \
  > /tmp/basebox-rendered.yaml

grep -nE 'host:|secretName|nvidia.com/|name: inference' /tmp/basebox-rendered.yaml

4. Installieren

helm upgrade --install basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  -n basebox \
  --create-namespace \
  --wait \
  --timeout 120m \
  -f values.customer.yaml

Weitere Values-Dateien mit zusätzlichen -f. helm upgrade --install installiert, wenn das Release nicht existiert, und aktualisiert sonst. Der lange Timeout ist gewollt: Modell-Downloads und Bootstrap brauchen Zeit.

Was dabei geschieht: Namespace, alle Dienste und PostgreSQL-Cluster werden angelegt, Bootstrap-Secrets erzeugt, Ingress und OIDC für global.domain konfiguriert, das TLS-Secret angelegt bzw. bei cert-manager angefordert.

5. Pods und Bootstrap-Job prüfen

kubectl -n basebox get pods -w
kubectl -n basebox wait --for=condition=complete job/idp-keycloak-bootstrap --timeout=10m
kubectl -n basebox get cluster            # CNPG-Cluster
kubectl -n basebox get ingress

Erwartet: Dienst-Pods Running, idp-keycloak-bootstrap Complete, Ingress-Host = global.domain. inference und ragsrv-support brauchen beim ersten Start mehrere Minuten (Modell-Download); beobachten Sie kubectl logs -n basebox -l app.kubernetes.io/name=inference -f.

6. Anmeldedaten holen

kubectl -n basebox get secret basebox-admin-secret -o jsonpath='{.data.ADMIN_EMAIL}' | base64 -d && echo
kubectl -n basebox get secret basebox-admin-secret -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d && echo
kubectl -n basebox get secret keycloak-admin-secret -o jsonpath='{.data.KEYCLOAK_ADMIN_PASSWORD}' | base64 -d && echo

Übergeben Sie E-Mail und Passwort des ersten Administrators sicher (Passwortmanager) an die Person, die die Anwendung einrichtet; sie ändert das Passwort beim ersten Login. Das Keycloak-Admin-Passwort bleibt beim Betrieb.

7. Smoke-Checks

curl -k -X POST "https://<domain>/graphql" \
  -H 'Content-Type: application/json' \
  -H 'X-Realm: primary' \
  --data-binary '{"query":"query { __typename }"}'
# erwartet: {"data":{"__typename":"Query"}}

Dann im Browser https://<domain> öffnen und sich mit dem Administratorkonto anmelden.

Häufige Fehlerbilder

Symptom	Lösung
`404` auf dem Hostname	DNS und Ingress-Host vergleichen
Zertifikat wird nicht ausgestellt	`kubectl -n basebox get certificate,certificaterequest,order,challenge`; ClusterIssuer, ACME-Erreichbarkeit
Login-Callback scheitert, Weiterleitungsschleife	`global.domain` = externer Hostname? Browserdaten löschen; FAQ
GraphQL liefert HTML	Ingress-Regeln und Host-Zuordnung
Image-Pulls scheitern	Registry-Zugang aus der Runtime der Knoten prüfen
Pods `Pending`	GPU-Ressourcen, PVCs, Taints – Troubleshooting

Bestehende Installation aktualisieren

Vor jedem Upgrade die AISRV-Datenbank sichern. Dann mit denselben Values-Dateien und --reset-then-reuse-values aktualisieren – Befehle und der Hinweis zur Migration V32 (basebox 1.8.6) unter Helm Charts verwenden → Bestehende Installation aktualisieren und Updates.

Festhalten

Chart- und App-Version (helm list -n basebox), verwendete Values-Dateien (ohne Secrets, in Git), Image-Digests (kubectl -n basebox get deployments -o wide).

Nächster Schritt: Service-Modelle bereitstellen