Configuration

Configuration

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

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

---

Server

Variable	Default	What it does
PORT	3444	The port the application listens on
HOST	0.0.0.0	Bind address. Set 127.0.0.1 to accept only local connections
LOG_LEVEL	info	fatal…trace. Per-request logging turns on at debug
PUBLIC_BASE_URL	–	e.g. https://docs.example.com. Used for the URLs shown in the dashboard when behind a proxy
ADMIN_TOKEN	–	When set, /api/* requires Authorization: Bearer …. The dashboard asks for it once. Does not protect /mcp/*
ALLOWED_ORIGINS	–	Comma-separated browser origins allowed to call /mcp/*. Non-browser clients are always allowed
SESSION_IDLE_TTL_MS	1800000	Idle Streamable HTTP sessions are closed after 30 minutes

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	–	Local development only. The container ignores it and talks to its embedded PostgreSQL
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 and Notion tokens at rest. Needed only once such a source exists; changing it invalidates stored tokens

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

Embeddings

Variable	Default	What it does
EMBEDDING_PROVIDER	local	local (CPU, no API key) or openai
EMBEDDING_MODEL	Xenova/paraphrase-multilingual-MiniLM-L12-v2	Any transformers.js feature-extraction model. English-only and faster: Xenova/all-MiniLM-L6-v2
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 (air-gapped hosts with a pre-populated cache)
OPENAI_API_KEY	–	Required when the provider is openai
OPENAI_EMBEDDING_MODEL	text-embedding-3-small

Chunking

Variable	Default	What it does
CHUNK_MAX_TOKENS	400	Approximate tokens per chunk (tokens ≈ characters ÷ 4)
CHUNK_OVERLAP_TOKENS	50	Overlap between consecutive chunks of one section. Must be smaller than CHUNK_MAX_TOKENS

Worth knowing: MiniLM-class models only look at roughly the first 128–256 word pieces of each input, so with the local models CHUNK_MAX_TOKENS=250 usually retrieves slightly better. 400+ suits OpenAI's 8k window. Changing this only affects files indexed afterwards — force a re-index to apply it everywhere. See Indexing.

---

Applying changes

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

Most settings take effect immediately. Three need a little more:

• EMBEDDING_MODEL — the next index run becomes a full re-index automatically.
• 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.

Checking what is live

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