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

// installation

Installationswege

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Start ab Bare Metal vs. Start mit bestehendem Kubernetes-Cluster; was jeder Weg voraussetzt und wo beide zusammenlaufen. Dazu zwei Querentscheidungen, die auf beiden Wegen anstehen: Evaluierung oder Produktion, und gebündelte oder externe Inferenz.

Die zwei Wege

flowchart LR
  subgraph BM["Weg A: ab Bare Metal"]
    OS["Betriebssystem<br/>Ubuntu 24.04 LTS"] --> NV["NVIDIA-Treiber<br/>CUDA · Container Toolkit"] --> K8S["Kubernetes<br/>GPU Operator · Ingress · Storage · CNPG"]
  end
  subgraph EX["Weg B: bestehendes Kubernetes"]
    REQ["Cluster erfüllt die<br/>Chart-Anforderungen"]
  end
  K8S --> HELM["basebox per Helm<br/>Umbrella-Chart basebox.ai"]
  REQ --> HELM
  HELM --> MODEL["Modell wählen<br/>und anbinden"] --> VAL["Installation prüfen"]
  style HELM fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c

	Weg A: ab Bare Metal	Weg B: bestehendes Kubernetes
Ausgangspunkt	Ein leerer Server (oder mehrere)	Ein Cluster, den Sie bereits betreiben
Sie installieren	Betriebssystem, NVIDIA-Stack, Kubernetes, Cluster-Komponenten, dann basebox	Nur basebox – nach Prüfung der Anforderungen
Leitfaden	Bare-Metal-Installation mit dem Server Preparation Guide	Helm Charts verwenden
Typisch für	Referenzkonfigurationen, FAST-LTA-Systeme, dedizierte Appliance	Organisationen mit Kubernetes-Plattform und GPU-Knoten
Dauer	Stunden bis ein Tag inklusive OS und Treiber	Unter einer Stunde, wenn die Anforderungen erfüllt sind

Beide Wege laufen bei helm upgrade --install basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai zusammen. Ab dort ist alles identisch.

Weg A: ab Bare Metal

Der durchgängige Pfad, Schritt für Schritt: Voraussetzungen → Server vorbereiten (OS, Treiber, CUDA, Docker, Kubernetes, GPU Operator) → NVIDIA / GPU → Kubernetes → Speicher → Netzwerk → basebox installieren → Service-Modelle bereitstellen → Inferenz anbinden → Installation prüfen.

Geprüft mit Ubuntu 24.04 LTS, NVIDIA-Treiber 580.126.09, CUDA 13.0, Kubernetes 1.33.7, Helm 3.20.0 (Februar 2026).

Weg B: bestehendes Kubernetes

Der Cluster muss erfüllen, was das Chart verlangt:

Kubernetes 1.23+, Helm 3.x
Dynamische Volume-Bereitstellung mit einer Standard-Storage-Class
Ein Ingress-Controller (nginx-Annotationen sind im Chart vorbereitet) und ein TLS-Weg: cert-manager mit ClusterIssuer, ein bestehendes TLS-Secret oder lokales Vertrauen
CloudNativePG-Operator für die PostgreSQL-Cluster
NVIDIA GPU Operator (oder Vergleichbares) auf den Knoten, die Inferenz oder Service-Modelle im GPU-Modus ausführen; bei gemischten MIG-Layouts entsprechend konfiguriert
Registry-Zugang zu gitea.basebox.health aus der Container-Runtime der Knoten – oder gespiegelte Images
Ausreichende Ressourcen: minimal 5+ Kerne, 12 GB+ RAM, 1+ GPU, 200 GB+; empfohlen 10+ Kerne, 32 GB+ RAM, 2+ GPUs, 500 GB+ SSD/NVMe

Sind die Punkte erfüllt, geht es direkt weiter mit Helm Charts verwenden. Fehlt etwas – meist GPU Operator oder CloudNativePG –, ergänzen Sie es nach den jeweiligen Schritten des Bare-Metal-Pfads.

Querentscheidung 1: Evaluierung oder Produktion

	Lokaler Schnellstart	Produktive Installation
Hostname	`basebox.local`	Ihre Domain
TLS	Lokal, selbstsigniert (`global.tls.mode=local`)	cert-manager oder bestehendes Secret
Zweck	Vorführung, Validierung, erste lokale Installation	Produktivbetrieb
Leitfaden	Lokaler Schnellstart	Helm Charts verwenden

Der Schnellstart ist ausdrücklich nicht für den Produktivbetrieb gedacht.

Querentscheidung 2: gebündelte oder externe Inferenz

	Gebündelt	Extern
Was	Das Chart stellt `inference` (vLLM) auf demselben Cluster bereit	`inference.enabled: false`; AISRV spricht einen separaten OpenAI-kompatiblen Endpunkt an
Wann	Einzelknoten-Referenzkonfigurationen	Separater GPU-Host, anderer Cluster, andere Sicherheitszone; reiner CPU-Anwendungsserver
Leitfaden	Inferenz anbinden	Deployment-Topologien mit erprobtem vLLM-Beispiel

Nutzer sprechen in beiden Fällen nur mit der Plattform, nie direkt mit der Inferenz.

Abgeschottete Umgebungen

Ohne Internetzugang brauchen beide Wege einen Offline-Transfer von Container-Images und Modellartefakten (interner Image-Mirror, vorab geladene Modelle mit HF_HUB_OFFLINE=1). Das Verfahren stimmen Sie mit support@basebox.ai ab. Was im abgeschotteten Betrieb funktioniert und was nicht: Air-Gapped-Umgebungen.

Was nach der Installation auf beiden Wegen folgt

Anmeldedaten holen aus basebox-admin-secret und keycloak-admin-secret.
Smoke-Checks: Pods Running, Bootstrap-Job abgeschlossen, GraphQL antwortet, Login im Browser.
Modell prüfen – Inferenz erreichbar, Modellbezeichner stimmt mit /v1/models überein.
Abnahme nach Installation prüfen: Chat, RAG, OCR, STT je einmal, Neustart-Test.
Übergabe an die Administratoren – die Anwendung wird ab jetzt unter Administration eingerichtet.

Nächster Schritt: Bare-Metal-Installation oder Helm Charts verwenden