Configuration
Beyond Retrieval v2 separates configuration into two layers:
.env file — Infrastructure settings (database, auth, Docker services)- Global Settings UI — API keys and storage provider (per-user, stored in database)
Deployment Modes
| Mode | Database | Ollama | Auto-HTTPS | Best For |
dev | Cloud Supabase | No | No | Local development with hot-reload |
local | Docker Supabase | Yes (CPU/GPU) | No | Self-hosted, offline/air-gapped |
cloud | Cloud Supabase | No | Yes (Caddy) | VPS with managed database |
production | Docker Supabase | Yes (CPU/GPU) | Yes (Caddy) | Full VPS deployment |
python start_services.py <mode> [--gpu nvidia|amd|cpu] [--build]
GPU support: --gpu nvidia (CUDA), --gpu amd (ROCm), --gpu cpu (CPU-only).
Environment Variables
Domain & CORS
| Variable | Default | Description |
APP_HOSTNAME | — | Public domain for the web UI (Caddy auto-HTTPS) |
STUDIO_HOSTNAME | — | Public domain for Supabase Studio |
DOCLING_HOSTNAME | — | Public domain for the Docling sidecar |
CORS_ORIGINS | ["http://localhost:5173","http://localhost:3000"] | Allowed CORS origins (JSON array) |
Database
| Variable | Default | Description |
DB_TYPE | cloud | "cloud" for hosted Supabase, "local" for Docker Supabase |
SUPABASE_URL | — | Cloud Supabase project URL |
SUPABASE_SECRET_KEY | — | Cloud Supabase service role key |
LOCAL_SUPABASE_URL | http://supabase-kong:8000 | Docker-internal URL for local Supabase |
LOCAL_SUPABASE_KEY | — | Must equal SUPABASE_SERVICE_ROLE_KEY (same JWT_SECRET) |
Authentication
| Variable | Default | Description |
BYPASS_AUTH | true | true = dev mode (no JWT check), false = production |
CLERK_SECRET_KEY | — | Clerk backend secret key |
CLERK_PUBLISHABLE_KEY | — | Clerk publishable key (backend JWKS derivation) |
VITE_CLERK_PUBLISHABLE_KEY | — | Same key, exposed to frontend via Vite |
Docker Services
| Variable | Default | Description |
OLLAMA_BASE_URL | http://ollama:11434 | Ollama API endpoint (Docker-internal) |
DOCLING_SERVE_URL | — | Docling sidecar URL; empty = local import |
| Variable | Default | Description |
WEB_CONCURRENCY | 4 | Number of uvicorn workers in production |
MAX_FILE_SIZE_MB | 50 | Maximum upload file size |
Local Supabase Docker
These are only needed when running local Supabase via Docker:
| Variable | Default | Description |
POSTGRES_PASSWORD | — | PostgreSQL superuser password |
JWT_SECRET | — | JWT signing secret (shared across Supabase services) |
ANON_KEY | — | Supabase anonymous JWT |
SUPABASE_SERVICE_ROLE_KEY | — | Supabase service role JWT (full access) |
DASHBOARD_USERNAME | admin | Supabase Studio login |
DASHBOARD_PASSWORD | admin | Supabase Studio password |
Storage
| Variable | Default | Description |
LOCAL_STORAGE_PATH | ./data/documents | Filesystem path when storage_provider=local |
API Keys (Global Settings UI)
API keys for LLM providers are managed per-user through the Global Settings page and stored in the user_api_keys database table. This keeps secrets out of environment files.
| Provider | Purpose | Required For |
| OpenRouter | LLM inference gateway (25+ models) | Chat, Enhancement, Judge, Agentic search |
| OpenAI | Direct OpenAI API access | Alternative to OpenRouter for OpenAI models |
| Mistral | OCR-based document parsing | Mistral OCR parser |
| Cohere | Search result reranking | Reranking in retrieval (optional) |
Key Priority
User-saved keys (from Global Settings) take priority over server .env keys. If no user key is saved, the server default is used. If neither exists and the provider is not Ollama, the system returns a 400 error.
Docker Profiles
| Profile | Services Activated |
| (default) | backend, frontend-build, caddy |
local | supabase-db, supabase-rest, supabase-auth, supabase-kong, supabase-storage, supabase-meta, supabase-studio |
cpu | ollama-cpu, ollama-init-cpu |
gpu-nvidia | ollama-gpu-nvidia, ollama-init-gpu-nvidia |
gpu-amd | ollama-gpu-amd, ollama-init-gpu-amd |
docling | docling |
Important Notes
.env Changes in Docker
docker compose restart reuses the old environment. You must use docker compose up -d to pick up .env changes (recreates containers).
PostgREST Schema Cache
After running ALTER TABLE statements, restart the PostgREST container:
docker compose restart supabase-rest
Without this, new columns return
null.