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

// installation

basebox Helm charts

Applies to

Product: Server · Audience: Platform Operator

The basebox umbrella chart is a Helm chart that bundles all basebox AI platform services into a single deployment. It orchestrates the deployment of frontend, backend services, databases, identity provider, and inference services.

Terms of Use

By using this software (i.e. pulling container images and/or deploying), you agree to the terms of use and privacy policy of basebox.

Architecture

The umbrella chart deploys the following services:

Service	Purpose	Port	Dependencies
Frontend	Vue 3 web application	3000	AISRV, IDP
IDP	Keycloak identity provider	8080	PostgreSQL (idp-db)
AISRV	Main API server (GraphQL)	8888	PostgreSQL (aisrv-db), IDP, Inference, RAGSRV
STORESRV	Store server (GraphQL)	8889	PostgreSQL (storesrv-db), IDP
RAGSRV	RAG vector database service	3001	PostgreSQL (ragsrv-db), RAGSRV-Support, GPU
RAGSRV-Support	RAG model inference service	8000	GPU
Inference	LLM inference server	8000	GPU
CNPG Operator	CloudNativePG database operator	N/A	-

Prerequisites

Kubernetes Cluster Requirements

Kubernetes Version: 1.23 or later
Helm Version: 3.x
GPU Support: NVIDIA GPU Operator or similar (for inference and RAG services)
Ingress Controller: Any
Storage: Dynamic volume provisioning with a default storage class

Resource Requirements

Minimum Production Deployment: - CPU: 5+ cores - Memory: 12GB+ RAM - GPU: 1+ NVIDIA GPUs (1 for inference) - Storage: 200GB+ for databases and model caching

Recommended Production Deployment: - CPU: 10+ cores - Memory: 32GB+ RAM - GPU: 2+ NVIDIA GPUs (1 for inference, 1 for RAGSRV) - Storage: 500GB+ SSD/NVMe

External Dependencies

Image Registry: Access to gitea.basebox.health/basebox-distribution/
Domain/DNS: Configured DNS for the application domain
TLS Certificates: Valid certificates for HTTPS (via cert-manager pre-created or other means)

Global Configuration

Service Configuration

CloudNativePG Operator

Parameter	Default	Description
`cnpg-operator.fullnameOverride`	`cnpg`	Name override for CNPG operator

IDP (Keycloak)

Parameter	Default	Description
`idp.ingress.enabled`	`true`	Enable ingress for IDP
`idp.ingress.className`	`nginx`	Ingress class name
`idp.ingress.hosts[].host`	Required	Hostname for IDP
`idp.ingress.hosts[].paths[].path`	`/auth`	Base path for Keycloak
`idp.ingress.tls`	`[]`	TLS configuration

Key Annotations: - Proxy buffer sizes configured for large headers - CORS enabled for cross-origin requests - Cache disabled for authentication flows - Long timeouts for SSO operations (86400s)

AISRV

Parameter	Default	Description
`aisrv.database.enabled`	`true`	Enable PostgreSQL database
`aisrv.database.host`	`aisrv-db-rw`	Database host
`aisrv.database.port`	`5432`	Database port
`aisrv.database.user`	`aisrv`	Database username
`aisrv.database.password`	Required	Database password (use secure value)
`aisrv.database.dbname`	`aisrv`	Database name
`aisrv.ingress.enabled`	`true`	Enable ingress

Exposed Paths: - /rest - application endpoints (including token management) - /graphql - GraphQL API endpoint - /subscriptions - GraphQL subscriptions (WebSocket) - /media - Media file serving - /stream/message-of-day - Message-of-the-day stream - /v1 - OpenAI-compatible API endpoints

STORESRV

Parameter	Default	Description
`storesrv.logLevel`	`trace`	Logging level
`storesrv.host`	`0.0.0.0`	Server bind address
`storesrv.port`	`8889`	Server port
`storesrv.oauth.IdpUrl`	`http://idp:8080/realms/master`	OAuth IDP URL
`storesrv.oauth.IdpAud`	`account`	OAuth audience
`storesrv.database.enabled`	`true`	Enable PostgreSQL database
`storesrv.graphql.allowIntrospection`	`true`	Allow GraphQL introspection
`storesrv.graphql.graphiql`	`true`	Enable GraphiQL interface

RAGSRV

Parameter	Default	Description
`ragsrv.enabled`	`true`	Enable RAGSRV service
`ragsrv.resources.requests.nvidia.com/gpu`	`1`	Number of GPUs to request
`ragsrv.resources.limits.nvidia.com/gpu`	`1`	Maximum GPUs
`ragsrv.env.COMPUTE`	`gpu`	Compute mode (`gpu` or `cpu`)

Note: RAGSRV-Support is automatically enabled when RAGSRV is enabled.

RAGSRV-Support

Parameter	Description

This service is deployed automatically with RAGSRV.

Inference

Parameter	Default	Description
`inference.enabled`	`true`	Enable inference service
`inference.resources.requests.nvidia.com/gpu`	`1`	Number of GPUs to request
`inference.resources.limits.nvidia.com/gpu`	`1`	Maximum GPUs

Frontend

Parameter	Default	Description
`frontend.ingress.enabled`	`true`	Enable ingress
`frontend.ingress.hosts[].path`	`/`	Serve frontend at root path

The frontend is configured with the same proxy and CORS settings as other services.

Ingress Configuration

Common Ingress Annotations

All services use consistent nginx ingress annotations:

Proxy Configuration

nginx.ingress.kubernetes.io/proxy-body-size: "20m"
nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
nginx.ingress.kubernetes.io/proxy-busy-buffers-size: "256k"
nginx.ingress.kubernetes.io/client-header-buffer-size: "16k"
nginx.ingress.kubernetes.io/large-client-header-buffers: "4 16k"
nginx.ingress.kubernetes.io/proxy-read-timeout: "86400"
nginx.ingress.kubernetes.io/proxy-send-timeout: "86400"
nginx.ingress.kubernetes.io/proxy-buffering: "off"

Purpose: - Large body size (20MB) for file uploads - Large buffer sizes for authentication headers (JWT tokens) - Long timeouts (24h) for WebSocket connections - Buffering disabled for streaming responses

Cache Control

nginx.ingress.kubernetes.io/Cache-Control: "no-store, no-cache, must-revalidate, proxy-revalidate"
nginx.ingress.kubernetes.io/Pragma: "no-cache"
nginx.ingress.kubernetes.io/Expires: "0"
nginx.ingress.kubernetes.io/Surrogate-Control: "no-store"

Purpose: Prevent caching of API responses and authentication flows

CORS Configuration

nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-origin: "*"
nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, OPTIONS"
nginx.ingress.kubernetes.io/cors-allow-headers: "Authorization, Content-Type, X-Realm"
nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
nginx.ingress.kubernetes.io/cors-max-age: "86400"

Purpose: Enable cross-origin requests for SPA frontend

Configuration Examples

Minimal Production Configuration

global:
  domain: basebox.company.com
  tls:
    mode: cert-manager
    clusterIssuer: letsencrypt-prod
    secretName: basebox-company-tls

cnpg-operator:
  fullnameOverride: cnpg

idp:
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: basebox.company.com
        paths:
          - path: /auth
            pathType: Prefix

aisrv:
  database:
    enabled: true
    password: "<generate-secure-password>"
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: basebox.company.com
        paths:
          - path: /rest
            pathType: Prefix
          - path: /graphql
            pathType: Exact
          - path: /subscriptions
            pathType: Exact
          - path: /media
            pathType: Prefix
          - path: /stream/message-of-day
            pathType: Exact
          - path: /v1
            pathType: Prefix

storesrv:
  logLevel: info
  database:
    enabled: true
    password: "<generate-secure-password>"
  graphql:
    allowIntrospection: false
    graphiql: false

ragsrv:
  enabled: true
  resources:
    requests:
      nvidia.com/gpu: 1
    limits:
      nvidia.com/gpu: 1
  env:
    COMPUTE: gpu

ragsrv-support:

inference:
  enabled: true
  resources:
    requests:
      nvidia.com/gpu: 1
    limits:
      nvidia.com/gpu: 1

frontend:
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: basebox.company.com
        paths:
          - path: /
            pathType: Prefix

Installation

Prepare Values File

Critical values to change: - All database passwords - Domain names - TLS secret names - Image pull secrets - GPU resource allocations - Storage class names

Install the Chart

# Install basebox umbrella chart
helm install basebox ./basebox.ai \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace \
  --timeout 30m

# Watch the deployment
kubectl get pods -n basebox -w

Verify Installation

# Check all pods are running
kubectl get pods -n basebox

# Check database clusters
kubectl get cluster -n basebox

# Check ingress
kubectl get ingress -n basebox

# Check GPU allocation
kubectl describe nodes | grep -A5 "Allocated resources"

Upgrade

Upgrades run with helm upgrade against the OCI chart, with the same values files as at installation and --reset-then-reuse-values; back up the AISRV database first. The complete procedure (read, back up, render, upgrade, migrations, verify, rollback) is described in Updates; the commands and the note on migration V32 are under Using Helm charts → Upgrade an existing installation.

Uninstall

Complete Removal

# Uninstall chart
helm uninstall basebox --namespace basebox

# Delete PVCs (databases - DATA LOSS!)
kubectl delete pvc -n basebox --all

# Delete namespace
kubectl delete namespace basebox

Preserve Data

To preserve databases when uninstalling:

# Uninstall chart
helm uninstall basebox --namespace basebox

# PVCs remain - do not delete them
# To reinstall with existing data:
helm install basebox ./basebox.ai \
  --values values-production.yaml \
  --namespace basebox

Backup

What needs to be backed up, dumps, restore and retention are described in Backup & restore. Chart-specific is the configuration of automated CloudNativePG backups in the values:

aisrv:
  aisrv-db:
    cluster:
      backup:
        barmanObjectStore:
          destinationPath: s3://backups/aisrv
          s3Credentials:
            accessKeyId:
              name: backup-s3-creds
              key: ACCESS_KEY_ID
            secretAccessKey:
              name: backup-s3-creds
              key: SECRET_ACCESS_KEY
        retentionPolicy: "30d"

Monitoring and logs

Health endpoints, alerts and log analysis are described in Monitoring and Logging. Chart-specific is enabling the Prometheus metrics in the values:

aisrv:
  metrics:
    enabled: true
    port: 9090

idp:
  idp-db:
    cluster:
      monitoring:
        enablePodMonitor: true

Troubleshooting

Failure patterns and debug commands are under Troubleshooting and in the FAQ.

Security Considerations

Resource Allocation

Backend Services (AISRV, STORESRV):

resources:
  requests:
    cpu: 1000m
    memory: 2Gi
  limits:
    cpu: 2000m
    memory: 4Gi

GPU Services (Inference, RAGSRV):

resources:
  requests:
    cpu: 4000m
    memory: 32Gi
    nvidia.com/gpu: 1
  limits:
    cpu: 8000m
    memory: 64Gi
    nvidia.com/gpu: 1

Databases:

cluster:
  instances: 3
  storage:
    size: 50Gi
    storageClass: fast-ssd

Database Performance

Use read replicas (increase instances)
Use fast storage (SSD/NVMe)
Tune PostgreSQL parameters
Regular VACUUM and ANALYZE

Next step: Using Helm charts · Services: AISRV