Configuration

Everything is an environment variable. With Compose, put them in .env next to docker-compose.yml; the shipped .env.example is the annotated full list.

Configuration is validated at startup. If something is wrong, the server prints every problem and exits rather than starting in a half-working state.

---

Server

Accounts and sessions

People sign in to the dashboard with their own account; these settings shape how that works. See Accounts and Permissions.

Federated sign-in (OIDC_ISSUER_URL and the rest of the OIDC_* variables) is its own page — see Single Sign-On.

Database

Storage (Compose only)

Examples:

CONTEXTATOR_PGDATA_PATH=/srv/contextator/pgdata     # Linux: keep the database on a chosen disk
CONTEXTATOR_MODELS_PATH=D:/contextator/models       # Windows host directory (forward slashes)
CONTEXTATOR_PGDATA_VOLUME=contextator-pgdata-v2     # or simply another named volume

Documents

Uploads

Embeddings

Search and ranking

Tuning for the vector index and how one answer is assembled from its hits. The defaults are what the golden set measured best; see How Indexing Works for the benchmark these came from.

Sync

Observability

Chunking

Worth knowing: 96 is not a fraction of the model’s window — the default model reads 512 tokens — it is what measured best on the golden set, and filling the window measures worse. Raise both on OpenAI, whose window is 8191. Changing either only affects files indexed afterwards — force a re-index to apply it everywhere. See Indexing.

---

Running behind a reverse proxy

Nothing is in front of this by default — Compose publishes 3444 on the loopback interface (CONTEXTATOR_BIND=127.0.0.1), with nothing between it and the port, and the defaults above are written for that. Publishing it anywhere else (CONTEXTATOR_BIND=0.0.0.0) is the moment to put something in front. Put nginx, Caddy, Traefik or a cloud load balancer in front and two settings have to move together:

TRUST_PROXY=172.18.0.0/16        # the proxy's own address or CIDR, or `loopback` if it runs on the host
PUBLIC_BASE_URL=https://docs.example.com
AUTH_COOKIE_SECURE=1

TRUST_PROXY is what lets this server read X-Forwarded-For and X-Forwarded-Proto from that proxy. Left at 0 behind one, three things break, and none of them says so on its own:

• The per-IP sign-in limit becomes instance-wide. Every request carries the proxy’s address, so AUTH_LOGIN_MAX_ATTEMPTS failures from one person answer 429 to everybody.
• MCP connectors stop being able to authorize. With PUBLIC_BASE_URL unset, the OAuth protected-resource metadata and the WWW-Authenticate pointer are built from req.protocol — which reads http — so the document advertises http://… while the client sends https://…, and /oauth/authorize answers invalid_target every time. Setting PUBLIC_BASE_URL fixes this half on its own, which is why it is in the block above.
• The session cookie loses its Secure flag, because AUTH_COOKIE_SECURE=auto follows the same forwarded scheme. AUTH_COOKIE_SECURE=1 fixes this half on its own.

The server watches for the mistake rather than guessing at it: the first request that arrives carrying an X-Forwarded-* header this instance is not trusting logs one warning naming all three.

Name the proxy, not the network your clients are on. The list is matched against every hop, not only against the peer — the server walks the chain from the socket outwards, and req.ip is the first address the list does not cover. So TRUST_PROXY=uniquelocal on a LAN where the clients are also on 10.0.0.0/8 or 192.168.0.0/16 protects nothing: a client is walked past exactly as a proxy is, and X-Forwarded-For: 203.0.113.99 puts that value into req.ip again. TRUST_PROXY=1 is the same hazard stated plainly, and is only safe when nothing but the proxy can reach the port at all. A hop count is not accepted — it is a claim the server cannot check, and it goes silently wrong the day a CDN appears in front of the proxy.

Make sure the proxy replaces X-Forwarded-For rather than appending to whatever the client sent (nginx: proxy_set_header X-Forwarded-For $remote_addr;, not $proxy_add_x_forwarded_for, unless a further trusted proxy sits in front of it). A proxy that appends hands the caller the left-most value, and no setting here can tell the difference. See Security for an nginx example that puts Basic authentication in front of the dashboard.

Applying changes

docker compose up -d      # recreates the container with the new .env

Most settings take effect immediately. A few need a little more:

• EMBEDDING_MODEL — the next index run becomes a full re-index automatically. Nothing starts that run by itself: the project page shows the mismatch with a Re-index now button, and search stays refused until it is pressed. The run is safe to start at any time of day — it is written beside the old index and published in one step at the end, so the project never passes through “no indexed content”. While it runs, the project holds two copies of its chunks and its share of the vector index, so plan disk for the peak. See Embedding Models.
• EMBEDDING_QUERY_PREFIX / EMBEDDING_PASSAGE_PREFIX — count as changing the model: setting either, including setting both to none, makes every project re-index on its next run.
• EMBEDDING_DIMENSIONS — requires RESET_VECTORS=1 once; see Embedding Models.
• CHUNK_MAX_TOKENS / CHUNK_OVERLAP_TOKENS — apply to newly indexed files; use Force re-index to rebuild everything.

Upgrading across a default change is its own case: Xenova/multilingual-e5-small became the default after Xenova/paraphrase-multilingual-MiniLM-L12-v2. An installation that never set EMBEDDING_MODEL picks the new one up on upgrade, and every existing project reads as a mismatch until it is re-indexed. Pin the old value in .env to postpone that — and note that going back is not a matter of reverting the setting alone: a project already re-indexed under the new model needs another re-index to return.

Checking what is live

GET /api/health reports the running configuration: database status, embedding provider, model, dimensions, dtype and readiness and its input window, whether CHUNK_MAX_TOKENS fits that window, open MCP sessions, allowed document roots, the data directory, whether SECRET_KEY is configured, and the upload limits. The dashboard’s top bar shows the important ones.

It answers with less detail the less it knows about the caller: an anonymous request — a monitor, or the container’s own health check — gets ok, the version, the database status and whether setup is still pending, and nothing that describes the machine. Sign in, or use ADMIN_TOKEN, for the rest.

GET /metrics is a separate, Prometheus-shaped endpoint with its own credential rules — see Admin API.