Infrastructure
Choose the local image stack or source-development dependencies, and configure backing services.
Local Development (Docker Compose)
To run Bosca locally using published images, follow Run Bosca Locally. The root docker-compose.yaml starts the applications and their backing services using published images. It keeps data in its own named volumes.
When running the backend from source, start the development dependencies with server/services/docker-compose.yaml. Run these commands from the repository root:
Services
| Service | Image | Port | Purpose |
|---|---|---|---|
| PostgreSQL | pgvector/pgvector:pg18 | 5433 | Primary database |
| PostgreSQL (Warehouse) | postgres:18.1-alpine | 5434 | Iceberg catalog database |
| NATS | nats | 4222 | Messaging, pub/sub, job queues |
| Redis-compatible | docker.dragonflydb.io/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 | cr.jaegertracing.io/jaegertracing/jaeger:2.13.0 | 16686 | Distributed tracing (OTEL) |
| TensorFlow Serving | tensorflow/serving | 8501 | Serve recommendation models when model artifacts are present |
| Text Embeddings Inference | CPU embedding service | 8092 | Semantic embeddings for content indexing |
Start the server and runner in separate terminals from the repository root. JVM modules use the Java 25 toolchain:
For Studio development, run pnpm install in web/, then pnpm --filter @bosca/studio dev. Its development proxy targets the API on port 8080. The dependencies Compose file also offers a Git server through the git-server profile; alternatively run ./gradlew :git:git-server:run.
The dependency stack differs from the root image stack: it publishes backing-service ports for applications running on the host and includes embedding and model-serving services. It does not start Studio, the API, and the runner for you.
Downstream Systems
Core backing services
| System | Role | Config |
|---|---|---|
| PostgreSQL | Primary database — all models, permissions, workflow state | DATABASE_URL, DATABASE_USER, DATABASE_PASSWORD |
| Redis-compatible | Cache, pub/sub, locks, and jobs when Redis backends are selected | REDIS_HOST, REDIS_PORT |
| NATS | Default cache, pub/sub, durable jobs, and distributed locks | 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 |
External integrations such as mail, OAuth2, and AI model providers need their own configuration and credentials. See Optional Integrations for the local image stack.
Configurable Backends
Several infrastructure services are swappable at startup via environment variables:
| Concern | Env Var | Options |
|---|---|---|
| Cache | CACHE_TYPE | nats (default), redis |
| Pub/Sub | PUBSUB_TYPE | nats (default), redis |
| Job Queue | JOB_QUEUE_FACTORY | nats (default), redis |
| 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 by the server and runner. This is a variable reference, not a complete environment file. Their checked-in local defaults match the dependency stack; the root Compose stack supplies container-network settings: