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

// installation

Install basebox

Applies to

Product: Server · Audience: Platform Operator

Installing the basebox umbrella chart with your values file. This page places the steps within the bare-metal path; the canonical guide with all options is Using Helm charts, the chart reference the Helm chart overview.

Current stable release

Chart basebox.ai 0.3.32 deploys basebox 1.8.8.

Prerequisites from the previous steps

  • Cluster ready: nodes Ready, ingress controller, default storage class, CloudNativePG, GPU Operator with advertised GPU resources
  • DNS points to the ingress IP; TLS mode decided (secret or ClusterIssuer present)
  • kubectl and helm on the workstation, KUBECONFIG set
  • Registry access checked; credentials for the OCI login under Using Helm charts → Prerequisites

1. Create the values file

Minimal for production – domain, TLS, admin e-mail:

# values.customer.yaml
global:
  domain: basebox.customer.internal
  tls:
    mode: existing-secret          # or cert-manager / local
    secretName: customer-tls       # with cert-manager: name of the secret to be created
    # clusterIssuer: letsencrypt-prod   # cert-manager only

quickstart:
  adminEmail: admin@basebox.customer.internal

Add as needed – each in its own file so you can apply them again on upgrade:

Addition File Page
GPU resources of the services (whole GPU vs. MIG), storage class, database sizes values.customer.yaml Deploy service models · Storage
External inference instead of bundled vLLM values.external-inference.yaml Connect inference
MCP connectors values.mcp.yaml MCP connectors with Helm
SMTP, frontend options (support link, translation app) values.customer.yaml AISRV · Frontend

Must be changed from defaults: domain, TLS, passwords (the chart generates bootstrap secrets automatically – use them instead of setting your own clear-text values), GPU allocations, storage class. Credentials belong in Kubernetes secrets, referenced via valueFrom.secretKeyRef, not in the values.

2. Optional: registry login

helm registry login gitea.basebox.health -u pacman

If anonymous OCI pull works, this step is optional.

3. Render and check

Render before installing – this shows you ingress host, TLS secret, GPU requests and whether an inference deployment is included:

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. Install

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

Further values files with additional -f. helm upgrade --install installs if the release does not exist and upgrades otherwise. The long timeout is intentional: model downloads and bootstrap take time.

What happens: namespace, all services and PostgreSQL clusters are created, bootstrap secrets generated, ingress and OIDC configured for global.domain, the TLS secret created or, with cert-manager, requested.

5. Check pods and bootstrap job

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 clusters
kubectl -n basebox get ingress

Expected: service pods Running, idp-keycloak-bootstrap Complete, ingress host = global.domain. inference and ragsrv-support need several minutes on first start (model download); watch kubectl logs -n basebox -l app.kubernetes.io/name=inference -f.

6. Retrieve credentials

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

Hand over the first administrator's e-mail and password securely (password manager) to the person setting up the application; they change the password on first login. The Keycloak admin password stays with operations.

7. Smoke checks

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

Then open https://<domain> in the browser and sign in with the administrator account.

Common failure patterns

Symptom Solution
404 on the hostname Compare DNS and ingress host
Certificate not issued kubectl -n basebox get certificate,certificaterequest,order,challenge; ClusterIssuer, ACME reachability
Login callback fails, redirect loop global.domain = external hostname? Clear browser data; FAQ
GraphQL returns HTML Ingress rules and host mapping
Image pulls fail Check registry access from the nodes' runtime
Pods Pending GPU resources, PVCs, taints – Troubleshooting

Upgrading an existing installation

Back up the AISRV database before every upgrade. Then upgrade with the same values files and --reset-then-reuse-values – commands and the note on migration V32 (basebox 1.8.6) under Using Helm charts → Upgrading an existing installation and Updates.

Record

Chart and app version (helm list -n basebox), values files used (without secrets, in Git), image digests (kubectl -n basebox get deployments -o wide).

Next step: Deploy service models