Self Hosting
Run OrcAI with Docker Compose or a manually managed service stack.
OrcAI can be run as a local Docker Compose stack or as manually managed Bun app and worker processes connected to external services.
For most self-hosting experiments, start with Docker Compose quickstart. Use manual setup when you need to manage PostgreSQL, Valkey, Qdrant, SpiceDB, S3-compatible storage, and workers yourself.
Not production hardened
These pages document what the repository can run today. They are not yet a complete production operations guide.
Choose A Path
Docker Compose quickstart
Start the app, workers, databases, object storage, authorization, and vector search locally.
Manual setup
Run the Bun app and workers directly against services you manage yourself.
Configuration
Map the required environment variables for auth, storage, AI, retrieval, and services.
Operations
Use the current maintenance notes for migrations, workers, retrieval, and troubleshooting.
Required Infrastructure
- PostgreSQL
- Valkey
- S3-compatible object storage
- Qdrant
- SpiceDB
- An OpenAI-compatible inference endpoint
- Background workers
Model Configuration Scope
Custom embedding and image-processing model definitions are supported only when you self-host OrcAI.
In managed/shared deployments, treat these as platform-level settings controlled by the hosting operator.
Important Caveats
- OrcAI is not production-ready yet.
docker-compose.local.yamlis a development-oriented override, not a production deployment manifest.- AI model, embedding model, and embedding dimensions must be configured before useful content ingestion can work.
- Changing embedding settings on an existing deployment requires recreating the Qdrant collection and reprocessing assets.
Source Files
.env.exampledocker-compose.yamldocker-compose.local.yamlpackages/ai/src/config.tspackages/db/src/config.tspackages/notifications/src/config.tspackages/qdrant/src/config.tspackages/s3/src/server/config.tspackages/spice-db/src/config.tspackages/valkey/src/config.ts