Overview
The backend is a Node.js REST API that handles authentication, business logic, data-connector queries, and LLM orchestration. It runs on port 3000 and is exposed through Gateway API or Ingress, usually on its own API hostname.
Set CONNECT_SERVICE_URL to the in-cluster Connect service URL when connect.enabled: true, for example http://cobi-dashboard-connect:8000.
Required Secrets
Create the backend Kubernetes Secret before running helm install. The backend will crash-loop if the Secret is missing or incomplete.
kubectl create secret generic cobi-backend-secrets \
--namespace cobi \
# ── Database ─────────────────────────────────────────────────────────
--from-literal=DATABASE_URL="postgres://postgres:<password>@<pg-host>:5432/dashboard_auth?schema=public" \
--from-literal=CORE_DATABASE_URL="postgres://postgres:<password>@<pg-host>:5432/cobi_core?schema=public" \
--from-literal=ENABLE_MIGRATIONS="true" \
# ── Auth ─────────────────────────────────────────────────────────────
--from-literal=BETTER_AUTH_SECRET="<random-64-char-string>" \
--from-literal=BETTER_AUTH_URL="https://api.example.com" \
--from-literal=FRONTEND_URL="https://app.example.com" \
--from-literal=CONNECT_SERVICE_URL="http://cobi-dashboard-connect:8000" \
# ── LLM inference ────────────────────────────────────────────────────
--from-literal=AI_PROVIDER="openai" \
--from-literal=OPENAI_API_KEY="not-used" \
--from-literal=OPENAI_BASE_URL="http://cobi-dashboard-vllmstack-engine:8000/v1" \
--from-literal=DEFAULT_MODEL_ID="QuantTrio/Qwen3.5-9B-AWQ" \
--from-literal=DEFAULT_FAST_MODEL_ID="QuantTrio/Qwen3.5-9B-AWQ" \
--from-literal=DEFAULT_OCR_MODEL_ID="QuantTrio/Qwen3.5-9B-AWQ" \
# ── Vector store (Qdrant) ────────────────────────────────────────────
--from-literal=QDRANT_URL="http://cobi-dashboard-qdrant:6333" \
--from-literal=QDRANT_LOCAL_ONLY="true" \
--from-literal=QDRANT_API_KEY="" \
--from-literal=QDRANT_CLUSTER_KEY="" \
--from-literal=QDRANT_COLLECTION_PREFIX="prod_" \
# ── Object storage (MinIO or AWS S3) ─────────────────────────────────
--from-literal=S3_BUCKET="documents" \
--from-literal=S3_REGION="us-east-1" \
--from-literal=S3_ENDPOINT="http://cobi-dashboard-minio:9000" \
--from-literal=S3_ACCESS_KEY_ID="admin" \
--from-literal=S3_SECRET_ACCESS_KEY="<minio-root-password>" \
# ── Security ─────────────────────────────────────────────────────────
--from-literal=DATASOURCES_ENCRYPTION_KEY="<random-64-hex-chars>"
After the first successful deployment, change ENABLE_MIGRATIONS to "false" and re-apply the Secret. Running migrations on every pod restart is not safe in production.
Environment Variable Reference
Database
| Variable | Required | Description |
|---|
DATABASE_URL | Yes | PostgreSQL connection string for the dashboard_auth database (auth, sessions) |
CORE_DATABASE_URL | Yes | PostgreSQL connection string for the cobi_core database (application data) |
ENABLE_MIGRATIONS | Yes | Set "true" on first install to run schema migrations; "false" after |
postgres://<user>:<password>@<host>:<port>/<database>?schema=public
<release-name>-postgresql (e.g. cobi-dashboard-postgresql).
Authentication
| Variable | Required | Description |
|---|
BETTER_AUTH_SECRET | Yes | Secret key for signing session tokens. Generate with openssl rand -hex 32 |
BETTER_AUTH_URL | Yes | Public HTTPS URL of the application — used for auth callbacks and CSRF checks |
FRONTEND_URL | Yes | Public HTTPS URL of the frontend — used for redirect allowlists |
BETTER_AUTH_URL must match the public API URL. FRONTEND_URL must match the public frontend URL.
LLM Inference
| Variable | Required | Description |
|---|
AI_PROVIDER | Yes | Always "openai" — the backend uses the OpenAI-compatible API |
OPENAI_BASE_URL | Yes | Base URL of the vLLM inference service (e.g. http://cobi-dashboard-vllmstack-engine:8000/v1) |
OPENAI_API_KEY | Yes | API key. Set to any non-empty string for self-hosted vLLM (it ignores the key by default) |
DEFAULT_MODEL_ID | Yes | Model ID passed in inference requests (must match the model loaded in vLLM) |
DEFAULT_FAST_MODEL_ID | No | Model for fast/cheap requests. Defaults to DEFAULT_MODEL_ID if not set |
DEFAULT_OCR_MODEL_ID | No | Model for OCR document extraction. Defaults to DEFAULT_MODEL_ID if not set |
--from-literal=OPENAI_BASE_URL="https://openrouter.ai/api/v1" \
--from-literal=OPENAI_API_KEY="sk-or-..." \
--from-literal=DEFAULT_MODEL_ID="qwen/qwen3.5-9b"
Vector Store (Qdrant)
| Variable | Required | Description |
|---|
QDRANT_URL | Yes | HTTP URL of the Qdrant service (e.g. http://cobi-dashboard-qdrant:6333) |
QDRANT_LOCAL_ONLY | Yes | Set "true" for in-cluster or on-prem Qdrant; "false" for Qdrant Cloud |
QDRANT_COLLECTION_PREFIX | No | String prefix for all collection names. Useful to namespace multiple environments sharing one Qdrant instance (e.g. "prod_", "staging_") |
QDRANT_API_KEY | Conditional | Required when using Qdrant Cloud. Leave empty for local |
QDRANT_CLUSTER_KEY | Conditional | Required when using Qdrant Cloud. Leave empty for local |
Object Storage
| Variable | Required | Description |
|---|
S3_BUCKET | Yes | Bucket name for document storage |
S3_REGION | Yes | Signing region. Set to "us-east-1" for MinIO |
S3_ENDPOINT | Yes for S3-compatible storage | Custom S3 endpoint. Set to "http://cobi-dashboard-minio:9000" when using in-cluster MinIO |
S3_ACCESS_KEY_ID | Yes for static credentials | S3 access key ID, or MinIO rootUser |
S3_SECRET_ACCESS_KEY | Yes for static credentials | S3 secret access key, or MinIO rootPassword |
When backend.s3.existingSecret is set, the Helm chart maps these generic S3_* Secret keys to the backend container’s runtime environment variables.
Security
| Variable | Required | Description |
|---|
DATASOURCES_ENCRYPTION_KEY | Yes | 64-character hex key used to encrypt stored data-source credentials at rest. Generate with openssl rand -hex 32 |
Observability
| Variable | Required | Description |
|---|
OTEL_EXPORTER_OTLP_ENDPOINT | No | OTLP receiver URL (e.g. http://cobi-dashboard-otel-lgtm:4318). Set when otel-lgtm is enabled |
OTEL_SERVICE_NAME | No | Service name shown in traces (e.g. "cobi-backend") |
OTEL_SERVICE_VERSION | No | Service version shown in traces |
OTEL_METRIC_EXPORT_INTERVAL | No | Metric export interval in milliseconds (default 5000) |
POSTHOG_API_KEY | No | PostHog project API key for product analytics |
POSTHOG_HOST | No | PostHog ingest host (e.g. https://eu.i.posthog.com) |
POSTHOG_PERSONAL_API_KEY | No | PostHog personal API key for server-side calls |
LANGFUSE_PUBLIC_KEY | No | Langfuse project public key for LLM tracing |
LANGFUSE_SECRET_KEY | No | Langfuse project secret key |
LANGFUSE_HOST | No | Langfuse host (e.g. https://cloud.langfuse.com) |
LANGFUSE_TRACING_ENVIRONMENT | No | Environment label in Langfuse traces (e.g. "production") |
LANGFUSE_PROMPT_RUNTIME_MODE | No | "local-only" to load prompts from bundled files; "langfuse" to fetch from Langfuse at runtime |
LANGFUSE_PROMPT_LABEL | No | Prompt version label to load from Langfuse (default "latest") |
LANGFUSE_PROMPT_BUNDLE_PATH | No | File path of the bundled prompt file when LANGFUSE_PROMPT_RUNTIME_MODE=local-only |
Helm Values
Reference the Secret in your values file:
backend:
enabled: true
image:
repository: docker.io/hellocobi/dashboard-backend
tag: "0.2.6"
pullPolicy: IfNotPresent
replicaCount: 1
service:
type: ClusterIP
port: 3000
envFrom:
- secretRef:
name: cobi-backend-secrets
s3:
existingSecret: cobi-backend-secrets
resources:
requests:
cpu: 250m
memory: 512Mi
limits:
cpu: "1"
memory: 1Gi
Generating Secure Keys
# BETTER_AUTH_SECRET — 32-byte hex string
openssl rand -hex 32
# DATASOURCES_ENCRYPTION_KEY — 32-byte hex string (64 chars)
openssl rand -hex 32
