Infrastructure¶

Beyond Retrieval v2 runs as a Docker Compose stack with 16 services across multiple profiles.

Docker Compose Architecture¶

graph TB
    subgraph Core Services
        backend["backend<br/>FastAPI Python 3.12<br/>Port 8000"]
        frontend_build["frontend-build<br/>Vite build → /srv<br/>One-shot"]
        caddy["caddy<br/>Caddy 2 Alpine<br/>Ports 80, 443"]
    end

    subgraph Local Supabase — profile: local
        supabase_db["supabase-db<br/>PostgreSQL 15.8.1<br/>Port 5432"]
        supabase_rest["supabase-rest<br/>PostgREST v12.2.3<br/>Port 3000"]
        supabase_auth["supabase-auth<br/>GoTrue v2.158.1<br/>Port 9999"]
        supabase_kong["supabase-kong<br/>Kong 2.8.1<br/>Port 8000"]
        supabase_storage["supabase-storage<br/>Storage API v1.11.13<br/>Port 5000"]
        supabase_meta["supabase-meta<br/>Postgres Meta v0.83.2"]
        supabase_studio["supabase-studio<br/>Studio Dashboard"]
    end

    subgraph AI Services
        ollama_cpu["ollama-cpu<br/>profile: cpu"]
        ollama_nvidia["ollama-gpu-nvidia<br/>profile: gpu-nvidia"]
        ollama_amd["ollama-gpu-amd<br/>profile: gpu-amd"]
        docling["docling<br/>profile: docling<br/>Port 5001"]
    end

    caddy --> backend
    caddy --> frontend_build
    backend --> supabase_kong
    supabase_kong --> supabase_rest
    supabase_kong --> supabase_auth
    supabase_rest --> supabase_db
    supabase_auth --> supabase_db
    supabase_storage --> supabase_db
    backend --> docling

Deployment Modes¶

Mode	Command	Database	Ollama	Auto-HTTPS
`dev`	`python start_services.py dev --build`	Cloud Supabase	No	No
`local`	`python start_services.py local --gpu cpu --build`	Docker Supabase	Yes	No
`cloud`	`python start_services.py cloud --build`	Cloud Supabase	No	Yes (Caddy)
`production`	`python start_services.py production --gpu cpu --build`	Docker Supabase	Yes	Yes (Caddy)

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

Volumes¶

Volume	Purpose
`frontend-dist`	Built React SPA static files
`caddy-data`	Caddy TLS certificates
`caddy-config`	Caddy runtime configuration
`ollama-models`	Downloaded Ollama model weights
`supabase-db-data`	PostgreSQL data directory
`supabase-storage-data`	Supabase Storage file backend
`local-documents`	Local filesystem document storage

Network¶

All services share a single internal bridge network. No service exposes ports in the base compose file — port mappings are added exclusively via override files, ensuring the base configuration is secure by default.

Caddy Configuration¶

Caddy serves three virtual hosts:

Virtual Host	Purpose
`APP_HOSTNAME`	Main app: static files + `/api/*` reverse proxy
`STUDIO_HOSTNAME`	Supabase Studio (proxied through Kong)
`DOCLING_HOSTNAME`	Docling Serve API

Optional subdomains default to unreachable hostnames (studio.internal, docling.internal), effectively disabling them unless configured in .env.

Caddy provides automatic HTTPS via Let's Encrypt when APP_HOSTNAME is a public domain. In local mode (APP_HOSTNAME=:80), it serves plain HTTP.

Compose File Structure¶

File	Purpose
`docker-compose.yml`	Base (all services, no exposed ports)
`docker-compose.override.private.yml`	Dev/local port mappings (localhost only)
`docker-compose.override.public.yml`	Production with Caddy HTTPS
`docker-compose.override.local.yml`	Local Supabase profile services
`Caddyfile`	Reverse proxy rules
`start_services.py`	Docker Compose orchestrator CLI

Init Scripts Mount

Docker init-scripts use individual file mounts, NOT directory mounts. A directory mount would replace the image's built-in scripts (98-webhooks, 99-roles, 99-jwt, 99-schema.sql).