Contextator
ENTR

Getting started

Configuration

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

Updated:

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: 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.


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_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 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, 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.

Arrow keys to move, Enter to open.