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
| 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 |
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 |
Accounts and sessions
People sign in to the dashboard with their own account; these settings shape how that works. See 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.
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 |
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 and Running on Kubernetes |
RESET_VECTORS |
0 |
One-time destructive reset when changing embedding dimensions — see 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:
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 |
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 |
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. 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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 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 |
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 |
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 |
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 |
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:
96is 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.
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.
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:
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_ATTEMPTSfailures from one person answer429to everybody. - MCP connectors stop being able to authorize. With
PUBLIC_BASE_URLunset, the OAuth protected-resource metadata and theWWW-Authenticatepointer are built fromreq.protocol— which readshttp— so the document advertiseshttp://…while the client sendshttps://…, and/oauth/authorizeanswersinvalid_targetevery time. SettingPUBLIC_BASE_URLfixes this half on its own, which is why it is in the block above. - The session cookie loses its
Secureflag, becauseAUTH_COOKIE_SECURE=autofollows the same forwarded scheme.AUTH_COOKIE_SECURE=1fixes 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
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 tonone, makes every project re-index on its next run.EMBEDDING_DIMENSIONS— requiresRESET_VECTORS=1once; 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, 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.