Operations

This page collects operational notes that are clear from the repository. It is not a complete production runbook yet.

Migrations

Apply application database migrations with:

bun run --filter @orcai/db migrate

Generate a new Drizzle migration during development with:

bun run --filter @orcai/db generate

Apply the SpiceDB schema with:

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

Inspect SpiceDB schema migration status with:

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

Workers

Keep workers running alongside the app. If workers are stopped, uploads and scheduled maintenance jobs may remain queued.

Asset Processing

If OCR or extraction fails, verify:

• Worker process is running.
• Tesseract is installed when running workers on the host.
• KREUZBERG_OCR_LANGUAGE only references installed language packs.
• The AI endpoint supports the configured GENERAL_MODEL.
• Object storage credentials and bucket setup are valid.

Retrieval

If retrieval quality or indexing fails, verify:

• OPENAI_COMPATIBLE_BASE_URL and OPENAI_COMPATIBLE_API_KEY.
• EMBEDDING_MODEL.
• EMBEDDING_DIMENSIONS.
• Qdrant availability and API key.

Do not change embedding model or dimensions on a live indexed dataset without recreating the collection and reindexing.

SpiceDB Connectivity

If SpiceDB connections fail, verify:

• SPICEDB_ENDPOINT.
• SPICEDB_TOKEN.
• SPICEDB_SECURITY matches your deployment mode.