Configuration

Runtime configuration is loaded across app and package config modules. .env.example is the current baseline for self-hosted environments. Every value comes from the container environment and applies when the container restarts, so one image serves any instance. The one exception is the legal pages, which are compiled into the image. Build args only carry image identity, never deployment values.

Under Docker Compose, a container only sees the variables docker-compose.yaml passes to it. Compose sets the service addresses itself (POSTGRES_HOST, QDRANT_URL, SPICEDB_ENDPOINT) and fills SPICEDB_TOKEN from SPICEDB_GRPC_PRESHARED_KEY. The bundled PostgreSQL always creates the user postgres and the database app, so leave POSTGRES_USER and POSTGRES_DB at those values. Compose does not pass BETTER_AUTH_RATE_LIMIT, WORKER_POLLING_INTERVAL_SECONDS or PORT, so setting them in .env has no effect until you add them to the service's environment.

The primary config modules are:

• packages/ai/src/config.ts
• packages/db/src/config.ts
• packages/notifications/src/config.ts
• packages/qdrant/src/config.ts
• packages/s3/src/server/config.ts
• packages/spice-db/src/config.ts
• apps/app/src/lib/effect/services/config.ts

Public URLsCopy Anchor Link

Browsers need to reach three origins: the app at BETTER_AUTH_URL, the docs site at WEB_URL, and object storage at S3_PUBLIC_ENDPOINT (see Object storage). docker-compose.yaml publishes no ports, so put a reverse proxy with TLS in front of these services, or publish their ports the way docker-compose.local.yaml does.

The app sends a Content Security Policy with every response. Browsers then load content only from the app itself, from object storage at S3_PUBLIC_ENDPOINT (or S3_ENDPOINT when it is unset), from YouTube's privacy-enhanced embeds, and from the Umami script's origin when UMAMI_SCRIPT_URL and UMAMI_WEBSITE_ID are set. Both origins come from this configuration, so the policy follows a changed value after a restart. Each response carries its own nonce for the page's scripts, so a reverse proxy must pass the Content-Security-Policy header through unchanged, add no second policy, and not cache pages.

Authentication and encryptionCopy Anchor Link

Database and cacheCopy Anchor Link

Object storageCopy Anchor Link

Browsers send files straight to object storage and download them from it, so S3_PUBLIC_ENDPOINT must be reachable from every user's browser. OrcAI addresses buckets by path (https://storage.example/uploads/...), not by subdomain. It uses two buckets, uploads and processed-files, with these fixed names, and creates them when they are missing, so the access key needs the right to create buckets unless you create both first. When object storage runs on a different origin than the app, its CORS rules must allow PUT with any request header from the BETTER_AUTH_URL origin and expose the ETag header, which multipart uploads read. The bundled SeaweedFS creates both buckets on startup.

AI and retrievalCopy Anchor Link

No environment variable sets the embedding endpoint. An instance admin sets it in the app, as described under Embeddings. Chats, the Assistant and the utility model use the providers each organisation adds in the app.

EmbeddingsCopy Anchor Link

The embedding endpoint and model are the same for every organisation on the instance and are stored in the database. An instance admin sets them under Manage instance > Settings (/instance/settings), in the Embeddings section:

• Base URL, the address of any OpenAI-compatible endpoint, usually ending in /v1.
• API key, stored encrypted with ENCRYPTION_KEY and never shown again. Leaving it empty when you edit the setting keeps the stored key.
• Model, the embedding model. Load models reads the endpoint's /models list, and for an endpoint without a list you enter the model name.
• Query prefix and Passage prefix, fixed text some models expect before every search query or before every passage they embed. The model's documentation names it, and both stay empty for models that need none. OrcAI keeps spaces and line breaks as entered. E5 instruct models such as e5-mistral-7b-instruct, for example, expect a query prefix like Instruct: Given a question, retrieve passages that answer it, a line break, and Query: . Other E5 models expect query: and passage: .

Save and test runs a test embedding first. If it fails, nothing is saved and the page shows the reason: the endpoint rejected the key, could not be reached, does not know the model, or answered with something other than a vector. If it succeeds, OrcAI reads the dimensions from the test vector, so there is no field for them.

Each embedding model has its own Qdrant collection, named orcai-chunks-g<generation>-<model>-<dimensions>. The first save creates it and embeds every asset in a repository again from its stored extracted text, so no file is read again and no image is described again. Changing the API key, the base URL or the query prefix while keeping the model applies at once, without embedding anything again. The passages stored for search and keyword matching stay without the passage prefix.

Change the modelCopy Anchor Link

Saving another model, the same model name with other dimensions, or another passage prefix asks for confirmation first and states how many assets in repositories it embeds again. Once confirmed, search moves to a new, empty collection at once, the old collection is deleted, and the workers embed every asset in a repository again from its stored extracted text. Search finds only the assets already embedded with the new setting until all of them are. Meanwhile, chats that search repositories and repository pages show a notice that search is being rebuilt. There is no way back to the old vectors, so going back to the old model embeds everything again too. If another instance admin changed the setting after you opened the page, saving fails and asks you to reload the page and confirm again.

The Search index section below the setting counts the assets in repositories per organisation: embedded with the current model, waiting, and failed, with the failure reasons as counts. It names no file or repository. While assets wait, and after Prepare assets again until they are queued, it refreshes every few seconds.

• Retry failed assets embeds the failed assets again from their stored text and leaves every embedded asset as it is. It skips assets whose stored text is missing.
• Prepare assets again appears when assets failed because their stored text is missing, as with files prepared before OrcAI described images. The workers then queue each of them once to be prepared again in the background, so they read the file again, describe its images with the utility model of the asset's organisation and embed it in every repository that holds it. Assets already being prepared are skipped. While they are prepared, their repository links count as waiting. Until the asset is embedded again, search keeps finding it in the repositories where it was already embedded.
• Re-embed everything embeds every asset in a repository again with the current setting, into a new collection, for when the endpoint's vectors changed without a new model name.

All three ask for confirmation with the number of assets first. Rate limits of the endpoint count as temporary failures, which the workers retry with a delay before an asset counts as failed.

Retry failed assets and Prepare assets again show up in your Activity as one run each. A request to prepare assets again while another one is still queueing joins that run instead of starting a second one.

Until embeddings are set up, uploads still work and OrcAI prepares the assets, but their indexing shows "Waiting for the embedding setup" and repository search is unavailable. Instance admins see a banner in the app that links to Settings, and the Health page fails its Embeddings check. Once the setting is saved, the workers index every waiting asset within about a minute, so nothing has to be uploaded again.

An instance that set its embedding model through environment variables keeps its vectors in a collection named orcai-chunks-<dimensions>. After the update, search is unavailable until an instance admin saves the embedding setting. Saving embeds every asset in a repository again into the new collection and deletes the old one. OrcAI does not read the old embedding variables, so remove them from .env.

QdrantCopy Anchor Link

SpiceDBCopy Anchor Link

EmailCopy Anchor Link

Only the workers read these variables, because they send every email. Until SMTP is configured, email stays in log-only mode for local testing and nothing is delivered. The workers then log each complete rendered message, including password reset, verification and invitation links, so do not use log-only mode in production and treat any captured log output as sensitive credentials.

ObservabilityCopy Anchor Link

Legal pagesCopy Anchor Link

The privacy policy at /privacy and the terms of use at /tou are Markdown files compiled into the app image: apps/app/src/static/legal/privacy-policy.md and apps/app/src/static/legal/terms-of-use.md. Both are templates that ask the operator to add its name, contact details and the legal terms that apply. Edit them and build the image again before users create accounts. The first-run form at /init and the account creation form link to them.