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

basebox - Using Helm Charts

Install basebox from the OCI Helm registry with one command.

Use this page for real domains, cert-manager based TLS, or customer-managed TLS secrets.

Current stable release

The basebox.ai chart version is 0.3.32 and deploys Basebox 1.8.8 components.

To deploy optional in-cluster connector services, see Deploy MCP Connectors with Helm.

If basebox will use an LLM on a separate GPU server, read Deployment Topologies first. The basebox application cluster can be CPU-only when all GPU workloads are placed elsewhere or configured in CPU mode.

Looking for the shortest local install path?

If you want a single-node basebox.local evaluation install with local/self-managed TLS defaults, use Local Quick Start.

Prerequisites

  • Kubernetes cluster already prepared
  • kubectl and helm installed on your workstation
  • CloudNativePG operator installed on the cluster
  • ingress controller installed on the cluster
  • NVIDIA GPU support installed on nodes that run inference or GPU-mode RAG services; it is not required on a CPU-only application cluster using external inference
  • DNS for your public hostname already points to the ingress IP
  • cert-manager installed and a ClusterIssuer available if you use global.tls.mode=cert-manager

Registry Credentials

The OCI chart is published at oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai.

If OCI pull or registry login requires credentials, use username pacman with this token:

ee4d3d1bad18cae07a1817701d2281f6fbf8aa2f

TLS Modes

The chart behavior is controlled by global.tls.mode.

local

  • local/self-managed TLS
  • AISRV uses JWKS file mode
  • intended for local evaluation and internal installs

cert-manager

  • cert-manager manages the ingress TLS secret
  • AISRV uses normal JWKS URL mode
  • recommended for public domains

existing-secret

  • you provide the ingress TLS secret yourself
  • AISRV uses normal JWKS URL mode
  • use this when the customer already manages TLS

The hostname itself is not the differentiator, e.g. basebox.internal can use local or existing-secret. What matters is the TLS trust model.

Step 1: Set Kubeconfig

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

Step 2: Optional OCI Registry Login

helm registry login gitea.basebox.health -u pacman

If anonymous OCI pull works in your environment, this step is optional.

Step 3: Install with cert-manager

Example for a public domain using cert-manager:

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

What this does:

  • installs all basebox services and databases
  • creates bootstrap secrets automatically
  • configures ingress for kubetest.bbox-dev.de
  • asks cert-manager to issue the TLS certificate
  • configures OIDC for the same external hostname

Step 4: Install with an Existing TLS Secret

If the customer already provides a TLS 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

Requirements for this mode:

  • secret customer-tls already exists in namespace basebox
  • certificate matches global.domain

Step 5: Watch Certificate State (cert-manager mode)

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

Expected:

  • ingress host matches your configured domain
  • certificate resources move to ready state

k3s DNS Issues

If you are using k3s, please see this FAQ item to avoid DNS issues.

Step 6: Check Pods and Bootstrap Job

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

Expected:

  • service pods become Running
  • idp-keycloak-bootstrap completes successfully

Step 7: Get Login Credentials

Primary UI login:

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 password:

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

Step 8: 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 }"}'

Expected response:

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

Open in browser:

https://kubetest.bbox-dev.de

Minimal Values-File Alternative

If you prefer a values file instead of many --set flags:

# 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

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

Upgrade an Existing Installation

Before upgrading, create and verify a backup of the AISRV database and retain the values files used for the installation.

Upgrade with the new chart defaults and the existing installation values:

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

Add every other values file used by the installation, such as the optional MCP connector values file. --reset-then-reuse-values adopts the Basebox 1.8.8 image defaults while retaining existing installation overrides.

Basebox 1.8.6 adds AISRV database migration V32. Returning to an AISRV version older than 1.8.6 requires restoring the matching pre-upgrade AISRV database backup together with the earlier Helm release.

Troubleshooting

  • 404 on the public hostname:
  • check DNS and ingress host alignment
  • certificate not issued:
  • check ClusterIssuer, ACME reachability, and ingress address
  • login callback error:
  • confirm the external hostname is the same in global.domain
  • GraphQL returns HTML instead of JSON:
  • check ingress rules and host mapping
  • image pulls fail on cluster nodes:
  • check registry pull access from the runtime, not only from your workstation