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

// installation

Storage

Applies to

Product: Server · Audience: Platform Operator

Persistent storage for model artefacts, documents and platform data: storage classes, capacity planning and backup hooks. basebox needs no exotic storage – but enough of it, fast enough for databases, and a clear separation between what must be backed up and what can be recreated.

What is persistent

Data Where Default size in the chart Back up?
AISRV database – users, organisations, apps, settings, audit log, connector credentials CloudNativePG cluster aisrv-db 10 Gi Yes – the most important
storesrv database storesrv-db 10 Gi Yes
ragsrv database – document sections and embeddings (pgvector) ragsrv-db 5 Gi Yes (or re-ingest knowledge bases)
Keycloak database – identities, realms, clients idp-db 5 Gi Yes
Media / uploads AISRV_MEDIA_ROOT (persistent volume) – Yes
Temporary RAG files /tmp/ragsrv (e.g. PVC ragsrv-shared-storage) – No
Inference model weights PVC inference-models under /data/.cache/huggingface 200 Gi in the example No – reloadable (air-gapped: keep a mirror)
Service model models PVC ragsrv-support-models under /models 20–50 Gi in the example No – reloadable
Caches (Numba, Triton) /data (emptyDir or PVC) 50 Gi in the example No
Secrets Kubernetes secrets (aisrv-database, keycloak-admin-secret, basebox-admin-secret, …) – Yes – etcd backup or export

Storage class

  • Dynamic provisioning is mandatory; the chart creates PVCs.
  • Evaluation: local-path (default in the local quick start).
  • Production: a storage class on SSD/NVMe (the service pages call it fast-ssd as an example) – database IOPS and model load times depend directly on it. Snapshots or replication at storage level are a plus but do not replace database backups.
  • Access mode: most volumes are ReadWriteOnce. A temp volume shared by ragsrv and ragsrv-support (/tmp/ragsrv, nfs-shared in the example) needs ReadWriteMany if both pods run on different nodes – on a single node RWO suffices.
kubectl get storageclass
kubectl get pvc -n basebox

Capacity planning

Chart guidelines: 200 GB+ minimum, 500 GB+ SSD/NVMe recommended, 1 TB+ when models are kept locally. More concretely:

Item Rule of thumb
Inference model weights Size of the model in the chosen quantisation (e.g. ~60 GB GPT-OSS 120B MXFP4, ~70 GB Llama 3.3 70B FP8, ~16 GB GPT-OSS 20B) plus room for a second model when switching
Service models 20–50 GB for embedding, OCR and STT models
Databases In production 20–50 Gi per cluster instead of the 5–10 Gi defaults; ragsrv-db grows with the number of document sections
Media Sum of files uploaded to knowledge bases and chats; depends on the limits administrators set per organisation
Shared memory /dev/shm with 64 GB in the verified configuration for loading large models
Reserve 20–30 % for growth, backups before upgrades, migration backups (AISRV_DB_MIGRATE_BACKUP_DIR)

Set sizes in the values, e.g.:

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

Backup hooks

Two complementary paths:

Database dumps per cluster:

kubectl exec -n basebox aisrv-db-1 -- pg_dump -U aisrv aisrv > aisrv-backup.sql

CloudNativePG backups to S3-compatible storage, configured in the values (backup.barmanObjectStore, retentionPolicy: "30d") – example on the Helm chart overview. Plus back up the media volume and secrets. The whole procedure, including restore and testing: Backup & restore.

Back up before every upgrade

Database migrations (such as V32 from basebox 1.8.6) are forward-only. Without a backup of the AISRV database there is no way back.

Air-gapped environments

Without internet access, model weights are loaded onto the PVCs in advance (download job or copy) and inference runs with HF_HUB_OFFLINE: "1"; example under Inference Server → Offline configuration. Plan storage for a local model and image mirror.

Verify

kubectl get pvc -n basebox                 # all Bound
kubectl get cluster -n basebox             # CNPG clusters healthy
df -h /dev/shm                             # shared memory
kubectl exec -n basebox deploy/aisrv -- df -h   # media volume mounted

Next step: Networking