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

// installation

Lokaler Schnellstart (basebox.local)

Gilt für

Produkt: Server (Evaluierung) · Zielgruppe: Platform Operator

Dies ist der kürzeste Evaluierungsweg für basebox auf einem vorbereiteten Einzelknoten-Kubernetes-Cluster.

Nutzen Sie diesen Modus für Vorführungen, Validierung, interne Tests und erste lokale Installationen.

Nicht für den Produktivbetrieb

Die Schnellstart-Installation ist nicht für den Produktiveinsatz gedacht.

Eine produktionsreife Installation beschreibt Helm Charts verwenden.

Was installiert wird

  • ein Hostname: basebox.local
  • lokaler/selbst verwalteter TLS-Modus
  • automatische Bootstrap-Secrets
  • automatische Datenbank-Cluster
  • automatischer OIDC-Bootstrap
  • lokale Standard-Storage-Class: local-path

Das ist eine Schnellstart-Topologie, keine Produktionstopologie.

Für öffentliche Domains, cert-manager oder kundeneigenes TLS nutzen Sie Helm Charts verwenden.

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 im Cluster für Inferenz- und RAG-Dienste installiert
  • der Browser der Workstation löst basebox.local auf Ihre Ingress- oder Knoten-IP auf

Schritt 1: Kubeconfig setzen

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

Schritt 2: basebox.local auf den Cluster zeigen lassen

Fügen Sie auf der Workstation, auf der Sie den Browser öffnen, einen /etc/hosts-Eintrag hinzu:

sudo sh -c 'printf "\n<INGRESS_OR_NODE_IP> basebox.local\n" >> /etc/hosts'

Prüfen:

ping basebox.local

Schritt 3: Optionaler OCI-Registry-Login

helm registry login gitea.basebox.health -u pacman
# If this prompts for a password, use ee4d3d1bad18cae07a1817701d2281f6fbf8aa2f

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

Schritt 4: basebox 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

Was dabei geschieht:

  • der Namespace basebox wird angelegt
  • Bootstrap-Zugangsdaten werden automatisch erzeugt
  • das lokale TLS-Secret wird automatisch angelegt, falls es noch nicht existiert
  • der vollständige basebox-Stack wird installiert
  • OIDC wird für https://basebox.local konfiguriert

Schritt 5: Auf Pods und Bootstrap-Job warten

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

Die Standard-E-Mail ist in der Regel:

admin@basebox.local

Schritt 7: Smoke-Checks

kubectl -n basebox get ingress

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

Erwartete Antwort:

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

Im Browser öffnen:

https://basebox.local

Hinweis zum Zertifikat

Standardmäßig erzeugt der lokale Modus automatisch ein selbstsigniertes TLS-Secret.

Das reicht für Installation und Backend-OIDC-Bootstrap, Ihr Browser zeigt aber eine Zertifikatswarnung, solange Sie das Secret nicht durch ein lokal vertrauenswürdiges Zertifikat ersetzen.

Wollen Sie ein vertrauenswürdiges lokales Browser-Zertifikat, legen Sie basebox-local-tls vor der Installation selbst an, zum Beispiel mit mkcert. Das Chart behält das bestehende Secret und überschreibt es nicht.

Troubleshooting

  • https://basebox.local/graphql liefert 404:
  • /etc/hosts und Ingress-IP auf Übereinstimmung prüfen
  • Inferenz-Pod bleibt Pending:
  • GPU-Ressourcenverfügbarkeit auf dem Knoten prüfen
  • Browser-Anmeldeseite scheitert nach der Installation:
  • prüfen, dass basebox.local auf denselben Ingress auflöst, auf dem installiert wurde
  • Image-Pulls auf Cluster-Knoten scheitern:
  • Registry-Zugang der Runtime auf Knotenseite prüfen