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

AISRV

Overview

AISRV is the main AI server that provides a GraphQL API for the basebox AI application. It handles user authentication via OpenID Connect (OIDC/Keycloak), connects to a PostgreSQL database, and integrates with LLM providers, RAG services, Whisper transcription, and other external services.

Important: The server is designed to run behind a reverse proxy (e.g., nginx) and does not provide TLS support on its own. Configure your reverse proxy or ingress controller to handle TLS/SSL termination.

Deployment

AISRV is deployed via Helm chart to Kubernetes clusters with an integrated PostgreSQL database managed by CloudNativePG.

Helm Chart Configuration

Basic Settings

Parameter	Default	Description
replicaCount	1	Number of AISRV pod replicas
image.repository	gitea.basebox.health/basebox-distribution/aisrv	Container image repository
image.pullPolicy	IfNotPresent	Image pull policy
image.tag	latest	Image tag to deploy
fullnameOverride	aisrv	Override the full name of the deployment

Service Configuration

Parameter	Default	Description
service.type	ClusterIP	Kubernetes service type
service.port	8888	Service port

Resource Management

Parameter	Description
resources.requests	CPU/memory resource requests
resources.limits	CPU/memory resource limits
autoscaling.enabled	Enable horizontal pod autoscaling
autoscaling.minReplicas	Minimum number of replicas
autoscaling.maxReplicas	Maximum number of replicas
autoscaling.targetCPUUtilizationPercentage	Target CPU for scaling

Health Checks

Parameter	Description
livenessProbe	Liveness probe configuration
readinessProbe	Readiness probe configuration

Database Configuration

Database Settings

Parameter	Default	Description
database.enabled	true	Enable database creation
database.imageName	ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm	PostgreSQL image
database.host	aisrv-db-rw	Database host (read-write service)
database.port	5432	Database port
database.user	aisrv	Database username
database.password	<secure-password>	Database password
database.name	aisrv	Database name
database.sslMode	disable	Database SSL mode (disable, require, verify-full)

CloudNativePG Cluster Settings

Parameter	Default	Description
aisrv-db.cluster.instances	1	Number of PostgreSQL instances
aisrv-db.cluster.storage.size	10Gi	Storage size for database
aisrv-db.cluster.storage.storageClass	default	Storage class to use
aisrv-db.cluster.monitoring.enablePodMonitor	false	Enable Prometheus monitoring

Migration Settings

Variable	Default	Description
AISRV_DB_MIGRATE	false	Automatic database migration on startup
AISRV_DB_MIGRATE_BACKUP	false	Backup database before migrations
AISRV_DB_MIGRATE_BACKUP_DIR	migrations-backups	Backup directory path
AISRV_DB_MIGRATE_RUN_ONLY	false	Run only migrations then exit

Environment Variables

Server Configuration

Variable	Default	Description
AISRV_HOST	0.0.0.0	Host or IP address to listen on
AISRV_PORT	8888	Port to listen on
AISRV_LOG_LEVEL	info	Log level (trace, debug, info, warn, error)
AISRV_SET_CORS_HEADERS	true	Set CORS headers (disable when using reverse proxy)
AISRV_DEBUG_MODE	false	Debug mode: send errors verbatim to client
AISRV_ON_PREMISE	false	On-premise deployment mode
AISRV_DO_ON_PREMISE_INIT	false	On-premise initialization
AISRV_METRICS_PORT	None	Metrics port (Prometheus)

Database Connection (from Secrets)

Variable	Source	Description
AISRV_DB_HOST	aisrv-database secret	Database hostname
AISRV_DB_PORT	aisrv-database secret	Database port
AISRV_DB_USER	aisrv-database secret	Database username
AISRV_DB_PASSWORD	aisrv-database secret	Database password
AISRV_DB_NAME	aisrv-database secret	Database name
AISRV_DB_SSL_MODE	Configuration	SSL mode for database connection

OIDC/Authentication Configuration

Variable	Description
AISRV_OIDC_IDP_URL	Base URL of IdP (Keycloak) server (without realm)
AISRV_OIDC_ISSUER_URL	Optional issuer URL for token validation
AISRV_OIDC_AUD	OIDC audience field contents
AISRV_OIDC_JWKS_FILEPATH	Path to OIDC JWKS file
AISRV_OIDC_SUPER_ADMIN_USER	Super admin username
AISRV_OIDC_SUPER_ADMIN_PASSWORD	Super admin password
AISRV_OIDC_SUPER_ADMIN_CLIENT_ID	Super admin client ID
AISRV_OIDC_SUPER_ADMIN_CLIENT_SECRET	Super admin client secret
AISRV_BASE_DOMAIN	Base domain for organizations (e.g., basebox.ai)
AISRV_USE_TLS	Assume HTTPS URLs (true for production)

GraphQL Configuration

Variable	Default	Description
AISRV_QUERY_DEPTH_LIMIT	6	GraphQL query depth limit
AISRV_QUERY_COMPLEXITY_LIMIT	20	GraphQL query complexity limit
AISRV_GRAPHQL_ALLOW_INTROSPECTION	false	Allow introspection queries
AISRV_GRAPHQL_APOLLO_TRACING	false	Enable Apollo tracing
AISRV_GRAPHQL_GRAPHIQL	false	Enable GraphiQL interface

LLM Configuration

Variable	Description
AISRV_LLM_URL	URL of the LLM server
AISRV_LLM_CHAT_ENDPOINT	Chat completions endpoint path
AISRV_LLM_API_KEY	API key for LLM service
AISRV_LLM_MODEL	LLM model identifier
AISRV_LLM_PROVIDER	LLM provider (determines auth scheme)
AISRV_LLM_CONTEXT_SIZE	Maximum context size in tokens
AISRV_LLM_WORD_LIMIT	Estimated word limit per request
AISRV_LLM_MAX_TOKENS	Maximum output tokens (default: 8000)
AISRV_LLM_TEMPERATURE	Sampling temperature (0-1)
AISRV_LLM_TOP_P	Nucleus sampling parameter (0-1)
AISRV_LLM_REPETITION_PENALTY	Repetition penalty (>1.0 discourages repetition)

For a physically separate vLLM server, use the secret-backed configuration in Deployment Topologies. Current releases require the provider-derived VLLM_API_KEY variable in addition to the general AISRV API-key setting.

RAG Configuration

Variable	Description
AISRV_ENABLE_RAG_API	Enable RAG endpoints
AISRV_RAG_URL	Base URL of RAG server API
AISRV_RAG_DOWNLOAD_URL	URL for RAG server to download files
AISRV_RAG_API_KEY	API key for RAG service
AISRV_MAX_RAG_FILE_SIZE	Maximum file size for uploads
AISRV_MAX_RAG_FILES_PER_APP	Maximum files per application

Whisper Configuration

Variable	Default	Description
AISRV_WHISPER_URL	http://localhost:6000/inference	Whisper service endpoint
AISRV_WHISPER_API_KEY	None	API key for Whisper service

SMTP Configuration

Variable	Description
AISRV_SMTP_HOST	SMTP server hostname
AISRV_SMTP_PORT	SMTP server port
AISRV_SMTP_USERNAME	SMTP username
AISRV_SMTP_PASSWORD	SMTP password
AISRV_SMTP_TLS_TYPE	SMTP connection type (tls, starttls)
AISRV_SENDER_EMAIL	From-email address

Media Storage Configuration

Variable	Description
AISRV_STORE_URL	URL for store server
AISRV_MEDIA_ROOT	Root directory for uploaded files
AISRV_MEDIA_URL	URL to media server root
AISRV_ENABLE_STATIC_FILES	Enable static file server

API Configuration

Variable	Default	Description
AISRV_ENABLE_REST_API	false	Enable REST API and token management

Configuration Examples

Production Configuration

# values-production.yaml
replicaCount: 3

image:
  repository: gitea.basebox.health/basebox-distribution/aisrv
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8888

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  hosts:
    - host: company.com
      paths:
        - path: /graphql
          pathType: Prefix
  tls:
    - secretName: aisrv-tls
      hosts:
        - company.com

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

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 15
  periodSeconds: 5

database:
  enabled: true
  host: aisrv-db-rw
  port: 5432
  user: aisrv
  password: "<generate-secure-password>"
  name: aisrv
  sslMode: "require"

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

env:
  # Server
  AISRV_HOST: "0.0.0.0"
  AISRV_PORT: "8888"
  AISRV_LOG_LEVEL: "info"
  AISRV_SET_CORS_HEADERS: "false"  # Using ingress
  AISRV_DEBUG_MODE: "false"
  AISRV_METRICS_PORT: "9090"
  AISRV_DO_ON_PREMISE_INIT: "true"
  AISRV_ON_PREMISE: "true"

  # Database (from secrets)
  AISRV_DB_HOST:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: host
  AISRV_DB_PORT:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: port
  AISRV_DB_USER:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: username
  AISRV_DB_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: password
  AISRV_DB_NAME:
    valueFrom:
      secretKeyRef:
        name: aisrv-database
        key: name
  AISRV_DB_SSL_MODE: "require"

  # Migrations
  AISRV_DB_MIGRATE: "true"
  AISRV_DB_MIGRATE_BACKUP: "true"
  AISRV_DB_MIGRATE_BACKUP_DIR: "/backups"

  # OIDC
  AISRV_OIDC_IDP_URL: "http://idp:8080"
  AISRV_OIDC_ISSUER_URL: "https://auth.company.com"
  AISRV_OIDC_AUD: "aisrv"
  AISRV_OIDC_SUPER_ADMIN_USER:
    valueFrom:
      secretKeyRef:
        name: aisrv-admin
        key: username
  AISRV_OIDC_SUPER_ADMIN_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: aisrv-admin
        key: password
  AISRV_BASE_DOMAIN: "company.com"
  AISRV_USE_TLS: "true"

  # GraphQL
  AISRV_QUERY_DEPTH_LIMIT: "8"
  AISRV_QUERY_COMPLEXITY_LIMIT: "50"
  AISRV_GRAPHQL_ALLOW_INTROSPECTION: "false"
  AISRV_GRAPHQL_GRAPHIQL: "false"

  # LLM
  AISRV_LLM_URL: "http://inference:8000"
  AISRV_LLM_CHAT_ENDPOINT: "/v1/chat/completions"
  AISRV_LLM_API_KEY:
    valueFrom:
      secretKeyRef:
        name: llm-credentials
        key: api-key
  AISRV_LLM_MODEL: "meta-llama/Llama-3.1-8B-Instruct"
  AISRV_LLM_PROVIDER: "openai-compatible"
  AISRV_LLM_CONTEXT_SIZE: "16000"
  AISRV_LLM_MAX_TOKENS: "4096"
  AISRV_LLM_TEMPERATURE: "0.7"

  # RAG
  AISRV_ENABLE_RAG_API: "true"
  AISRV_RAG_URL: "http://ragsrv:3001"
  AISRV_RAG_API_KEY:
    valueFrom:
      secretKeyRef:
        name: rag-credentials
        key: api-key

  # Whisper
  AISRV_WHISPER_URL: "http://whisper:6000/inference"

  # SMTP
  AISRV_SMTP_HOST: "smtp.company.com"
  AISRV_SMTP_PORT: "587"
  AISRV_SMTP_USERNAME:
    valueFrom:
      secretKeyRef:
        name: smtp-credentials
        key: username
  AISRV_SMTP_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: smtp-credentials
        key: password
  AISRV_SMTP_TLS_TYPE: "starttls"
  AISRV_SENDER_EMAIL: "noreply@company.com"

Installation

Prerequisites

• Kubernetes cluster (1.23+)
• Helm 3.x
• CloudNativePG operator installed
• Storage provisioner
• OIDC/Keycloak instance configured

Install CloudNativePG Operator

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg

Install AISRV

# Install with custom values
helm install aisrv oci://gitea.basebox.health/basebox-distribution/helm/aisrv \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Verify installation
kubectl get pods -n basebox -l app.kubernetes.io/name=aisrv
kubectl get cluster -n basebox aisrv-db

Upgrade

helm upgrade aisrv oci://gitea.basebox.health/basebox-distribution/helm/aisrv \
  --values values-production.yaml \
  --namespace basebox

Uninstall

helm uninstall aisrv --namespace basebox

# Delete PVCs if needed
kubectl delete pvc -n basebox -l cnpg.io/cluster=aisrv-db

Migrations

How Migrations Work

• Migration Tracking: _migrations_history table tracks applied migrations
• Numbered Format: Vnnn__<migration_name> (double underscores)
• Sequential Execution: Migrations run in numerical order
• Checksum Validation: Detects alterations to migration files
• Embedded: All migrations embedded in application binary

Running Migrations

Automatic on Startup:

env:
  AISRV_DB_MIGRATE: "true"
  AISRV_DB_MIGRATE_BACKUP: "true"

Migrations Only (No Server Start):

env:
  AISRV_DB_MIGRATE: "true"
  AISRV_DB_MIGRATE_RUN_ONLY: "true"

Verification

Check Deployment

# Check pods
kubectl get pods -n basebox -l app.kubernetes.io/name=aisrv

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

# View logs
kubectl logs -n basebox -l app.kubernetes.io/name=aisrv --tail=100

Test GraphQL API

# Port forward
kubectl port-forward -n basebox svc/aisrv 8888:8888

# Test query
curl -X POST http://localhost:8888/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

Integration with Other Services

IDP (Keycloak)

env:
  AISRV_OIDC_IDP_URL: "http://idp:8080"

Inference Server

env:
  AISRV_LLM_URL: "http://inference:8000"
  AISRV_LLM_CHAT_ENDPOINT: "/v1/chat/completions"

RAGSRV

env:
  AISRV_ENABLE_RAG_API: "true"
  AISRV_RAG_URL: "http://ragsrv:3001"

STORESRV

env:
  AISRV_STORE_URL: "http://storesrv:8889"

Performance Tuning

Resource Allocation

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

Database Performance

• Use read replicas (increase aisrv-db.cluster.instances)
• Fast storage (SSD/NVMe)
• Connection pooling (configured in application)

Monitoring

Metrics

Enable Prometheus metrics:

env:
  AISRV_METRICS_PORT: "9090"

Health Checks

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 15
  periodSeconds: 5

Database Monitoring

Enable CloudNativePG monitoring:

aisrv-db:
  cluster:
    monitoring:
      enablePodMonitor: true