Manual Setup

Use manual setup when you want to run OrcAI directly on a host instead of using the full Compose stack.

Prerequisites

• Bun >=1.3.10
• PostgreSQL
• Valkey
• Qdrant
• SpiceDB
• S3-compatible object storage
• OpenAI-compatible inference endpoint
• Tesseract with eng and deu language packs if workers run on the host
• Optional SMTP server

Install Dependencies

cp .env.example .env
bun install --frozen-lockfile

Edit .env before starting the app. See Configuration for required variables.

Initialize Data Stores

Run database migrations:

bun run --filter @orcai/db migrate

Apply the SpiceDB schema:

bun run --filter @orcai/spice-db up

Start Development Processes

Start the app:

bun run dev

Start background workers in a separate terminal:

bun run workers:dev

The app is available at:

http://localhost:3000

On a fresh database, complete initial instance setup at:

http://localhost:3000/init

Production Commands

Build and start the app:

bun run build
bun run start

Start workers:

bun run workers:start

Host OCR Notes

OCR-backed asset processing runs in the worker process. When workers run outside Docker, install Tesseract and the configured language packs. Use KREUZBERG_OCR_LANGUAGE=eng+deu only where both packs are installed.

Model Customisation Scope

Custom embedding and image-processing model definitions are supported only when you self-host OrcAI.