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

// installation

Installation paths

Applies to

Product: Server · Audience: Platform Operator

Starting from bare metal vs. starting with an existing Kubernetes cluster; what each path requires and where both converge. Plus two cross-cutting decisions that come up on both paths: evaluation or production, and bundled or external inference.

The two paths

flowchart LR
  subgraph BM["Path A: from bare metal"]
    OS["Operating system<br/>Ubuntu 24.04 LTS"] --> NV["NVIDIA driver<br/>CUDA · container toolkit"] --> K8S["Kubernetes<br/>GPU Operator · ingress · storage · CNPG"]
  end
  subgraph EX["Path B: existing Kubernetes"]
    REQ["Cluster meets the<br/>chart requirements"]
  end
  K8S --> HELM["basebox via Helm<br/>umbrella chart basebox.ai"]
  REQ --> HELM
  HELM --> MODEL["Choose and<br/>connect a model"] --> VAL["Validate installation"]
  style HELM fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c
Path A: from bare metal Path B: existing Kubernetes
Starting point An empty server (or several) A cluster you already operate
You install Operating system, NVIDIA stack, Kubernetes, cluster components, then basebox Only basebox – after checking the requirements
Guide Bare-metal installation with the Server Preparation Guide Using Helm charts
Typical for Reference configurations, FAST LTA systems, dedicated appliance Organisations with a Kubernetes platform and GPU nodes
Duration Hours to a day including OS and drivers Under an hour if the requirements are met

Both paths converge at helm upgrade --install basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai. From there on everything is identical.

Path A: from bare metal

The end-to-end path, step by step: Requirements → Prepare the server (OS, drivers, CUDA, Docker, Kubernetes, GPU Operator) → NVIDIA / GPU → Kubernetes → Storage → Networking → Install basebox → Deploy service models → Connect inference → Validate installation.

Verified with Ubuntu 24.04 LTS, NVIDIA driver 580.126.09, CUDA 13.0, Kubernetes 1.33.7, Helm 3.20.0 (February 2026).

Path B: existing Kubernetes

The cluster must meet what the chart requires:

  • Kubernetes 1.23+, Helm 3.x
  • Dynamic volume provisioning with a default storage class
  • An ingress controller (nginx annotations are prepared in the chart) and a TLS path: cert-manager with a ClusterIssuer, an existing TLS secret or local trust
  • CloudNativePG operator for the PostgreSQL clusters
  • NVIDIA GPU Operator (or equivalent) on the nodes running inference or service models in GPU mode; configured accordingly for mixed MIG layouts
  • Registry access to gitea.basebox.health from the nodes' container runtime – or mirrored images
  • Sufficient resources: minimum 5+ cores, 12 GB+ RAM, 1+ GPU, 200 GB+; recommended 10+ cores, 32 GB+ RAM, 2+ GPUs, 500 GB+ SSD/NVMe

If these are met, continue directly with Using Helm charts. If something is missing – usually the GPU Operator or CloudNativePG – add it following the respective steps of the bare-metal path.

Cross-cutting decision 1: evaluation or production

Local quick start Production installation
Hostname basebox.local Your domain
TLS Local, self-signed (global.tls.mode=local) cert-manager or existing secret
Purpose Demonstration, validation, first local installation Production
Guide Local quick start Using Helm charts

The quick start is explicitly not intended for production.

Cross-cutting decision 2: bundled or external inference

Bundled External
What The chart deploys inference (vLLM) on the same cluster inference.enabled: false; AISRV talks to a separate OpenAI-compatible endpoint
When Single-node reference configurations Separate GPU host, other cluster, other security zone; CPU-only application server
Guide Connect inference Deployment topologies with a proven vLLM example

In both cases users talk only to the platform, never directly to inference.

Air-gapped environments

Without internet access, both paths need an offline transfer of container images and model artefacts (internal image mirror, pre-loaded models with HF_HUB_OFFLINE=1). Agree the procedure with support@basebox.ai. What works in air-gapped operation and what does not: Air-gapped environments.

What follows the installation on both paths

  1. Get credentials from basebox-admin-secret and keycloak-admin-secret.
  2. Smoke checks: pods Running, bootstrap job complete, GraphQL responds, login in the browser.
  3. Check the model – inference reachable, model identifier matches /v1/models.
  4. Acceptance following Validate installation: chat, RAG, OCR, STT once each, reboot test.
  5. Handover to the administrators – from now on the application is set up under Administration.

Next step: Bare-metal installation or Using Helm charts