Deployment Guide¶

Beyond Retrieval v2 uses a single start_services.py command with --profile to set the GPU mode. Network is auto-detected from .env, and services can be opted out with --no-* flags.

How It Works¶

The --profile flag controls GPU mode for Ollama. Network comes from .env. Services are opted out with CLI flags:

Configuration Matrix¶

Development Setup¶

Local Supabase (default)¶

The default .env.example runs everything locally. Local Supabase starts by default — no extra flags needed.

cd beyond-retrieval-pythonv
cp .env.example .env
python start_services.py --profile cpu --build

Access: http://localhost:3000

Cloud Supabase¶

For users with a hosted Supabase project:

cp .env.cloud.example .env

Fill in your Supabase URL and key, then pass --no-supabase to skip local DB containers:

python start_services.py --profile cpu --no-supabase --build

For hot-reload during development:

python start_services.py --dev --build

Access: http://localhost:3000

Local Self-Hosted Setup¶

Runs everything locally including Supabase and Ollama. No cloud dependencies. Local Supabase starts by default.

POSTGRES_PASSWORD=your-strong-password
JWT_SECRET=your-32-char-secret
SUPABASE_SERVICE_ROLE_KEY=your-jwt-token
LOCAL_SUPABASE_KEY=your-jwt-token  # Must match SUPABASE_SERVICE_ROLE_KEY
ANON_KEY=your-anon-jwt
BYPASS_AUTH=true

python start_services.py --profile cpu --build

Access:

• App: http://localhost:3000
• Supabase Studio: http://localhost:54321

VPS with Cloud Supabase¶

VPS with cloud Supabase and Caddy auto-HTTPS. Pass --no-supabase to skip local DB containers.

APP_HOSTNAME=your-domain.com
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SECRET_KEY=eyJhbGci...
BYPASS_AUTH=false
CLERK_SECRET_KEY=sk_live_...
CLERK_PUBLISHABLE_KEY=pk_live_...
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...

python start_services.py --profile cpu --no-supabase --build

Caddy auto-provisions SSL certificates from Let's Encrypt.

Full VPS Production¶

Full self-hosted deployment with Docker Supabase, Ollama, and Caddy HTTPS. Local Supabase starts by default.

APP_HOSTNAME=your-domain.com
POSTGRES_PASSWORD=strong-password
JWT_SECRET=long-secret
SUPABASE_SERVICE_ROLE_KEY=jwt-token
LOCAL_SUPABASE_KEY=jwt-token
BYPASS_AUTH=false
CLERK_SECRET_KEY=sk_live_...
CLERK_PUBLISHABLE_KEY=pk_live_...
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...
WEB_CONCURRENCY=4

# CPU:
python start_services.py --profile cpu --build

# NVIDIA GPU:
python start_services.py --profile nvidia --build

CLI Reference¶

python start_services.py --profile cpu --build                          # Everything ON
python start_services.py --profile nvidia --build                       # NVIDIA GPU Ollama
python start_services.py --profile amd --build                          # AMD GPU Ollama
python start_services.py --profile cpu --no-docling --build             # Skip Docling
python start_services.py --profile cpu --no-supabase --build            # Cloud-only (no local DB)
python start_services.py --no-ollama --no-docling --no-supabase --build # Minimal
python start_services.py --dev --build                                  # Dev mode (hot-reload)
python start_services.py --stop                                         # Stop all services
python start_services.py --logs backend                                 # Tail backend logs
python start_services.py --logs                                         # Tail all logs
python start_services.py --status                                       # Show service status

Database Setup¶

Cloud Supabase¶

1. Create a project at supabase.co
2. Open the SQL Editor
3. Run db/migrations/001_initial_schema.sql
4. Run any additional migration files

Local Supabase (Docker)¶

The start_services.py script automatically copies the schema to docker/supabase/init-scripts/99-schema.sql. It runs on first container startup.

Post-Deployment Checklist¶

• Health check: curl https://your-domain.com/api/health
• Auth config: curl https://your-domain.com/api/auth/config
• Open the app and create a test notebook
• Upload a test document and verify ingestion completes
• Ask a question in chat and verify citations appear
• Configure API keys in Global Settings
• Set up Clerk with your domain (if using auth)

Troubleshooting¶