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

// installation

basebox components

Applies to

Product: Server (Cloud for understanding) · Audience: Platform Operator

The services a basebox installation consists of – frontend, AISRV, storesrv, ragsrv and ragsrv-support, identity provider, databases, inference, connectors –, what each does, which layer it belongs to and how they communicate. The umbrella chart basebox.ai deploys them together.

Component map

flowchart TB
  U["Users / API clients"] -->|HTTPS| ING["Ingress / TLS"]
  ING --> FE["frontend<br/>Vue 3 · :3000"]
  ING --> AISRV["AISRV<br/>GraphQL · REST · OpenAI API · MCP gateway · :8888"]
  ING --> IDP["idp (Keycloak)<br/>OIDC · /auth · :8080"]
  FE -->|GraphQL| AISRV
  FE -->|OIDC| IDP
  AISRV -->|token verification| IDP
  AISRV --> STORE["storesrv<br/>GraphQL · :8889"]
  AISRV -->|RAG API| RAG["ragsrv<br/>vector DB · :3001"]
  RAG --> RAGS["ragsrv-support<br/>extraction · OCR · embeddings · STT · :8000"]
  AISRV -->|OpenAI-compatible| INF["inference<br/>vLLM · :8000"]
  AISRV -->|POST /mcp| MCP["MCP connectors<br/>mcp-&lt;name&gt;"]
  MCP --> EXT["target systems · search provider"]
  AISRV --- DB1[("aisrv-db")]
  STORE --- DB2[("storesrv-db")]
  RAG --- DB3[("ragsrv-db<br/>pgvector")]
  IDP --- DB4[("idp-db")]
  CNPG["CloudNativePG operator"] -.-> DB1 & DB2 & DB3 & DB4
  style FE fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style AISRV fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style STORE fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style IDP fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
  style RAG fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c
  style RAGS fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c
  style INF fill:#dbeafe,stroke:#1e40af,color:#1d1e1c

Beige = basebox platform · green = service models · blue = inference. The layers are explained in Understand the architecture.

The services

Service Layer Task Port Dependencies Reference
frontend Platform Vue 3 single-page application; talks GraphQL to AISRV, OIDC to Keycloak 3000 AISRV, IDP Frontend
AISRV Platform Application server: chat orchestration, apps, users/organisations, GraphQL API, REST and OpenAI-compatible API, MCP gateway, audit log, SMTP, media 8888 aisrv-db, IDP, inference, ragsrv, storesrv AISRV
storesrv Platform Store service (GraphQL) for persistence 8889 storesrv-db, IDP Storesrv
idp (Keycloak) Platform Identity provider: realms, users, OIDC tokens, LDAP federation, identity brokering 8080 idp-db IDP (Keycloak)
ragsrv Service models RAG server: document ingestion, chunking, embeddings, semantic search; PostgreSQL with pgvector 3001 ragsrv-db, ragsrv-support, GPU (or CPU mode) Ragsrv
ragsrv-support Service models Model service for document extraction, OCR, embeddings, speech-to-text 8000 GPU (or CPU mode) Ragsrv-Support
inference Inference Bundled LLM inference server (vLLM), OpenAI-compatible API 8000 GPU Inference Server
MCP connectors Platform (optional) One deployment + service mcp-<name> per connector; reach exactly their target system per connector AISRV MCP connectors with Helm
CloudNativePG operator Platform Manages the PostgreSQL clusters aisrv-db, storesrv-db, ragsrv-db, idp-db (image postgresql:16-standard-bookworm) – Storage class Helm chart overview
Ingress / TLS Platform Entry point; paths /, /graphql, /rest, /subscriptions, /media, /auth, /v1 443 Ingress controller, certificate Using Helm charts

Communication paths

From → to Protocol Purpose
Browser → frontend, AISRV, idp HTTPS via ingress Interface, GraphQL/subscriptions, login
API client → AISRV HTTPS /v1/…, /rest/… OpenAI-compatible and REST API
frontend → idp OIDC Sign-in, tokens (VITE_BB_OIDC_DOMAIN, ends with /auth/realms/)
AISRV → idp HTTP internal (AISRV_OIDC_IDP_URL) Token verification, user synchronisation
AISRV → inference OpenAI-compatible API (AISRV_LLM_URL, API key) Chat completions; alternatively an external endpoint
AISRV → ragsrv RAG API (AISRV_RAG_URL, X-API-KEY) Knowledge bases, retrieval
ragsrv → ragsrv-support HTTP (SUPPORT_SERVICE_URL, shared API_KEY) Extraction, OCR, embeddings, STT
ragsrv → AISRV Webhook (WEBHOOK_STATE_URL) File processing status
AISRV → storesrv GraphQL (AISRV_STORE_URL) Persistence
AISRV → MCP connector POST /mcp with the user's Authorization Tool calls
MCP connector → target system system-specific, allowed hosts only Wiki, tickets, IMAP, search provider
AISRV → SMTP STARTTLS/TLS Invitations, notifications
Services → PostgreSQL TCP 5432 (*-db-rw) State

Users and browsers never talk directly to inference, ragsrv or the connectors – only via AISRV.

What is stored where

Data Location
Users, organisations, apps, settings, audit log, connector credentials (write-only) aisrv-db
Store server persistence storesrv-db
Document sections and embeddings of the knowledge bases ragsrv-db (pgvector)
Identities, realms, clients idp-db
Uploaded files / media AISRV_MEDIA_ROOT (persistent volume) and temporarily /tmp/ragsrv
Model weights and caches Volumes of inference (/data/.cache/huggingface) and ragsrv-support (/models) – recreatable
Secrets Kubernetes secrets (aisrv-database, keycloak-admin-secret, basebox-admin-secret, …)

Details for backup and security: Backup & restore · Storage (security).

Resource profile per component

  • GPU: only inference, ragsrv and ragsrv-support (the latter two can also run in CPU mode).
  • CPU/RAM-heavy: AISRV, Keycloak, PostgreSQL clusters.
  • Light: frontend, storesrv, MCP connectors.

Chart guidelines: minimum 5+ cores, 12 GB+ RAM, 1+ GPU, 200 GB+ storage; recommended 10+ cores, 32 GB+ RAM, 2+ GPUs, 500 GB+ SSD/NVMe – see Helm chart overview. What grows with users, documents and model size: Resources & scaling.

Next step: Helm chart overview