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

BaseBox - Quick Start Guide

Get your BaseBox up and running in minutes using OCI Helm registry.

Prerequisites

Kubernetes cluster (1.24+)
kubectl configured
Helm 3.8+ installed (OCI support required)
Ingress controller (nginx recommended)
Storage provisioner

Step 1: Install CloudNativePG Operator

# Add CloudNativePG Helm repository
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm repo update

# Install the operator
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg

# Verify installation
kubectl wait --for=condition=Available --timeout=300s \
  deployment/cnpg-cloudnative-pg \
  -n cnpg-system

Step 2: Create Database Clusters

Save this as databases.yaml:

---
# Cluster for aisrv
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: aisrv-db
spec:
  instances: 3
  storage:
    size: 10Gi
    storageClass: standard
  bootstrap:
    initdb:
      database: aisrv
      owner: aisrv
      secret:
        name: aisrv-db-secret
      postInitSQL:
        - CREATE EXTENSION IF NOT EXISTS vector;
---
apiVersion: v1
kind: Secret
metadata:
  name: aisrv-db-secret
type: kubernetes.io/basic-auth
stringData:
  username: aisrv
  password: "CHANGE_ME"
---
# Cluster for idp (Keycloak)
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: idp-db
spec:
  instances: 3
  storage:
    size: 5Gi
    storageClass: standard
  bootstrap:
    initdb:
      database: keycloak
      owner: keycloak
      secret:
        name: idp-db-secret
---
apiVersion: v1
kind: Secret
metadata:
  name: idp-db-secret
type: kubernetes.io/basic-auth
stringData:
  username: keycloak
  password: "CHANGE_ME"
---
# Cluster for storesrv
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: storesrv-db
spec:
  instances: 3
  storage:
    size: 10Gi
    storageClass: standard
  bootstrap:
    initdb:
      database: storesrv
      owner: storesrv
      secret:
        name: storesrv-db-secret
---
apiVersion: v1
kind: Secret
metadata:
  name: storesrv-db-secret
type: kubernetes.io/basic-auth
stringData:
  username: storesrv
  password: "CHANGE_ME"

Apply the databases:

kubectl apply -f databases.yaml

# Wait for clusters to be ready
kubectl wait --for=condition=Ready --timeout=600s cluster/aisrv-db
kubectl wait --for=condition=Ready --timeout=600s cluster/idp-db
kubectl wait --for=condition=Ready --timeout=600s cluster/storesrv-db

Step 3: Configure Your Values

Create my-values.yaml and customize for your environment:

global:
  storageClass: "standard"  # Change to your storage class
  baseUrl: "https://basebox.example.com"  # Change to your domain
  domain: "basebox.example.com"  # Change to your domain

  ingress:
    enabled: true
    className: "nginx"
    tls:
      enabled: true
      secretName: basebox-tls  # Change to your TLS secret name
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"  # Add if using cert-manager
      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/enable-cors: "true"
      nginx.ingress.kubernetes.io/cors-allow-origin: "https://basebox.example.com"
      nginx.ingress.kubernetes.io/cors-allow-credentials: "true"

  database:
    port: 5432
    password: "CHANGE_ME"  # IMPORTANT: Change this!

  oauth:
    idpUrl: "http://idp:8080/realms/master"
    idpAud: "account"
    jwksUrl: "https://idp:8080/realms/master/protocol/openid-connect/certs"

database:
  enabled: true

idp:
  ingress:
    paths:
      - path: /auth
        pathType: Prefix

aisrv:
  database:
    host: aisrv-db-rw
    user: aisrv
    dbname: aisrv
  ingress:
    paths:
      - path: /graphql
        pathType: Exact
      - path: /subscriptions
        pathType: Exact
      - path: /media
        pathType: Prefix

storesrv:
  logLevel: info  # Change to 'trace' for debugging
  host: "0.0.0.0"
  port: "8889"
  database:
    host: storesrv-db-rw
    user: storesrv
    dbname: storesrv
  graphql:
    allowIntrospection: true
    graphiql: true

ragsrv:
  enabled: true

ragsrv-support:
  enabled: true

inference:
  enabled: false  # Enable if you have GPU nodes

frontend:
  ingress:
    paths:
      - path: /
        pathType: Prefix

Step 4: Install BaseBox from OCI Registry

Since BaseBox charts are hosted in an OCI registry, you reference them directly without adding a repository.

Install the Complete Platform (Umbrella Chart)

# Install latest version
helm upgrade --install basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --namespace basebox \
  --create-namespace \
  --values my-values.yaml \
  --wait \
  --timeout 10m

# Or install specific version
helm upgrade --install basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 1.2.3 \
  --namespace basebox \
  --create-namespace \
  --values my-values.yaml \
  --wait \
  --timeout 10m

Step 5: Verify Installation

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

# Check ingress
kubectl get ingress -n basebox

# Check database clusters
kubectl get clusters -n basebox

# Check all resources
kubectl get all -n basebox

Step 6: Access Your Installation

Once all pods are running, access your installation at:

Frontend: https://basebox.example.com
GraphQL API: https://basebox.example.com/graphql

Default admin credentials (change after first login): - Username: admin - Password: Check your Keycloak configuration

Working with OCI Charts

View Chart Information

# Show chart details
helm show chart oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai

# Show all chart information (values, readme, etc.)
helm show all oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai

# Show default values
helm show values oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai

Pull Charts Locally

# Pull chart to local directory
helm pull oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai

# Pull and extract
helm pull oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai --untar

# Template the chart locally (without installing)
helm template basebox oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --values my-values.yaml > rendered-manifests.yaml

Update Your Installation

# Upgrade to latest version
helm upgrade basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --namespace basebox \
  --values my-values.yaml \
  --wait

# Upgrade to specific version
helm upgrade basebox \
  oci://gitea.basebox.health/basebox-distribution/helm/basebox.ai \
  --version 1.2.4 \
  --namespace basebox \
  --values my-values.yaml \
  --wait

Troubleshooting

Pods not starting

# Check pod status
kubectl describe pod <pod-name> -n basebox

# Check logs
kubectl logs <pod-name> -n basebox

# Check events
kubectl get events -n basebox --sort-by='.lastTimestamp'

Database connection issues

# Check database cluster status
kubectl get cluster -n basebox
kubectl describe cluster aisrv-db -n basebox

# Check database pods
kubectl get pods -l cnpg.io/cluster=aisrv-db -n basebox

# Test database connectivity
kubectl run -it --rm debug --image=postgres:16 --restart=Never -n basebox -- \
  psql -h aisrv-db-rw -U aisrv -d aisrv

Ingress not working

# Check ingress controller
kubectl get pods -n ingress-nginx

# Check ingress resources
kubectl describe ingress -n basebox

# Check TLS certificate (if using cert-manager)
kubectl get certificate -n basebox
kubectl describe certificate basebox-tls -n basebox

Helm installation issues

# List installed releases
helm list -n basebox

# Get release status
helm status basebox -n basebox

# Get release history
helm history basebox -n basebox

# Rollback if needed
helm rollback basebox 1 -n basebox

Database Connection Endpoints

Your applications connect to these endpoints:

aisrv database:
Read-Write: aisrv-db-rw:5432
Read-Only: aisrv-db-ro:5432
idp database:
Read-Write: idp-db-rw:5432
Read-Only: idp-db-ro:5432
storesrv database:
Read-Write: storesrv-db-rw:5432
Read-Only: storesrv-db-ro:5432

Next Steps

Configure SSL/TLS: Set up cert-manager for automatic certificate management
Update Passwords: Change all default passwords in production
Enable Monitoring: Set up Prometheus and Grafana for monitoring
Configure Backup: Set up database backups using CloudNativePG backup features
Scale Resources: Adjust replica counts and resource limits based on usage
Review Security: Configure network policies and RBAC

Important Security Notes

⚠️ Before going to production:

✅ Change all default passwords
✅ Enable proper TLS certificates (not self-signed)
✅ Configure proper network policies
✅ Set up backup and disaster recovery
✅ Review and adjust resource limits
✅ Configure proper authentication and authorization
✅ Enable audit logging
✅ Rotate image pull secrets regularly