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

// installation

basebox – Helm Charts verwenden

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

basebox mit einem Befehl aus der OCI-Helm-Registry installieren.

Nutzen Sie diese Seite für echte Domains, TLS über cert-manager oder kundenverwaltete TLS-Secrets.

Aktuelles stabiles Release

Die Chart-Version von basebox.ai ist 0.3.32 und stellt Komponenten von basebox 1.8.8 bereit.

Zur Bereitstellung optionaler Konnektor-Dienste im Cluster siehe MCP-Konnektoren mit Helm bereitstellen.

Soll basebox ein LLM auf einem separaten GPU-Server nutzen, lesen Sie zuerst Deployment-Topologien. Der basebox-Anwendungscluster kann rein CPU-basiert sein, wenn alle GPU-Workloads woanders liegen oder im CPU-Modus konfiguriert sind.

Sie suchen den kürzesten lokalen Installationsweg?

Für eine Einzelknoten-Evaluierungsinstallation basebox.local mit lokalen/selbst verwalteten TLS-Standards nutzen Sie den Lokalen Schnellstart.

Voraussetzungen

  • Kubernetes-Cluster bereits vorbereitet
  • kubectl und helm auf Ihrer Workstation installiert
  • CloudNativePG-Operator im Cluster installiert
  • Ingress-Controller im Cluster installiert
  • NVIDIA-GPU-Unterstützung auf den Knoten, die Inferenz oder RAG-Dienste im GPU-Modus ausführen; auf einem reinen CPU-Anwendungscluster mit externer Inferenz nicht erforderlich
  • DNS für Ihren öffentlichen Hostname zeigt bereits auf die Ingress-IP
  • cert-manager installiert und ein ClusterIssuer verfügbar, wenn Sie global.tls.mode=cert-manager nutzen

Registry-Zugangsdaten

Das OCI-Chart ist unter oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai veröffentlicht.

Erfordern OCI-Pull oder Registry-Login Zugangsdaten, verwenden Sie den Benutzernamen pacman mit diesem Token:

ee4d3d1bad18cae07a1817701d2281f6fbf8aa2f

TLS-Modi

Das Verhalten des Charts wird über global.tls.mode gesteuert.

local

  • lokales/selbst verwaltetes TLS
  • AISRV nutzt den JWKS-Dateimodus
  • gedacht für lokale Evaluierung und interne Installationen

cert-manager

  • cert-manager verwaltet das Ingress-TLS-Secret
  • AISRV nutzt den normalen JWKS-URL-Modus
  • empfohlen für öffentliche Domains

existing-secret

  • Sie stellen das Ingress-TLS-Secret selbst bereit
  • AISRV nutzt den normalen JWKS-URL-Modus
  • nutzen Sie diesen Modus, wenn Sie TLS bereits selbst verwalten

Der Hostname selbst ist nicht das Unterscheidungsmerkmal; basebox.internal kann z. B. local oder existing-secret nutzen. Entscheidend ist das TLS-Vertrauensmodell.

Schritt 1: Kubeconfig setzen

export KUBECONFIG="<PATH_TO_KUBECONFIG>"
kubectl cluster-info
kubectl get nodes

Schritt 2: Optionaler OCI-Registry-Login

helm registry login gitea.basebox.health -u pacman

Funktioniert der anonyme OCI-Pull in Ihrer Umgebung, ist dieser Schritt optional.

Schritt 3: TLS-Konfiguration wählen

Wählen Sie genau eine der folgenden Optionen. Führen Sie nicht beide Helm-Befehle aus. helm upgrade --install installiert basebox, wenn das Release noch nicht existiert, und aktualisiert das bestehende Release, wenn es existiert.

Option A: cert-manager verwenden

Nutzen Sie diese Option, wenn cert-manager installiert ist und der Cluster einen passenden ClusterIssuer hat. cert-manager erzeugt und erneuert das Kubernetes-TLS-Secret mit dem Namen aus global.tls.secretName.

helm upgrade --install basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  -n basebox \
  --create-namespace \
  --wait \
  --timeout 120m \
  --set global.domain=kubetest.bbox-dev.de \
  --set global.tls.mode=cert-manager \
  --set global.tls.clusterIssuer=letsencrypt-prod \
  --set global.tls.secretName=kubetest-bbox-dev-de-tls \
  --set quickstart.adminEmail=admin@kubetest.bbox-dev.de

Was dabei geschieht:

  • alle basebox-Dienste und Datenbanken werden installiert
  • Bootstrap-Secrets werden automatisch erzeugt
  • der Ingress wird für kubetest.bbox-dev.de konfiguriert
  • cert-manager wird um Ausstellung des TLS-Zertifikats gebeten
  • OIDC wird für denselben externen Hostname konfiguriert

Option B: Bestehendes TLS-Secret verwenden

Nutzen Sie diese Option, wenn Sie Zertifikat und privaten Schlüssel bereits haben.

Ein Kubernetes-TLS-Secret ist ein Secret vom Typ kubernetes.io/tls. Es enthält das Zertifikat in tls.crt und den privaten Schlüssel in tls.key. Das Secret muss im selben Namespace wie basebox liegen, und sein Name muss global.tls.secretName entsprechen.

Legen Sie zum Beispiel den Namespace basebox und ein Secret customer-tls an:

kubectl create namespace basebox --dry-run=client -o yaml | kubectl apply -f -

kubectl -n basebox create secret tls customer-tls \
  --cert=<PATH_TO_TLS_CERTIFICATE> \
  --key=<PATH_TO_TLS_PRIVATE_KEY>

Installieren oder aktualisieren Sie basebox dann mit diesem Secret:

helm upgrade --install basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  -n basebox \
  --create-namespace \
  --wait \
  --timeout 120m \
  --set global.domain=basebox.customer.internal \
  --set global.tls.mode=existing-secret \
  --set global.tls.secretName=customer-tls \
  --set quickstart.adminEmail=admin@basebox.customer.internal

Anforderungen für diesen Modus:

  • das Secret customer-tls existiert bereits im Namespace basebox
  • der Secret-Typ ist kubernetes.io/tls, und es enthält tls.crt und tls.key
  • das Zertifikat ist für global.domain gültig

Schritt 4: TLS-Konfiguration prüfen

Prüfen Sie in beiden TLS-Modi, dass der Ingress Ihren konfigurierten Hostname nutzt:

kubectl -n basebox get ingress

Haben Sie Option A (cert-manager) gewählt, beobachten Sie die Zertifikatsressourcen:

kubectl -n basebox get certificate,certificaterequest,order,challenge

Erwartet:

  • die Zertifikatsressourcen erreichen den Zustand ready

Haben Sie Option B (existing-secret) gewählt, prüfen Sie den Secret-Typ:

kubectl -n basebox get secret customer-tls -o jsonpath='{.type}{"\n"}'

Erwartet:

kubernetes.io/tls

In beiden Modi muss der Ingress-Host global.domain entsprechen.

k3s-DNS-Probleme

Wenn Sie k3s verwenden, beachten Sie diesen FAQ-Eintrag, um DNS-Probleme zu vermeiden.

Schritt 5: Pods und Bootstrap-Job prüfen

kubectl -n basebox get pods
kubectl -n basebox wait --for=condition=complete job/idp-keycloak-bootstrap --timeout=10m

Erwartet:

  • Dienst-Pods werden Running
  • idp-keycloak-bootstrap wird erfolgreich abgeschlossen

Schritt 6: Anmeldedaten holen

Login für die Oberfläche:

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

Keycloak-Admin-Passwort:

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

Schritt 7: Smoke-Checks

curl -k -X POST "https://kubetest.bbox-dev.de/graphql" \
  -H 'Content-Type: application/json' \
  -H 'X-Realm: primary' \
  --data-binary '{"query":"query { __typename }"}'

Erwartete Antwort:

{"data":{"__typename":"Query"}}

Im Browser öffnen:

https://kubetest.bbox-dev.de

Alternative: minimale Values-Datei

Wenn Sie eine Values-Datei vielen --set-Flags vorziehen:

# values.customer.yaml
global:
  domain: kubetest.bbox-dev.de
  tls:
    mode: cert-manager
    clusterIssuer: letsencrypt-prod
    secretName: kubetest-bbox-dev-de-tls

quickstart:
  adminEmail: admin@kubetest.bbox-dev.de

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

Bestehende Installation aktualisieren

Erstellen und prüfen Sie vor dem Upgrade ein Backup der AISRV-Datenbank und bewahren Sie die für die Installation verwendeten Values-Dateien auf.

Verwenden Sie denselben TLS-Modus und dieselben Einstellungen wie die bestehende Installation. Enthält values.customer.yaml zum Beispiel die oben gezeigte cert-manager-Konfiguration, aktualisieren Sie mit den neuen Chart-Standards und dieser Values-Datei:

helm upgrade basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  --namespace basebox \
  --reset-then-reuse-values \
  --wait \
  --timeout 120m \
  --values values.customer.yaml

Verwalten Sie die cert-manager-Einstellungen direkt auf der Kommandozeile statt in einer Values-Datei, nutzen Sie:

helm upgrade basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 0.3.32 \
  --namespace basebox \
  --reset-then-reuse-values \
  --wait \
  --timeout 120m \
  --set global.domain=<YOUR_DOMAIN> \
  --set global.tls.mode=cert-manager \
  --set global.tls.clusterIssuer=<YOUR_CLUSTER_ISSUER> \
  --set global.tls.secretName=<YOUR_TLS_SECRET_NAME>

global.tls.secretName ist hier das Secret, das cert-manager erzeugt und erneuert; Sie legen dieses Secret nicht manuell an.

Fügen Sie jede weitere von der Installation verwendete Values-Datei hinzu, etwa die optionale Values-Datei für MCP-Konnektoren. --reset-then-reuse-values übernimmt die Image-Standards von basebox 1.8.8 und behält bestehende Installations-Overrides bei.

basebox 1.8.6 ergänzt die AISRV-Datenbankmigration V32. Eine Rückkehr zu einer AISRV-Version älter als 1.8.6 erfordert die Wiederherstellung des passenden AISRV-Datenbank-Backups von vor dem Upgrade zusammen mit dem früheren Helm-Release.

Troubleshooting

  • 404 auf dem öffentlichen Hostname:
  • DNS und Ingress-Host auf Übereinstimmung prüfen
  • Zertifikat wird nicht ausgestellt:
  • ClusterIssuer, ACME-Erreichbarkeit und Ingress-Adresse prüfen
  • Fehler beim Login-Callback:
  • bestätigen, dass der externe Hostname in global.domain derselbe ist
  • GraphQL liefert HTML statt JSON:
  • Ingress-Regeln und Host-Zuordnung prüfen
  • Image-Pulls auf Cluster-Knoten scheitern:
  • Registry-Pull-Zugang aus der Runtime prüfen, nicht nur von Ihrer Workstation