Docker Compose Quickstart

Use the Compose quickstart when you want a runnable local stack outside the devcontainer.

Prerequisites

• Docker with Docker Compose.
• A configured OpenAI-compatible endpoint for embeddings and model calls.
• A local .env file based on .env.example.
• Values for EMBEDDING_MODEL, EMBEDDING_DIMENSIONS, and GENERAL_MODEL.
• Secrets for auth/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 .env

Edit .env before starting the stack. At minimum, set the AI variables below.

Run Compose [step]

From the repository root:

docker compose -f docker-compose.yaml -f docker-compose.local.yaml up -d --build

The app is published on:

http://localhost:3000

Services And Ports

The local override publishes:

Most ports can be overridden with environment variables such as APP_PORT, POSTGRES_PORT, MINIO_API_PORT, and QDRANT_HTTP_PORT.

Required AI Variables

The local override provides development placeholders for some secrets, but these AI variables must be meaningful for ingestion and chat to work:

OPENAI_COMPATIBLE_BASE_URL="https://your-ai-provider.example/v1"
OPENAI_COMPATIBLE_API_KEY="replace-with-openai-compatible-api-key"
EMBEDDING_MODEL="baai/bge-m3"
EMBEDDING_DIMENSIONS=1024
GENERAL_MODEL="google/gemma-4-26b-a4b-it"

Stop The Stack

docker compose -f docker-compose.yaml -f docker-compose.local.yaml down

Add -v only if you intentionally want to remove local volumes and lose stored database, object storage, Qdrant, and SpiceDB data.

Production-Like Notes

• The local override injects development defaults for several values; treat those as non-production.
• Keep EMBEDDING_MODEL and EMBEDDING_DIMENSIONS stable after indexing data.
• Custom embedding and image-processing model definitions are only supported in self-hosted deployments.

What Compose Initializes

The Compose stack includes one-shot services for:

• Application database migrations.
• MinIO bucket bootstrap.
• SpiceDB schema migration.