Infrastructure
Running Bosca locally with Docker Compose, deploying to Kubernetes with the CLI, and understanding the downstream systems.
Local Development (Docker Compose)
The full dependency stack runs via Docker Compose. The root docker-compose.yaml includes server/services/docker-compose.yaml, which defines every backing service.
bash
Services
| Service | Image | Port | Purpose |
|---|---|---|---|
| PostgreSQL | postgres:18.1-alpine | 5433 | Primary database |
| PostgreSQL (Warehouse) | postgres:18.1-alpine | 5434 | Analytics warehouse |
| NATS | nats | 4222 | Messaging, pub/sub, job queues |
| Redis-compatible | dragonflydb/dragonfly | 6380 | Cache, distributed locks |
| Meilisearch | getmeili/meilisearch:v1.39.0 | 7701 | Full-text search |
| S3Proxy | andrewgaul/s3proxy:3.0.0 | 8000 | S3-compatible local object storage |
| Trino | trinodb/trino:479 | 8089 | Distributed SQL / Iceberg analytics |
| Jaeger | jaegertracing/jaeger:2.13.0 | 16686 | Distributed tracing (OTEL) |
| Text Extractor | Text extraction service | 8083 | Document text extraction (PDF, DOCX, etc.) |
Then start the server and runner:
bash
Downstream Systems
Required
| System | Role | Config |
|---|---|---|
| PostgreSQL | Primary database — all models, permissions, workflow state | DATABASE_URL, DATABASE_USER, DATABASE_PASSWORD |
| Redis-compatible | Cache, distributed locks, job queues (when configured) | REDIS_HOST, REDIS_PORT |
| NATS | Messaging, pub/sub, job queues, distributed locks, cache (when configured) | NATS_HOST, NATS_TOKEN |
| S3 / GCS | Object storage for content files, Git pack files, LFS objects | STORAGE_TYPE, STORAGE_BUCKET, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_ACCESS_KEY_SECRET |
| Meilisearch | Full-text search for content and code | MEILISEARCH_URL, MEILISEARCH_API_KEY |
Optional / Analytics
| System | Role |
|---|---|
| Trino | Distributed SQL for analytics queries over Iceberg/warehouse data |
| Jaeger | Distributed tracing via OpenTelemetry (OTLP on 4317/4318) |
| Text Extractor | Extracts text from PDFs, DOCX, and other document formats |
Integrations
| System | Role |
|---|---|
| Mux | Video upload, transcoding, and streaming |
| HubSpot | CRM contact sync |
| SendGrid | Transactional email |
| Crowdin | Localization / translation management |
| Google OAuth2 / TTS / GenAI | Authentication, text-to-speech, AI features |
| OpenAI / Anthropic | AI model providers for chat, agents, and tools |
| PostHog | Product analytics and experimentation |
Configurable Backends
Several infrastructure services are swappable at startup via environment variables:
| Concern | Env Var | Options |
|---|---|---|
| Cache | CACHE_TYPE | redis (default), nats |
| Pub/Sub | PUBSUB_TYPE | nats (default), redis |
| Job Queue | JOB_QUEUE_FACTORY | redis (default), nats |
| Distributed Locks | DISTRIBUTED_LOCK_TYPE | nats (default), redis |
| Object Storage | STORAGE_TYPE | s3 (default), gcs |
Kubernetes Deployment
Bosca deploys to Kubernetes via the official Helm charts. See Helm for the chart catalog, install and upgrade flows, and values reference.
Key Environment Variables
Configuration is loaded from application.yaml with $VAR:default substitution. The names below are read directly by the server and runner:
Essential variables