# Configuration

> Every environment variable Contextator reads — server, accounts, database, storage, documents, uploads, embeddings, search, sync, observability and reverse proxies.

- Updated: 2026-11-04
- Source: https://contextator.com/en/docs/configuration/
- Language: en-US
- Author: Muhammet Şafak

---
Everything is an environment variable. With Compose, put them in `.env` next to `docker-compose.yml`;
the shipped [`.env.example`](https://github.com/Contextator/Contextator/blob/main/.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

| Variable | Default | What it does |
|----------|---------|--------------|
| `PORT` | `3444` | The port the application listens on. Under `docker compose` it changes only the port published on the host — inside the container the application stays on `3444` |
| `HOST` | `0.0.0.0` | Bind address **inside the container**. Leave this alone — it is not the setting that controls what is reachable from outside; that is `CONTEXTATOR_BIND` below. Docker cannot forward a published port to a process bound only to the container's own loopback |
| `CONTEXTATOR_BIND` | `127.0.0.1` | **Which host interface `docker compose` publishes the port on** (Compose only — the application itself never reads it). The default answers on this machine and nowhere else. `0.0.0.0` publishes on every interface — do that only with a reverse proxy or a VPN in front, and set `TRUST_PROXY` and `PUBLIC_BASE_URL` to match; see *Running behind a reverse proxy* below |
| `CONTEXTATOR_TAG` | `latest` | Which image tag `docker compose` runs (Compose only — the application never reads it). Pin a version such as `1.0.0` to upgrade deliberately; see [Installation](/en/docs/installation/) |
| `LOG_LEVEL` | `info` | `fatal`…`trace`, or `silent`. Per-request logging turns on at `debug` |
| `PUBLIC_BASE_URL` | – | e.g. `https://docs.example.com`. Used for the URLs shown in the dashboard, and — behind a proxy — for the OAuth metadata MCP connectors read. See *Running behind a reverse proxy* |
| `TRUST_PROXY` | `0` | **Which peers may tell this server where a request came from.** Decides `req.ip` (the per-IP sign-in limit, `/oauth/register`'s per-host budget, the address beside an audit event) and `req.protocol`. `0` ignores `X-Forwarded-*` entirely, which is correct for the shipped Compose shape with nothing in front of it. Behind a real proxy this must be set — see *Running behind a reverse proxy* below |
| `ALLOWED_ORIGINS` | – | Comma-separated browser origins allowed to call `/mcp/*`. Non-browser clients are always allowed |
| `SESSION_IDLE_TTL_MS` | `1800000` | Idle Streamable HTTP **transport** sessions are closed after 30 minutes. Dashboard sign-ins are separate — that is `AUTH_SESSION_IDLE_MS` |
| `MCP_STRUCTURED_OUTPUT` | `0` | `1` makes the MCP tools publish an `outputSchema` and return `structuredContent` beside the unchanged text **to MCP 2025-11-25 clients**; a 2026-07-28 client always gets them and is not affected. Off by default because Claude Code reads the structured content instead of the text once a result carries it — see [MCP Tools](/en/docs/mcp-tools/#structured-output) |

## Accounts and sessions

People sign in to the dashboard with their own account; these settings shape how that works. See
[Accounts and Permissions](/en/docs/accounts-and-permissions/).

| Variable | Default | What it does |
|----------|---------|--------------|
| `SETUP_CODE` | – | The one-time code `/setup` asks for before the first account exists. Set it and you never have to read it out of the log; leave it empty and the server generates one and prints it at every start until that account is created. Ignored from then on. Case, dashes and punctuation are ignored when it is checked, so give it enough letters and digits rather than relying on punctuation |
| `ADMIN_TOKEN` | – | **Machine access** to `/api/*` via `Authorization: Bearer …`, acting with root permissions — for scripts and CI. Browsers sign in with an account instead; treat this like a root password and never paste it into one. **Does not protect `/mcp/*`** |
| `AUTH_SESSION_IDLE_MS` | `43200000` (12 h) | A dashboard session unused for this long has to sign in again. Refreshed while the dashboard is in use |
| `AUTH_SESSION_TTL_DAYS` | `30` | Hard ceiling on a session's life, however actively it is used. Must not be shorter than `AUTH_SESSION_IDLE_MS` |
| `AUTH_COOKIE_SECURE` | `auto` | `auto` sets the `Secure` flag when the request arrives over HTTPS. Force it with `1` behind a terminating proxy; use `0` for a plain-HTTP LAN install, or the browser drops the cookie and sign-in loops back to `/login` |
| `AUTH_LOGIN_MAX_ATTEMPTS` | `10` | Failed sign-ins per account and per IP address before a lockout or a `429` |
| `AUTH_LOGIN_WINDOW_MIN` | `15` | The IP window in minutes, and the first step of the account lockout — which doubles from there, capped at an hour |
| `PASSWORD_MIN_LENGTH` | `12` | Applies to every password, temporary ones included. No composition rules are imposed |
| `MCP_OAUTH` | `1` | The OAuth 2.1 flow that lets a client act as an account on `/mcp/*`. `0` removes it, and then only static tokens open a closed project — browser-based connectors cannot connect at all |
| `MCP_OAUTH_ACCESS_TTL_MIN` | `60` | Life of one access token handed to a connector |
| `MCP_OAUTH_REFRESH_TTL_DAYS` | `30` | A connector left unused this long has to be authorized again |
| `MCP_OAUTH_MAX_CLIENTS` | `200` | Ceiling on dynamically registered connector clients (1 to 100000); it bounds what an unauthenticated `/oauth/register` can write |

Federated sign-in (`OIDC_ISSUER_URL` and the rest of the `OIDC_*` variables) is its own page — see
[Single Sign-On](/en/docs/sso/).

## Database

| Variable | Default | What it does |
|----------|---------|--------------|
| `POSTGRES_PASSWORD` | `contextator` | Password of the embedded PostgreSQL. Applied when the cluster is first created; changing it later needs `ALTER USER` — see [Backup and Data](/en/docs/backup-and-data/) |
| `DATABASE_URL` | – | Empty (the default) means the image starts its own embedded PostgreSQL. Set, it points Contextator at an external PostgreSQL 16 or newer with the `vector` extension, and the embedded server is **not** started — the database is then yours to back up, and `POSTGRES_PASSWORD` and the pgdata volume go unused. Required for the `-slim` image, which has no PostgreSQL in it; also what a source checkout reads (there, the libpq variables `PGHOST`, `PGUSER`, `PGPASSWORD` and `PGDATABASE` work in its place). See [Installation](/en/docs/installation/) and [Running on Kubernetes](/en/docs/kubernetes/) |
| `RESET_VECTORS` | `0` | One-time destructive reset when changing embedding dimensions — see [Embedding Models](/en/docs/embedding-models/) |

## Storage (Compose only)

| Variable | Default | What it does |
|----------|---------|--------------|
| `CONTEXTATOR_PGDATA_VOLUME` | `contextator-pgdata` | Volume name for the database |
| `CONTEXTATOR_MODELS_VOLUME` | `contextator-models` | Volume name for downloaded models |
| `CONTEXTATOR_DATA_VOLUME` | `contextator-data` | Volume name for materialised sources |
| `CONTEXTATOR_PGDATA_PATH` | – | Absolute host directory used **instead of** the volume above |
| `CONTEXTATOR_MODELS_PATH` | – | Same, for models |
| `CONTEXTATOR_DATA_PATH` | – | Same, for materialised sources |
| `DOCS_HOST_PATH` | `./docs` | Host folder mounted read-only at `/docs` |

Examples:

```bash
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

| Variable | Default | What it does |
|----------|---------|--------------|
| `ALLOWED_DOC_ROOTS` | `/docs` | Comma-separated. A local directory source **must** live inside one of these. This is a real security boundary — see [Security](/en/docs/security/) |
| `IGNORE_GLOBS` | – | Comma-separated globs skipped while indexing, e.g. `**/CHANGELOG.md,drafts/**`. Applies to every source |
| `DATA_DIR` | `.data` (`/data` in the container) | Writable directory holding git checkouts, uploads and Notion pulls |
| `SECRET_KEY` | – | At least 32 characters (`openssl rand -hex 32`). Encrypts git, Notion, Confluence and GitHub tokens, S3 key pairs, Google Drive keys and webhook secrets at rest (AES-256-GCM). Needed only once such a source exists. Changing it on its own leaves every stored token unreadable — rotate it instead: set `SECRET_KEY_PREVIOUS` to the retiring key, set the new `SECRET_KEY`, restart, run `npm run rotate-secret`, then remove `SECRET_KEY_PREVIOUS` and restart again. See the rotation runbook on [Security](/en/docs/security/#rotating-things) |
| `SECRET_KEY_PREVIOUS` | – | The key being retired, set only for the length of a rotation (above). It never encrypts — reads fall back to it, every write uses `SECRET_KEY` |
| `SOURCE_ALLOWED_HOSTS` | – | New in 0.6.0. Comma-separated host names (or IP literals) that a Confluence source, an S3 source's endpoint and the GitHub Enterprise Server host of a GitHub source may reach **on a private address** (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `198.18.0.0/15`, `fc00::/7`, `fec0::/10`), e.g. `wiki.corp.example`. Needed for a Confluence Data Center instance on the internal network; loopback, link-local (`169.254.169.254` included), unspecified and multicast addresses and the reserved `240.0.0.0/4` stay refused whatever is listed. Checked on the connected address and again on every redirect. See [Confluence](/en/docs/confluence/#a-data-center-on-the-internal-network). Names, not URLs; it does not admit a host for a web or git source. Helm: `config.sourceAllowedHosts` |
| `CONFLUENCE_ALLOWED_HOSTS` | – | **Removed in 1.0.0.** A non-empty value stops the server from starting, with a message that names `SOURCE_ALLOWED_HOSTS`; move its hosts there before upgrading. An empty or unset value is accepted. With the Helm chart the setting is `config.sourceAllowedHosts`; `config.confluenceAllowedHosts` was removed in chart 3.0.0. See the [compatibility policy](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md) |
| `WEB_ALLOWED_HOSTS` | – | Comma-separated host names (or IP literals) a documentation-site (web) source may reach **on a private address** — the same ranges and the same always-refused addresses as `SOURCE_ALLOWED_HOSTS`. Needed for a site on the internal network; from 0.3.1 a web source on an internal host stops working until it is listed. Names, not URLs; independent of the other lists. Helm: `config.webAllowedHosts`. See [Documentation site source](/en/docs/documentation-site-source/#internal-addresses) |
| `GIT_ALLOWED_HOSTS` | – | Comma-separated host names (or IP literals) a git source's remote may reach **on a private address** — the same ranges and the same always-refused addresses as `SOURCE_ALLOWED_HOSTS`. Needed for a git server on the internal network, a self-hosted Gitea for example; from 0.3.1 such a source stops working until it is listed. Names, not URLs; independent of the other lists. Helm: `config.gitAllowedHosts`. See [Git repository source](/en/docs/git-repository-source/#a-git-server-on-the-internal-network) |
| `GIT_MAX_PACK_BYTES` | `268435456` (256 MiB) | Minimum `1048576` (1 MiB). The most bytes one response from a git remote (the ref list, or the pack of a clone or update) may carry; a larger one fails the sync with an error that names this setting. Not a memory cap: the git library holds a pack in memory and copies it twice, so a fetch can use about **twice this value** on top of the instance's own use — raise it together with the container's memory limit, and keep that limit well above twice the value. Helm: `config.gitMaxPackBytes`. New in 0.3.2. See [Git repository source](/en/docs/git-repository-source/#how-large-a-response-may-be) |
| `CONFLUENCE_MAX_PAGES` | `5000` | Pages one Confluence sync may fetch (1 to 100000) |
| `NOTION_MAX_PAGES` | `5000` | Pages one Notion sync may fetch (1 to 100000) |
| `S3_MAX_OBJECTS` | `5000` | 1 to 100 000. Objects one S3 source indexes at most: the first ones in key order. Helm: `config.s3MaxObjects` |
| `GDRIVE_MAX_FILES` | `5000` | 1 to 100 000. Files one Google Drive source indexes at most: the first ones in walk order. Helm: `config.gdriveMaxFiles` |
| `GITHUB_MAX_ISSUES` / `GITHUB_MAX_DISCUSSIONS` | `5000` each | 1 to 100 000. Issues and Discussions one GitHub source indexes at most, the most recently created first. Helm: `config.githubMaxIssues`, `config.githubMaxDiscussions` |
| `MAX_STORED_DOCUMENT_BYTES` | `1048576` (1 MB) | Minimum `4096`. How much of each document's text is kept in the database for `read_document`. Past it, the prefix is stored and the tool says so. Compressed out of line by PostgreSQL, so the cost is a small fraction of the same document's vectors |
| `MAX_CONVERTED_FILE_BYTES` | `33554432` (32 MiB) | Checked against the size the scan recorded, before the file is read, so a limit is never applied to bytes already in memory. `.md`, `.mdx` and `.txt` are decoded rather than parsed and are not capped |
| `MAX_PDF_PAGES` | `2000` | Refuses a PDF that declares more pages than this before every page is read into memory at once |
| `MAX_DOCX_UNPACKED_BYTES` | `268435456` (256 MiB) | A `.docx` is a zip whose directory reports a size its author writes; each part is inflated through a counter and discarded once this ceiling is crossed, which is what actually bounds a zip bomb |
| `CONVERSION_TIMEOUT_MS` | `120000` (2 min) | A file still converting past this is refused by name, the same as an unreadable PDF; the worker thread is replaced and the run carries on |
| `CONVERSION_IDLE_MS` | `60000` (1 min) | The conversion worker thread is kept warm between files and dropped after this much idle time, so a quiet server is not holding the heap a large document grew |
| `MAX_SPEC_FILE_BYTES` | `8388608` (8 MiB) | Largest OpenAPI/Swagger file read as a spec (minimum 16384); a bigger one is refused rather than loaded whole |
| `CONVERSION_WORKER_MAX_HEAP_MB` | unset (no cap) | Optional cap, in MiB, on the conversion thread's heap. For a memory-limited container: a file that crosses it is refused by name and the run carries on, instead of the kernel's OOM killer taking the whole process |
| `WEB_MAX_PAGES` | `1000` | Pages one web crawl may fetch (1 to 50000) |
| `WEB_MAX_DEPTH` | `10` | Link depth a crawl follows from its start page (0 to 25) |
| `WEB_REQUEST_DELAY_MS` | `500` | Pause between requests to the same site, in milliseconds (0 to 60000) |
| `WEB_CRAWL_BUDGET_MS` | `900000` (15 min) | Wall-clock budget for one crawl (at least 1000) |
| `WEB_RESPECT_ROBOTS` | `1` | `0` stops the crawler from honouring `robots.txt` |

## Uploads

| Variable | Default | What it does |
|----------|---------|--------------|
| `UPLOAD_MAX_FILE_BYTES` | `52428800` (50 MB) | Per uploaded file |
| `UPLOAD_MAX_FILES_PER_REQUEST` | `500` | The dashboard splits large folders across requests by itself |
| `UPLOAD_MAX_ARCHIVE_BYTES` | `268435456` (256 MB) | Per uploaded archive |
| `ARCHIVE_MAX_ENTRIES` | `20000` | Guard applied while extracting |
| `ARCHIVE_MAX_TOTAL_BYTES` | `1073741824` (1 GB) | Guard applied while extracting |
| `DATA_DIR_MIN_FREE_BYTES` | `536870912` (512 MiB) | The free space `DATA_DIR` must keep. An upload, and a forced re-index on the embedded database, is refused with `507 insufficient_disk` below it; a project import needs it **plus four times the archive's size**, checked before the upload is read and again before it is unpacked. The check is advisory, and `0` turns it off. See [Backup and Data](/en/docs/backup-and-data/#moving-one-project) |

## Embeddings

| Variable | Default | What it does |
|----------|---------|--------------|
| `EMBEDDING_PROVIDER` | `local` | `local` (CPU, no API key) or `openai` |
| `EMBEDDING_MODEL` | `Xenova/multilingual-e5-small` | Any transformers.js feature-extraction model. Previous default, reads only 128 tokens: `Xenova/paraphrase-multilingual-MiniLM-L12-v2`. English-only and faster: `Xenova/all-MiniLM-L6-v2`. All three are 384-d |
| `EMBEDDING_DIMENSIONS` | `384` | **Must match the model.** `1536` for `text-embedding-3-small` |
| `EMBEDDING_DTYPE` | `fp32` | `q8` downloads a ~4× smaller quantized model |
| `EMBEDDING_BATCH_SIZE` | `16` | Chunks embedded per batch |
| `MODEL_CACHE_DIR` | `.cache/models` | `/app/.cache/models` inside the container |
| `EMBEDDING_OFFLINE` | `0` | `1` forbids model downloads, the embedding model's and the reranker's alike (air-gapped hosts with a pre-populated cache). See [Air-gapped installations](/en/docs/embedding-models/#air-gapped-installations) |
| `EMBEDDING_BASE_URL` | – | Where the `openai` provider sends its requests, with the path (`http://localhost:11434/v1`). Takes precedence over `OPENAI_BASE_URL`, which is **deprecated since 1.0.0**: it still routes the requests while `EMBEDDING_BASE_URL` is empty, the server logs one warning at startup while that is what it does, and it is removed no sooner than 2.0. Moving from the old name to this one changes the model id once (unless the URL is `api.openai.com`), so each project is re-indexed. With neither set, requests go to OpenAI. The host and port are part of the model id, so pointing at another server re-indexes every project. See [Embedding Models](/en/docs/embedding-models/#using-a-server-of-your-own) |
| `EMBEDDING_REQUEST_DIMENSIONS` | `auto` | `auto`, `always` or `never`. Whether the `openai` provider sends `dimensions` with each request: `auto` does so only for `text-embedding-3-*`, `always` for a model that shortens its vectors on request, `never` for a server that rejects the field |
| `OPENAI_API_KEY` | – | Required for `api.openai.com`; optional when `EMBEDDING_BASE_URL` points elsewhere, where it is sent as a bearer token if set |
| `OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | The model name the endpoint serves. The query and passage prefixes below are looked up from this name, so write the model's real name (`intfloat/multilingual-e5-small`), not a local alias |
| `EMBEDDING_MAX_INPUT_TOKENS` | – | What the model reads **usefully** — the window it was trained at, not where its tokenizer truncates. Left empty, the server discovers it from the loaded model and warns after startup if `CHUNK_MAX_TOKENS` does not fit; set, it overrules that discovery, and a contradicting `CHUNK_MAX_TOKENS` refuses to start |
| `EMBEDDING_TOKENIZER` | – | Only with `EMBEDDING_PROVIDER=openai`. A Hugging Face model id whose `tokenizer.json` matches the model the endpoint serves (`Xenova/multilingual-e5-small`). Chunks are then sized with the model's own tokenizer instead of the characters ÷ 4 estimate, so an endpoint cuts the same chunks the local provider cuts. Only the tokenizer files (`tokenizer.json` and `tokenizer_config.json`) are downloaded, never weights, into `MODEL_CACHE_DIR`, at startup, and startup stops if it cannot be loaded. It is part of the model id: setting or changing it re-indexes every project once. See [Embedding Models](/en/docs/embedding-models/#using-a-server-of-your-own) |
| `EMBEDDING_QUERY_PREFIX` / `EMBEDDING_PASSAGE_PREFIX` | – | The instruction prefixes the model was trained with, put on by the server and never by you. Empty means the model decides: `query: ` / `passage: ` for `multilingual-e5-*`, nothing for anything else. The trailing space matters and `.env` strips an unquoted one, so write `EMBEDDING_QUERY_PREFIX="query: "`. An empty value reads as *unset* rather than *no prefix* — `none` is how you say *no prefix* on a model that has them. Either value is part of the model id: changing one re-indexes every project, exactly as changing `EMBEDDING_MODEL` does. See [Embedding Models](/en/docs/embedding-models/#changing-the-model) |
| `SEARCH_SCORE_FLOOR` | `0.82` | Cosine similarity below which `search_docs` answers *no good match* rather than its best hit. `0` turns it off. Measured against the default embedding model and meaningless on another one |

## 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](/en/docs/indexing/) for the benchmark these came from.

| Variable | Default | What it does |
|----------|---------|---------------|
| `HNSW_EF_SEARCH` | `100` | How many candidates the vector index produces **before** the generation filter is applied — pgvector's own default is 40. Every project has its own partial index, so the candidates are that project's rows; while a project re-indexes, its next generation sits in the same index and is filtered out afterwards. Costs latency on every search |
| `HNSW_ITERATIVE_SCAN` | `relaxed_order` | `relaxed_order`, `strict_order` or `off`. Keeps scanning when the filter leaves fewer hits than asked for, instead of answering short (pgvector 0.8+; on an older release all three settings are ignored and search behaves as it did before). `relaxed_order` returns the rows unordered and the server sorts them itself |
| `HNSW_MAX_SCAN_TUPLES` | `20000` | The ceiling that actually **ends** an iterative scan, counted in tuples of the **project's own** index. Raise it as a project grows, not as the instance does |
| `SEARCH_MAX_PER_DOCUMENT` | `2` | Excerpts one document may contribute to one answer, applied after ranking and refilled from the excerpts below it, so an agent that asked for five still gets five. Measured on the golden set it *gains* a question — what it drops is a near-duplicate of something already on the page. `20` turns it off |
| `SEARCH_NEIGHBOR_CONTEXT` | `1` | Chunks either side of each hit, shown as context around it rather than as further results. `0` turns it off. A chunk is `CHUNK_MAX_TOKENS`, so one either side is about three times the context a hit used to be |
| `SEARCH_RERANK` | `off` | `on` re-scores the fused candidates with a cross-encoder. Off by default — it loads a second model and adds a round trip per search, and the measurement is on [Embedding Models](/en/docs/embedding-models/#cross-lingual-search-is-a-known-limit-and-it-is-not-being-fixed) |
| `SEARCH_RERANK_MODEL` | `Xenova/bge-reranker-base` | The cross-encoder used when `SEARCH_RERANK=on` |
| `SEARCH_RERANK_DTYPE` | `q8` | `fp32`, `fp16` or `q8` |
| `SEARCH_RERANK_MAX_TOKENS` | `128` | Where a question and passage pair is cut (32 to 512) |
| `SEARCH_RERANK_BATCH` | `16` | Pairs per forward pass (1 to 100) |
| `SEARCH_QUERY_LOG` | `1` | Instance-wide switch for the query log; `0` records nothing anywhere, whatever a project's own setting says |
| `SEARCH_QUERY_LOG_RETENTION_DAYS` | `30` | How long a recorded query is kept (1 to 3650); it sweeps `report_gap` reports too |
| `MCP_REPORT_GAP_PER_HOUR` | `20` | How many `report_gap` reports one MCP credential may have accepted per hour; every anonymous caller of an `open` project shares one bucket of the same size. `0` turns the limit off. A report over the limit is answered as a success and dropped. See [MCP Tools](/en/docs/mcp-tools/#report_gap) |
| `SEARCH_MAX_RESULT_CHARS` | `12000` | Ceiling on one rendered `search_docs` answer; past it whole excerpts are dropped and the result says how many. A default answer is around 3 300 characters |

## Sync

| Variable | Default | What it does |
|----------|---------|---------------|
| `SYNC_DEFAULT_INTERVAL_MINUTES` | `60` | The sync interval a **newly created** source is given, in minutes; `0` creates it unscheduled. It never reaches a source that already exists — not on upgrade, and not when this value changes — so an upgrade starts no outbound traffic nobody asked for. Per source, the dashboard and the API accept 5 to 43200 (30 days), or *never* |
| `WEBHOOK_MIN_INTERVAL_MINUTES` | `5` | Minimum gap between webhook-triggered syncs of one source; `0` queues every delivery at once. Read live, so a change applies to sources that have no interval of their own |
| `SYNC_PROBES_PER_TICK` | `10` | How many due sources one tick — one minute — may check. The rest keep their turn, oldest first, and the next tick takes them |
| `SYNC_MAX_SKIP_HOURS` | `24` | The longest a scheduled source may go without a successful sync while its check keeps answering "unchanged" (0 to 720). Past it, the source is synced anyway; that sync is what drops a Notion page that was unshared, or a file rewritten with its modification time restored, which the check cannot see. A page unshared in Notion therefore leaves the index within this many hours, plus the source's own sync interval and up to a minute, plus the time the sync itself takes or a run already in progress. `0` turns the bound off. The price is one real sync per source per this many hours even when nothing changed. A source whose sync keeps failing stays past the bound and runs at every due time until it succeeds. A value below a source's interval syncs it at every due time. Unscheduled sources (*Never*) are not affected |

## Observability

| Variable | Default | What it does |
|----------|---------|---------------|
| `AUDIT_LOG_RETENTION_DAYS` | `365` | How long an audit event is kept. There is no switch for the log itself — every state-changing admin request that succeeds is recorded. See [Admin API](/en/docs/admin-api/#audit-log) |
| `METRICS_TOKEN` | – | A bearer credential that reaches `GET /metrics` and **nothing else**, so scraping does not mean handing Prometheus an `ADMIN_TOKEN`. At least 16 characters — the length is a floor, not entropy, and this endpoint is not rate-limited. Unset, `/metrics` still answers a signed-in account or `ADMIN_TOKEN`, but only while the database is up; an instance that wants to stay readable during an outage sets this. See [Admin API](/en/docs/admin-api/) |
| `METRICS_PUBLIC` | `0` | `1` answers `/metrics` with no credential at all. For a private network, or a proxy that already guards the path — anywhere the port is reachable, leave it off; the exposition describes the instance |

## Chunking

| Variable | Default | What it does |
|----------|---------|--------------|
| `CHUNK_MAX_TOKENS` | `96` | Tokens per chunk, counted with the embedding model's own tokenizer |
| `CHUNK_OVERLAP_TOKENS` | `24` | Overlap between consecutive chunks of one section. Must be smaller than `CHUNK_MAX_TOKENS` |

> **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](/en/docs/indexing/).

---

## Connect with Notion (OAuth)

Three variables turn on **Connect with Notion** in the source dialog, as an alternative to pasting an internal integration
token. Each operator registers a public connection of their own in Notion; there is no Contextator-owned one.

| Variable | Notes |
|----------|-------|
| `NOTION_OAUTH_CLIENT_ID` | The public connection's client id. Set together with the secret |
| `NOTION_OAUTH_CLIENT_SECRET` | Its client secret. A process secret like `OIDC_CLIENT_SECRET`: never stored in the database, returned or logged |
| `NOTION_OAUTH_REDIRECT_URI` | The redirect URI registered on the connection. Defaults to `<PUBLIC_BASE_URL>/api/sources/notion/oauth/callback`. Use a domain name, or `localhost` for a local instance; not an IP address |

Startup is refused, with a message that names the variable, when only one of the id and the secret is set, when both are set
with neither `NOTION_OAUTH_REDIRECT_URI` nor `PUBLIC_BASE_URL`, or when both are set without `SECRET_KEY`. With none of them set
nothing changes and the dashboard shows no button. On Helm, put the id in `env` and the secret in `envSecret`. How the
connection works: [Notion](/en/docs/notion/#connect-with-notion-oauth).

## Scanning documents for secrets and personal numbers

`PII_SCAN` (default `1`, `0` turns it off) looks through the stored text of every document for six kinds of value: an AWS
access key id, a GitHub token, the header of a PEM private key, a JWT, a Turkish citizen number (only with valid check
digits) and an IBAN (only with a valid mod-97). It **reports and does nothing else**: a document is indexed, searched and read
exactly as written, never masked and never skipped, and search results are the same with the scan on and off.

A finding is where the value is (document, line, column) and a masked preview. When `SECRET_KEY` is set it also carries an
HMAC of the value under a key derived from it, which only lets the dashboard say "the same value appears in N documents";
without `SECRET_KEY` findings are written without it and nothing is grouped. The value itself is stored nowhere. The scan runs
in the background after an index run changes a project, and once at startup for everything not yet scanned. Findings are listed
by `GET /api/projects/:id/findings` for a project `editor` and above (a `viewer` gets `403`) and shown on the project page under
**Secrets and personal data**; nothing is on the MCP surface. `PII_SCAN=0` stops new scanning and leaves existing findings in
place. A project export leaves them out and counts them under `excluded.documentFindings`.

## 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**:

```bash
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` (and `true`) was
that hazard stated plainly: it was deprecated in 0.4.1 and is **refused at startup since 0.5.0** — the
process exits with a message that names the value. A hop count is **not** accepted either — it is a claim
the server cannot check, and it goes silently wrong the day a CDN appears in front of the proxy.

An upgrade from 0.4.x with `TRUST_PROXY=1` set is therefore a one-line change to the environment, and it is
needed before the new version will start: name the proxy (`loopback`, its address or its CIDR block), or
use `0` when nothing is in front.

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](/en/docs/security/#putting-authentication-in-front)
for an nginx example that puts Basic authentication in front of the dashboard.

## Applying changes

```bash
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](/en/docs/embedding-models/#changing-the-model).
- `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](/en/docs/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, the database mode (embedded or external) and the upload limits. For administrators it
adds the database target, the allowed document roots, the data directory and whether `SECRET_KEY` is
configured. 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](/en/docs/admin-api/#metrics).
