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:
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 | ghcr.io/sowers-io/bosca/text-extractor | 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/lakehouse 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
The Bosca CLI generates Kubernetes manifests using cdk8s (Cloud Development Kit for Kubernetes). There are no Helm charts — manifests are generated programmatically from a bosca.yaml config file.
bash
Generated manifests
The CLI generates layered manifests:
00-bosca-config.yaml— ConfigMaps and Secrets01-bosca-operators.yaml— CloudNativePG, cert-manager02-bosca-storage.yaml— PersistentVolumeClaims03-bosca-dependencies.yaml— PostgreSQL, NATS, Redis, Meilisearch, S3Proxy, Trino, Jaeger04-bosca.yaml— Application services (server, runner, admin, collector, Git server, etc.)05-bosca-gateway.yaml— Ingress / Gateway configuration
Feature flags
The Kubernetes config supports feature flags to enable/disable optional services:
bash
Key Environment Variables
Configuration is loaded from application.yaml with $VAR:default substitution:
Essential variables