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.

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 the cluster for inference and RAG services
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

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.19 \
  -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.19 \
  -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

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.19 \
  -n basebox \
  --create-namespace \
  --wait \
  --timeout 120m \
  -f values.customer.yaml

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

BaseBox - Using Helm Charts

Prerequisites

TLS Modes

local

cert-manager

existing-secret