BoscaDeveloper Documentation

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:

bash

Services

ServiceImagePortPurpose
PostgreSQLpgvector/pgvector:pg185433Primary database
PostgreSQL (Warehouse)postgres:18.1-alpine5434Iceberg catalog database
NATSnats4222Messaging, pub/sub, job queues
Redis-compatibledocker.dragonflydb.io/dragonflydb/dragonfly6380Cache, distributed locks
Meilisearchgetmeili/meilisearch:v1.39.07701Full-text search
S3Proxyandrewgaul/s3proxy:3.0.08000S3-compatible local object storage
Trinotrinodb/trino:4798089Distributed SQL / Iceberg analytics
Jaegercr.jaegertracing.io/jaegertracing/jaeger:2.13.016686Distributed tracing (OTEL)
TensorFlow Servingtensorflow/serving8501Serve recommendation models when model artifacts are present
Text Embeddings InferenceCPU embedding service8092Semantic embeddings for content indexing

Start the server and runner in separate terminals from the repository root. JVM modules use the Java 25 toolchain:

bash

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

SystemRoleConfig
PostgreSQLPrimary database — all models, permissions, workflow stateDATABASE_URL, DATABASE_USER, DATABASE_PASSWORD
Redis-compatibleCache, pub/sub, locks, and jobs when Redis backends are selectedREDIS_HOST, REDIS_PORT
NATSDefault cache, pub/sub, durable jobs, and distributed locksNATS_HOST, NATS_TOKEN
S3 / GCSObject storage for content files, Git pack files, LFS objectsSTORAGE_TYPE, STORAGE_BUCKET, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_ACCESS_KEY_SECRET
MeilisearchFull-text search for content and codeMEILISEARCH_URL, MEILISEARCH_API_KEY

Optional / Analytics

SystemRole
TrinoDistributed SQL for analytics queries over Iceberg/warehouse data
JaegerDistributed tracing via OpenTelemetry (OTLP on 4317/4318)
Text ExtractorExtracts 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:

ConcernEnv VarOptions
CacheCACHE_TYPEnats (default), redis
Pub/SubPUBSUB_TYPEnats (default), redis
Job QueueJOB_QUEUE_FACTORYnats (default), redis
Distributed LocksDISTRIBUTED_LOCK_TYPEnats (default), redis
Object StorageSTORAGE_TYPEs3 (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:

Essential variables