docs(env): document 35 missing variables and fix stale defaults

[Ahmath-Gadji]

What

Follow-up to #624: cross-checked every env var the code, compose stack and entrypoints actually read (config-loader mappings, os.getenv call sites, compose interpolation incl. extern includes, shell scripts) against the whole docs tree, and closed the remaining gap — 35 variables documented, plus a few stale defaults fixed.

Added to env_vars.md

• Loaders: PARSE_TIMEOUT; new Docling Loader Configuration subsection (DOCLING_POOL_SIZE, DOCLING_MAX_TASKS_PER_WORKER, DOCLING_NUM_GPUS); WHISPER_NUM_GPUS; TRANSCRIBER_PORT
• Embedder: EMBEDDER_TIMEOUT, EMBEDDER_BATCH_SIZE, EMBEDDER_CONCURRENCY
• Chat pipeline: MAX_OUTPUT_TOKENS; new RAG Pipeline Mode block (RAG_MODE: ChatBotRag vs SimpleRag)
• Retriever: INCLUDE_RELATED, INCLUDE_ANCESTORS, RELATED_LIMIT, MAX_DEPTH, RETRIEVER_ALLOW_FILTERLESS_FALLBACK (linked to the Linked-files page)
• Reranker: RERANKER_PORT
• FastAPI: WITH_OPENAI_API, WITH_CHAINLIT_UI
• Rate limiting: RATE_LIMIT_AUTH_FAILURE, with its fallback chain (RATE_LIMIT_AUTH → 20/minute) — the one gap inside docs(env): slim .env.example to essentials and fill env-var doc gaps #624's own new section
• New Advanced & Legacy Variables section:
  • the six seed-time legacy aliases (LLM_ENDPOINT, LLM_MODEL, VLM_ENDPOINT, EMBEDDER_ENDPOINT, EMBEDDING_MODEL, RERANKER_ENDPOINT) as a compact alias → canonical fallback table, marked "initial seeding only, prefer canonical"
  • operational vars: OPENRAG_CONF_DIR, DATA_DIR, DB_DIR, LOG_DIR, OPENRAG_CONTAINER_STARTUP_TIMEOUT, OPENRAG_BANNER, UVICORN_RELOAD
  • monitoring profile (opt-in): GRAFANA_ADMIN_USER, GRAFANA_ADMIN_PASSWORD
• MinIO note: the infra/quick_start/ stack requires the credentials under different names (MINIO_ROOT_USER/MINIO_ROOT_PASSWORD)

Accuracy fixes (doc default vs conf/config.yaml)

Variable	Doc said	Source says
MAX_MODEL_LEN	8192	2047
MAP_REDUCE_DEBUG	true	false
WITH_SURROUNDING_CHUNKS	true	false

Also repaired the LLM/VLM config tables: a 3-column header over 4-cell rows meant the Default cell of LLM_SEMAPHORE/MAX_LLM_CONTEXT_SIZE (and VLM equivalents) was silently dropped at render.

Verification

Re-ran the sweep after the change: every variable read by the app, compose stack and entrypoints is now either documented or intentionally excluded (script-local shell vars, Helm chart values, extern/chainlit-datalayer submodule dev tooling, OS conventions like NO_COLOR/XDG_CACHE_HOME).

Out of scope / follow-ups spotted

• SEMAPHORE (core/config/loader.py) is currently inert: it fills semaphore.* via setdefault, but conf/config.yaml always pre-populates both keys, so it never fires. Deliberately left undocumented; needs a code fix or removal.
• VDB_iPORT (core/config/loader.py) — mixed-case typo alias mapped right above the correct VDB_PORT; candidate for removal.

Summary by CodeRabbit

• Documentation
  • Expanded the environment-variable reference to reflect OpenRAG v2.0.0, adding options for parse timeouts, Docling loader settings, Whisper/GPU accounting, and multiple embedding tuning knobs.
  • Updated chat/LLM and VLM configuration details, including context-limit behavior and output budgeting, plus RAG pipeline mode.
  • Refreshed retrieval and reranking configuration (including surrounding-chunk defaults and related expansion controls), rate-limiting, and FastAPI mounting flags.
  • Added/clarified notes for service port publishing, MinIO credential naming, legacy aliases, and optional monitoring/admin settings.

[coderabbitai]

Warning

Review limit reached

@Ahmath-Gadji, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9456a1dc-12dc-4bc8-9d11-f46598489428

📥 Commits

Reviewing files that changed from the base of the PR and between 7c2d3d4 and d85db0a.

📒 Files selected for processing (1)

• docs/content/docs/documentation/env_vars.md

📝 Walkthrough

Walkthrough

This PR updates the environment-variable reference for OpenRAG v2.0.0, adding new settings for parsing, loaders, transcription, embeddings, retrieval, service mounts, rate limiting, and advanced/legacy behavior, while revising several documented defaults and notes.

Changes

Environment Variable Documentation

Layer / File(s)	Summary
Indexer, loader, and transcription variables docs/content/docs/documentation/env_vars.md	Adds the v2.0.0 notice, PARSE_TIMEOUT, a Docling Loader Configuration table, WHISPER_NUM_GPUS, and TRANSCRIBER_PORT.
Embedding tuning and storage credentials notes docs/content/docs/documentation/env_vars.md	Changes MAX_MODEL_LEN to 2047, adds EMBEDDER_TIMEOUT/BATCH_SIZE/CONCURRENCY, and clarifies MinIO credential variable names for the quick_start stack.
LLM/VLM, RAG mode, and retriever configuration docs/content/docs/documentation/env_vars.md	Rebuilds LLM/VLM tables, adds RAG_MODE, changes WITH_SURROUNDING_CHUNKS to false, and adds retriever expansion/filter options plus RERANKER_PORT.
Map-reduce, mounting flags, and rate limiting variables docs/content/docs/documentation/env_vars.md	Changes MAP_REDUCE_DEBUG to false, adds WITH_OPENAI_API and WITH_CHAINLIT_UI, and adds RATE_LIMIT_AUTH_FAILURE.
Advanced and legacy variables section docs/content/docs/documentation/env_vars.md	Adds an Advanced & Legacy Variables section for legacy aliases, operational paths/startup settings, and Grafana credentials.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• linagora/openrag#624: Updates the same environment-variable documentation area with overlapping config references and defaults.

Suggested labels: fix

Suggested reviewers: hedhoud

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: documenting missing env vars and correcting stale defaults in docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/complete-env-var-reference

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/docs/documentation/env_vars.md`:
- Around line 265-290: Add blank lines around the rebuilt LLM and VLM
configuration tables in env_vars.md. Update the markdown around the table blocks
so there is an empty line before and after each table to satisfy markdownlint
MD058 and keep GFM/Astro parsing stable. Use the table sections under the LLM
Configuration and VLM Configuration headings as the locations to fix.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 59a851fb-a291-4a77-91a3-256cc65ebb87

📥 Commits

Reviewing files that changed from the base of the PR and between 13562ad and bb58314.

📒 Files selected for processing (1)

• docs/content/docs/documentation/env_vars.md