Docker Compose quickstart
Start a local OrcAI stack with the repository Compose files.
Use the Compose quickstart when you want a runnable local stack outside the devcontainer.
Prerequisites
- Docker with Docker Compose.
- An OpenAI-compatible endpoint that serves your embedding model. Chats use the providers an admin adds in the app.
- A local
.envfile based on.env.example. - Secrets for authentication and encryption (
BETTER_AUTH_SECRET,ENCRYPTION_KEY) for anything beyond throwaway local testing.
Start the stack
Create the environment file [step]
If you do not have a local .env yet, create one from the example:
cp .env.example .envEdit .env before starting the stack.
Run Compose [step]
From the repository root:
docker compose -f docker-compose.yaml -f docker-compose.local.yaml up -d --buildThe app is then at http://localhost:3000.
Initialise the instance [step]
On a fresh database, open http://localhost:3000/init. The sign-in page sends you there until the instance is initialised. The form creates the first account, which is the instance admin, and the first organisation with that account as its admin. It asks for Organisation name, Organisation slug, Admin name, Admin email, Password and Confirm password, and for consent to the privacy policy and terms of use. Once you choose Initialise instance, the page is no longer available, and every later account comes from an invitation (see Creating accounts).
Set up embeddings [step]
Initialising the instance takes you to the instance Settings page. Under Embeddings, enter the Base URL, API key and Model of your OpenAI-compatible endpoint, then choose Save and test. Embeddings describes the fields and what saving does. Set up later goes to the app instead, and uploads are not searchable until embeddings are set up.
Chats need a provider and models, which the new admin adds in the app. Organisation setup walks through it.
Services and ports
The local override publishes:
| Service | Default port | Purpose |
|---|---|---|
| OrcAI app | 3000 | Main web application |
| OrcAI docs | 3001 | Documentation site, which the Assistant reads |
| PostgreSQL | 5432 | Application database |
| SeaweedFS S3 API | 8333 | S3-compatible object storage |
| Qdrant HTTP | 6333 | Vector database HTTP API |
| Qdrant gRPC | 6334 | Vector database gRPC API |
| SpiceDB gRPC | 50051 | Authorisation service |
| SpiceDB HTTP | 8080 | SpiceDB HTTP API |
| SpiceDB metrics | 9090 | SpiceDB metrics |
| SpiceDB PostgreSQL | 5431 | SpiceDB backing database |
Most ports can be overridden with environment variables such as APP_PORT, WEB_PORT, POSTGRES_PORT, S3_PORT, and QDRANT_HTTP_PORT.
Stop the stack
docker compose -f docker-compose.yaml -f docker-compose.local.yaml downAdd -v only to remove the local volumes, which deletes the stored database, object storage, Qdrant and SpiceDB data.
Production-like notes
The local override injects development defaults for several values, so do not use it in production. Without it, docker-compose.yaml publishes no ports, and Public URLs lists what browsers must reach.
What Compose initialises
One-shot services in the Compose stack apply the database migrations and the SpiceDB schema. SeaweedFS creates the uploads and processed-files buckets itself on startup.