Deployment
Local Development (Docker Compose)
All services run locally via Docker Compose. The dev.py script wraps common operations.
Services
| Service | Technology | Port | Purpose |
|---|---|---|---|
frontend | SvelteKit dev server | 5173 | UI application |
api | FastAPI + uvicorn | 8000 | Backend API |
worker | Python worker | — | Background jobs |
db | PostgreSQL 16 + pgvector | 5432 | Primary database |
redis | Redis | 6379 | Job queue broker |
supabase-auth | GoTrue | 9999 | Auth service |
inbucket | Inbucket SMTP | 9000 | Email capture (dev only) |
inbucket is a local email capture tool. It intercepts all outbound email from GoTrue (password reset links, confirmations) so that no real email is sent during development. Access the inbox at http://localhost:9000.
Dev Commands
python scripts/dev.py up # Start all services
python scripts/dev.py down # Stop all services
python scripts/dev.py clean # Remove volumes (resets all data)
python scripts/dev.py logs # View logs for all services
To view logs for a specific service:
python scripts/dev.py logs api
python scripts/dev.py logs worker
Production Topology
Orbit Classroom is designed for small-to-medium deployments. The v1 scale target is approximately 100 total users with a single active model.
Recommended Minimum Components
| Component | Recommended Option |
|---|---|
| Frontend | SvelteKit static build on CDN or container |
| Backend | FastAPI + uvicorn in a container |
| Worker | Python worker in a separate container |
| Database | Managed PostgreSQL (Supabase, AWS RDS, or equivalent) |
| Storage | Managed S3-compatible (Supabase Storage, AWS S3, or equivalent) |
| Cache | Managed Redis or containerized Redis |
| Auth | Supabase Cloud or self-hosted GoTrue |
A single application host plus managed database is acceptable at the v1 scale target. The frontend, API, and worker can run on the same host if needed.
Environment Variables
The .env file at the project root configures all services. Generate secrets with:
python scripts/dev.py secrets
Key Variables
| Variable | Description |
|---|---|
POSTGRES_PASSWORD | Database password |
SUPABASE_JWT_SECRET | Auth secret — must be 32+ characters |
ADMIN_EMAIL | Email address for the first Admin account |
ADMIN_PASSWORD | Password for the first Admin account |
PUBLIC_API_BASE_URL | URL the frontend uses to reach the backend API |
ANTHROPIC_API_KEY | Optional — required only if using Anthropic models |
OPENAI_API_KEY | Optional — required only if using OpenAI models |
OLLAMA_BASE_URL | Ollama endpoint (default: http://host.docker.internal:11434) |
Never commit .env to version control. The file contains secrets that grant access to the database, auth service, and external model providers.