docs(env): slim .env.example to essentials and fill env-var doc gaps

CLAUDE.md

@@ -17,7 +17,6 @@ infra/          # All deployment infrastructure
   scripts/      #   entrypoint.sh and other deployment scripts
   ansible/      #   Ansible playbooks
   charts/       #   Helm charts (openrag-stack)
-  quick_start/  #   Getting-started compose
   cluster.yaml  #   Ray cluster config
 scripts/        # Developer/operational CLI tools (check_layer_imports.py, data_indexer.py, postgres-init/)
 tests/          # Integration tests (api_tests/, integration/)

README.md

@@ -143,50 +143,34 @@ Create a `.env` file under `infra/compose/`, mirroring the structure of `infra/c
 cp infra/compose/.env.example infra/compose/.env
 ```
 #### 3. File Parser configuration 
-All supported file format parsers are pre-configured. For PDF processing, **[MarkerLoader](https://github.com/datalab-to/marker)** serves as the default parser, offering comprehensive support for OCR-scanned documents, complex layouts, tables, and embedded images. MarkerLoader operates efficiently on both GPU and CPU environments.
+All supported file format parsers are pre-configured. For PDF processing, **[PyMuPDFLoader](https://pymupdf.readthedocs.io/)** is the default parser — a lightweight, fast, CPU-friendly engine well suited to searchable PDFs and quick local testing.
+
+> ⚠️ **Important**: `PyMuPDFLoader` cannot process non-searchable (image-based / scanned) PDFs and does not run OCR or extract embedded images.
 
 <details>
 <summary>For more PDF options</summary>
 
-For CPU-only deployments or lightweight testing scenarios, you can consider switching to **`PyMuPDFLoader`**. To change the loader, set the **`PDFLoader`** variable like this `PDFLoader=PyMuPDFLoader`.
-
-> ⚠️ **Important**: These alternative loaders have limitations - they cannot process non-searchable (image-based) PDFs and do not extract or handle embedded images.
+For OCR-scanned documents, complex layouts, tables, or embedded images, switch to **[`MarkerLoader`](https://github.com/datalab-to/marker)** (heavier; runs on GPU and CPU) by setting the **`PDFLOADER`** variable: `PDFLOADER=MarkerLoader`. Other options: `DoclingLoader`, `DotsOCRLoader`.
 </details>
 
 #### 4.Deployment: Launch the app
 >[!IMPORTANT]
 > The **admin UI** (a web interface for intuitive document ingestion, indexing, and management) ships bundled as the `admin-ui` service — no separate setup is required. Once the stack is up it is served at `http://localhost:ADMIN_UI_PORT/app/` (default port `8081`).
 
-* **Simple and quick** launch for testing
-  >[!IMPORTANT]
-  > For a **simple `quick deployment`** using only the docker-compose file, only the [quick_start **folder**](./infra/quick_start/) is required. Follow these steps to launch the application:
-
-  1. Navigate to the **`infra/quick_start`** directory or download only that folder
-  2. Place your **`.env`** file inside the **`infra/quick_start`** directory
-  3. Run the appropriate command for your system:
-
-  ```bash
-  # GPU deployment (recommended for optimal performance)
-  docker compose up -d
-  # docker compose down # to stop the application
-
-  # CPU deployment
-  docker compose --profile cpu up -d
-  # docker compose --profile cpu down # to stop the application
-  ```
-* **Development Environment**: For development builds, use the **`--build`** flag to rebuild images:
-  >[!NOTE]
-  > The full stack and its service configs live under `infra/compose/`. Execute these commands from there (`cd infra/compose`).
-
-  ```bash
-  # GPU deployment with rebuild (recommended for optimal performance)
-  docker compose up --build -d
-  # docker compose down # to stop the application
-
-  # CPU deployment with rebuild
-  docker compose --profile cpu up --build -d
-  # docker compose --profile cpu down # to stop the application
-  ```
+The full stack and its service configs live under **`infra/compose/`**. Place the **`.env`** you created there and run the commands from that directory (`cd infra/compose`):
+
+```bash
+# GPU deployment (recommended for optimal performance)
+docker compose up -d
+# docker compose down # to stop the application
+
+# CPU deployment
+docker compose --profile cpu up -d
+# docker compose --profile cpu down # to stop the application
+```
+
+>[!NOTE]
+> For development builds, add the **`--build`** flag to rebuild images from your working tree, e.g. `docker compose up --build -d`.
 
 >[!WARNING]
 > The first startup may take longer as required dependencies are installed. 

docs/assets/env_example.env

@@ -1,62 +1,105 @@
-# LLM
+# ============================================================================
+# OpenRAG — minimal .env
+#
+# Only the variables you must set for the default compose stack to boot are
+# listed here. Every other knob (PDF/audio loaders, chunking, retriever,
+# reranker, Ray Serve, admin UI, OIDC/SSO, rate limiting, MCP server, web
+# search, …) has a sensible default and is documented in full at:
+#
+#   https://linagora.github.io/openrag/documentation/env_vars/
+# ============================================================================
+
+# ── LLM (external, OpenAI-compatible) ───────────────────────────────────────
 BASE_URL=
 API_KEY=
 MODEL=
+LLM_SEMAPHORE=10
 
-# VLM (Visual Language Model) you can set it to the same as LLM if your LLM supports images
+# ── VLM (vision model, used for image understanding) ────────────────────────
+# Can reuse the LLM values above if that model accepts images.
 VLM_BASE_URL=
 VLM_API_KEY=
 VLM_MODEL=
+VLM_SEMAPHORE=20
 
-## FastAPI App (no need to change it)
-# APP_PORT=8080 # this is the forwarded port
-# The uvicorn path runs a single worker by design (Ray provides concurrency).
-# To scale the HTTP layer, use Ray Serve: ENABLE_RAY_SERVE=true with
-# RAY_SERVE_NUM_REPLICAS=N (see the Ray Serve configuration section).
+# ── Embedder (HuggingFace model served by the bundled vLLM) ─────────────────
+# Point these at an external embedding service instead of the bundled vLLM:
 
-## To enable API HTTP authentication via HTTPBearer
-# AUTH_TOKEN=sk-openrag-1234
+EMBEDDER_MODEL_NAME=jinaai/jina-embeddings-v3
+# EMBEDDER_BASE_URL=http://vllm:8000/v1
+# EMBEDDER_API_KEY=EMPTY
+# MAX_MODEL_LEN=2047
 
-# SAVE_UPLOADED_FILES=true # usefull for chainlit (chat interface) source viewing
+# ── Reranker (re-scores retrieved chunks; bundled Infinity server) ───────────
+RERANKER_PROVIDER=infinity  # 'infinity' (bundled, default) or 'openai' (external endpoint)
+RERANKER_MODEL=Alibaba-NLP/gte-multilingual-reranker-base
+RERANKER_ENABLED=true
 
-# Set to true, it will mount chainlit chat ui to the fastapi app (Default: true)
-## WITH_CHAINLIT_UI=true
+## Point these at an external reranker instead of the bundled Infinity / VLLM(Openai) server:
+# RERANKER_BASE_URL=http://reranker:7997
+# RERANKER_API_KEY=EMPTY
 
-# EMBEDDER
-EMBEDDER_MODEL_NAME=jinaai/jina-embeddings-v3 # or other embedder from huggingface compatible with vllm 
-# EMBEDDER_BASE_URL=http://vllm:8000/v1
-# EMBEDDER_API_KEY=EMPTY
 
+# ── PDF parser (default: PyMuPDF — lightweight, CPU-friendly) ────────────────
+# Switch to MarkerLoader for OCR / scanned PDFs, complex layouts & embedded
+# images (heavier — more RAM/GPU). Other option: DoclingLoader.
+PDFLOADER=PyMuPDFLoader
+# Marker tuning (only when PDFLOADER=MarkerLoader):
+# MARKER_POOL_SIZE=1         # marker worker actors (≈ 1 per cluster node / Machine).
+# MARKER_MAX_PROCESSES=2     # concurrent PDFs per worker (raise with more GPU)
+
+# ── Image captioning & chunk contextualization (both ON by default) ──────────
+# Both run during indexing and call the VLM/LLM — set to false to index
+# faster and cheaper (with some retrieval-quality trade-off).
+# IMAGE_CAPTIONING=false       # stop describing images in documents via the VLM
+# CONTEXTUAL_RETRIEVAL=false   # stop prepending LLM-generated context to each chunk (Anthropic technique)
+
+# ── Secrets — dev defaults so the stack boots out of the box ─────────────────
+# ⚠️  Production: replace these with strong values, e.g. `openssl rand -hex 16`.
+# MINIO_* are shared by the minio service and Milvus — both sides must match.
+MINIO_ACCESS_KEY=minioadmin
+MINIO_SECRET_KEY=minioadmin
+POSTGRES_PASSWORD=postgres
+# POSTGRES_USER=root
+
+# ── API and Chainlit (chat interface) authentication ──────────────────────────────
+# Bearer token that bootstraps the admin user and guards the API.
+# ⚠️  Production: replace with a strong value, e.g. `openssl rand -hex 16`.
+# For SSO instead, see https://linagora.github.io/openrag/documentation/oidc/
+AUTH_TOKEN=or-openrag-1234
+# AUTH_MODE=token          # 'token' (default) or 'oidc' for SSO
+# SUPER_ADMIN_MODE=true
 
-# RETRIEVER
-# RETRIEVER_TOP_K=20 # number of top documents to retrieve, before reranking (lower (~10) is faster on CPU | on GPU, you can try to increase the value (~40) ).
+# # FastAPI port (the API and Chainlit chat interface share the same port).
+# APP_PORT=8080
 
-# RERANKER
-RERANKER_ENABLED=true # deactivate the reranker if your CPU is not powerful enough
-RERANKER_MODEL=Alibaba-NLP/gte-multilingual-reranker-base # or jinaai/jina-reranker-v2-base-multilingual
+# # Rate limiting, activated by default (recommended).
+# RATE_LIMIT_ENABLED=false
 
-# Prompts (templates ship inside the package at openrag/prompts/templates;
-# set PROMPTS_DIR only to override with a custom template directory)
-# PROMPTS_DIR=/path/to/custom/templates
 
-# Ray
-RAY_DEDUP_LOGS=0 # turns off ray log deduplication that appear across multiple processes
-RAY_ENABLE_RECORD_ACTOR_TASK_LOGGING=1 # # to enable logs at task level in ray dashboard
+# ──────────────── Chainlit: Chat interface ────────────────
+# Session-cookie signing secret — required once auth is enabled; keep it stable.
+# ⚠️  Production: replace with a generated value:
+#   python -c "import secrets; print(secrets.token_urlsafe(32))"
+CHAINLIT_AUTH_SECRET=openrag-dev-secret
+
+
+# ──────────────── Admin / Indexer UI (React SPA) ────────────────
+# Host port for the admin UI — the document ingestion, indexing & management
+# interface, served at http://<host>:<ADMIN_UI_PORT>/app/. It also proxies the
+# API/auth, so it is the OIDC front door. Zero-config otherwise (same-origin, no
+# CORS); VITE_* build-time options are documented in the env vars reference.
+# ADMIN_UI_PORT=8081
+
+
+
+# ── Ray (kept as-is by the compose stack; see the docs for what each does) ───
+RAY_DEDUP_LOGS=0
+RAY_ENABLE_RECORD_ACTOR_TASK_LOGGING=1
 RAY_task_retry_delay_ms=3000
-RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 # critical with the newest version of UV
-# Attach to an external Ray cluster instead of starting an embedded one (disables the local dashboard).
-# RAY_ADDRESS=ray://X.X.X.X:10001
-# Interface the embedded Ray dashboard binds to. Defaults to 127.0.0.1 (loopback) because the
-# dashboard/job API is unauthenticated (CVE-2023-48022). Set 0.0.0.0 only behind a firewall/auth proxy.
-# RAY_DASHBOARD_HOST=127.0.0.1
-
-# Admin UI (React SPA served by the admin-ui / nginx container)
-# VITE_* settings are baked into the bundle at BUILD time — rebuild with
-# `docker compose build admin-ui` after changing them. Replace X.X.X.X with
-# localhost (local) or your server IP, and APP_PORT with your FastAPI port.
-
-# ADMIN_UI_PORT=8081                            # Host port for the admin UI (nginx). Default is 8081.
-# VITE_API_BASE_URL=                            # API base baked into the SPA. EMPTY (default) = same-origin via
-#                                               # nginx (no CORS). Only set for a browser-direct build.
-# VITE_GRAFANA_URL=                             # Optional Grafana dashboard link on the admin "System" page.
-# VITE_APP_NAME=OpenRAG                         # App display name used in the UI branding.
+RAY_ENABLE_UV_RUN_RUNTIME_ENV=0
+
+# RAY_memory_monitor_refresh_ms=0
+
+# ── Logging (DEBUG on dev, INFO on prod) ──
+LOG_LEVEL=DEBUG