Deployment
Deploy SOIT with the required runtime infrastructure.
SOIT deploys as a set of application services plus supporting infrastructure: web, API, workers, database, queue, vector store, object storage, and secret store.
Service topology
| Component | Role |
|---|---|
| web | Workspace UI (port 5000 in the local stack) |
| api | FastAPI backend (port 9200 in the local stack) |
| gateway (optional) | New in v1.4.0: more API processes started with SOIT_ROLE=gateway, serving only /v1, /mcp, /api/v1/tools, and health, beside at least one api process with the default role |
| workers | knowledge-ingest-worker, outbox-dispatcher and scheduler: knowledge ingestion, event dispatch and scheduled runs |
| PostgreSQL | Business data, runtime ledger, and outbox events |
| Redis | Broker, cache, and runtime coordination |
| Milvus (+ etcd) | Vector collections for knowledge retrieval |
| MinIO | Documents and runtime artifacts |
| Vault | Workspace-scoped secret storage |
| migrate | One-shot job applying Alembic migrations |
| bootstrap | One-shot job creating the admin account and initial workspace |
The API and the workers reach external LLM providers, MCP servers and enterprise systems, always through governed adapters: the API makes the calls of chats, gateway requests and direct tool calls itself, and the workers those of ingestion and background runs.
Local self-hosted stack
Use the Docker path from the Quickstart:
cp .env.example .env
docker compose -f docker/docker-compose.yml up -d postgres redis minio etcd milvus vault migrate bootstrap api web knowledge-ingest-workerProduction checklist
- Run migrations before serving traffic — the
migratejob must complete beforeapistarts handling requests. See Migration and Upgrade for the full runbook. - Configure secret storage — Vault (or a compatible KMS) must be reachable; provider credentials are stored as references, never in environment plaintext beyond bootstrap configuration.
- Set bootstrap credentials —
BOOTSTRAP_ADMIN_EMAILandBOOTSTRAP_ADMIN_PASSWORDestablish the first admin account. - Enterprise only: mount the license — set
ENTERPRISE_LICENSE_PATHandENTERPRISE_LICENSE_PUBLIC_KEY_PATH, then check the edition under Settings › About. See Editions and Licenses. - Separate gateway processes — if you start processes with
SOIT_ROLE=gateway, keep at least one process with the default role running: it does the background work, such as usage aggregation and budget alerts. See Running the gateway on its own. - Confirm queue workers are healthy — knowledge ingestion and event dispatch stop silently if workers die; monitor them.
- Confirm vector and object storage are reachable — knowledge retrieval and artifact storage depend on Milvus and MinIO.
- Validate readiness before routing traffic:
curl http://<api-host>:9200/health/ready
curl http://<web-host>:5000/Observability in production
Traces, audit records, and cost entries land in the runtime ledger automatically; the Observe views read from it. Pair that with infrastructure-level monitoring for the services above. See Observability.
Docs site deployment
This documentation site itself (soit-docs) is a prerendered React Router + Fumadocs SPA deployed to Cloudflare Workers at docs.soit.ai. Its deployment is independent of the SOIT platform.