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

// installation

Updates

Applies to

Product: Server · Audience: Platform Operator

Updating basebox with Helm: read the changelog, back up, render before applying, upgrade in a maintenance window, database migrations, verification – and what a rollback requires. Plus the updates below basebox: operating system, drivers, Kubernetes. There are no automatic updates; security and feature updates are announced by e-mail and release notes, installation is up to the operator.

Current stable release

Chart basebox.ai 0.3.32 → basebox 1.8.8. History: Version matrix.

How a basebox upgrade runs

1. Read

Changelog and release notes of the target version: new features, changed defaults, migration notes, new environment variables. Check whether your values files need adjusting (e.g. new connector values or renamed keys).

2. Back up

Dump or CloudNativePG backup of aisrv-db (and the other databases), secrets, values files, helm list -n basebox – see Backup & restore. Optionally AISRV_DB_MIGRATE_BACKUP: "true" with a persistent AISRV_DB_MIGRATE_BACKUP_DIR.

3. Render

helm template basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version <target-chart-version> \
  --namespace basebox \
  -f values.customer.yaml -f values.mcp.yaml \
  > /tmp/basebox-rendered.yaml

grep -nE 'image:|host:|nvidia.com/|name: inference' /tmp/basebox-rendered.yaml

Check: new image tags plausible, ingress host unchanged, GPU requests as before, external inference still without an inference deployment.

4. Upgrade

In the maintenance window, with the same values files as at installation:

helm upgrade basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version <target-chart-version> \
  --namespace basebox \
  --reset-then-reuse-values \
  --wait \
  --timeout 120m \
  --values values.customer.yaml \
  --values values.mcp.yaml

--reset-then-reuse-values adopts the new chart defaults (image versions) and keeps your overrides. Pass all values files the installation uses. The chart updates in the right order – databases (for schema changes), backend services, IDP, inference, frontend.

5. Migrations

AISRV and storesrv migrate their databases on start if AISRV_DB_MIGRATE / STORESRV_DB_MIGRATE are true: migrations are embedded, numbered (Vnnn__name), applied sequentially, tracked in _migrations_history and validated by checksum. Watch:

kubectl -n basebox logs -l app.kubernetes.io/name=aisrv -f | grep -i migrat

Migrations are forward-only. basebox 1.8.6 adds the AISRV migration V32; returning to an older version requires restoring the AISRV backup from before the upgrade together with the earlier Helm release.

6. Verify

helm list -n basebox                               # new chart/app version
kubectl -n basebox get pods                        # all Running, no restarts
kubectl -n basebox get deployments -o wide         # new images

Then: login, chat, one RAG answer, one upload, "About" shows the new version – the short form of Validate installation. Inference needs minutes to warm up after a restart.

7. Record

Update the manifest: chart, app, image digests, date, who. Inform the administrators; they see changes in the changelog.

Rollback

Only with a backup:

helm rollback basebox <revision> -n basebox or helm upgrade … --version <old-chart-version> with the old values.
If database migrations were applied, first restore the databases from the backup taken before the upgrade (see Backup & restore), then start the old release.
Verify as above.

Without a backup, a rollback after migrations is not possible – hence step 2.

Updates below basebox

Component	Procedure	Caution
Ubuntu	`sudo apt update && sudo apt upgrade -y`; `unattended-upgrades` for security updates	Kernel updates → plan a reboot; the NVIDIA driver must match the kernel
NVIDIA driver	`sudo apt install --upgrade nvidia-driver-<version>`	Check compatibility with CUDA version and vLLM; test in non-production first; check MIG layout after reboot
CUDA	Only if the inference runtime requires it	Mind the driver/toolkit matrix
Kubernetes	kubeadm upgrade path, one minor version per step	Kubernetes documentation; cluster backup (etcd) beforehand
GPU Operator	`helm upgrade` in the `gpu-operator` namespace	Keep driver container vs. host driver consistent
CloudNativePG operator	`helm upgrade` in `cnpg-system`	Release notes; database backups beforehand
Ingress controller, cert-manager	Per their documentation	Check annotations and ClusterIssuer

Rule: one layer per maintenance window, acceptance check afterwards. Clean-up: sudo apt autoremove -y; docker system prune only with care.

Air-gapped environments

Transfer the images of the target version and any new model artefacts into the mirror beforehand; check helm template against the mirror; models with HF_HUB_OFFLINE=1. Agree the transfer procedure with support@basebox.ai.

Operation by basebox

basebox announces release, time and impact, backs up, upgrades in the approved window and reports with manifest – procedure under Operation by basebox.

Next step: Scaling