From f45441a9e5986c4ecbc2252387ed376b6f37426a Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 17:09:53 -0400 Subject: [PATCH 01/21] slight-cleanup --- docs/docs/configure/configuration.md | 127 +++++++++++++++++---------- 1 file changed, 80 insertions(+), 47 deletions(-) diff --git a/docs/docs/configure/configuration.md b/docs/docs/configure/configuration.md index 2387c2ce..79a5226a 100644 --- a/docs/docs/configure/configuration.md +++ b/docs/docs/configure/configuration.md @@ -1,48 +1,20 @@ --- -title: Configuration +title: Environment variables and configuration values slug: /configure/configuration --- -# Configuration - OpenRAG supports multiple configuration methods with the following priority: 1. **Environment Variables** (highest priority) 2. **Configuration File** (`config.yaml`) -3. **Langflow Flow Settings** (runtime override) -4. **Default Values** (fallback) +3. **Default Values** (fallback) -## Configuration File +## Environment variables -Create a `config.yaml` file in the project root to configure OpenRAG: +Environment variables will override configuration file settings. +You can create a `.env` file in the project root to set these variables. -```yaml -# OpenRAG Configuration File -provider: - model_provider: "openai" # openai, anthropic, azure, etc. - api_key: "your-api-key" # or use OPENAI_API_KEY env var - -knowledge: - embedding_model: "text-embedding-3-small" - chunk_size: 1000 - chunk_overlap: 200 - ocr: true - picture_descriptions: false - -agent: - llm_model: "gpt-4o-mini" - system_prompt: "You are a helpful AI assistant..." -``` - -## Environment Variables - -Environment variables will override configuration file settings. You can still use `.env` files: - -```bash -cp .env.example .env -``` - -## Required Variables +## Required variables | Variable | Description | | ----------------------------- | ------------------------------------------- | @@ -54,7 +26,7 @@ cp .env.example .env | `LANGFLOW_INGEST_FLOW_ID` | ID of your Langflow ingestion flow | | `NUDGES_FLOW_ID` | ID of your Langflow nudges/suggestions flow | -## Ingestion Configuration +## Ingestion configuration | Variable | Description | | ------------------------------ | ------------------------------------------------------ | @@ -63,10 +35,14 @@ cp .env.example .env - `false` or unset: Uses Langflow pipeline (upload → ingest → delete) - `true`: Uses traditional OpenRAG processor for document ingestion -## Optional Variables +## Optional variables | Variable | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| `OPENSEARCH_HOST` | OpenSearch host (default: `localhost`) | +| `OPENSEARCH_PORT` | OpenSearch port (default: `9200`) | +| `OPENSEARCH_USERNAME` | OpenSearch username (default: `admin`) | +| `LANGFLOW_URL` | Langflow URL (default: `http://localhost:7860`) | | `LANGFLOW_PUBLIC_URL` | Public URL for Langflow (default: `http://localhost:7860`) | | `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET` | Google OAuth authentication | | `MICROSOFT_GRAPH_OAUTH_CLIENT_ID` / `MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET` | Microsoft OAuth | @@ -75,20 +51,27 @@ cp .env.example .env | `SESSION_SECRET` | Session management (default: auto-generated, change in production) | | `LANGFLOW_KEY` | Explicit Langflow API key (auto-generated if not provided) | | `LANGFLOW_SECRET_KEY` | Secret key for Langflow internal operations | +| `DOCLING_OCR_ENGINE` | OCR engine for document processing | +| `LANGFLOW_AUTO_LOGIN` | Enable auto-login for Langflow (default: `False`) | +| `LANGFLOW_NEW_USER_IS_ACTIVE` | New users are active by default (default: `False`) | +| `LANGFLOW_ENABLE_SUPERUSER_CLI` | Enable superuser CLI (default: `False`) | +| `OPENRAG_DOCUMENTS_PATHS` | Document paths for ingestion (default: `./documents`) | -## OpenRAG Configuration Variables +## OpenRAG configuration variables These environment variables override settings in `config.yaml`: -### Provider Settings +### Provider settings -| Variable | Description | Default | -| ------------------ | ---------------------------------------- | -------- | -| `MODEL_PROVIDER` | Model provider (openai, anthropic, etc.) | `openai` | -| `PROVIDER_API_KEY` | API key for the model provider | | -| `OPENAI_API_KEY` | OpenAI API key (backward compatibility) | | +| Variable | Description | Default | +| -------------------- | ---------------------------------------- | -------- | +| `MODEL_PROVIDER` | Model provider (openai, anthropic, etc.) | `openai` | +| `PROVIDER_API_KEY` | API key for the model provider | | +| `PROVIDER_ENDPOINT` | Custom provider endpoint (e.g., Watson) | | +| `PROVIDER_PROJECT_ID`| Project ID for providers (e.g., Watson) | | +| `OPENAI_API_KEY` | OpenAI API key (backward compatibility) | | -### Knowledge Settings +### Knowledge settings | Variable | Description | Default | | ------------------------------ | --------------------------------------- | ------------------------ | @@ -98,11 +81,61 @@ These environment variables override settings in `config.yaml`: | `OCR_ENABLED` | Enable OCR for image processing | `true` | | `PICTURE_DESCRIPTIONS_ENABLED` | Enable picture descriptions | `false` | -### Agent Settings +### Agent settings | Variable | Description | Default | | --------------- | --------------------------------- | ------------------------ | | `LLM_MODEL` | Language model for the chat agent | `gpt-4o-mini` | -| `SYSTEM_PROMPT` | System prompt for the agent | Default assistant prompt | +| `SYSTEM_PROMPT` | System prompt for the agent | "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." | -See `.env.example` for a complete list with descriptions, and `docker-compose*.yml` for runtime usage. +See `docker-compose-*.yml` files for runtime usage examples. + +## Configuration file + +Create a `config.yaml` file in the project root to configure OpenRAG: + +```yaml +# OpenRAG Configuration File +provider: + model_provider: "openai" # openai, anthropic, azure, etc. + api_key: "your-api-key" # or use OPENAI_API_KEY env var + endpoint: "" # For custom provider endpoints (e.g., Watson/IBM) + project_id: "" # For providers that need project IDs (e.g., Watson/IBM) + +knowledge: + embedding_model: "text-embedding-3-small" + chunk_size: 1000 + chunk_overlap: 200 + doclingPresets: "standard" # standard, ocr, picture_description, VLM + ocr: true + picture_descriptions: false + +agent: + llm_model: "gpt-4o-mini" + system_prompt: "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." +``` + +## Default Values and Fallbacks + +When no environment variables or configuration file values are provided, OpenRAG uses default values. +These values can be found in the code base at the following locations. + +### OpenRAG configuration defaults + +These values are are defined in `src/config/config_manager.py`. + +### System configuration defaults + +These fallback values are defined in `src/config/settings.py`. + +### TUI default values + +These values are defined in `src/tui/managers/env_manager.py`. + +### Frontend default values + +These values are defined in `frontend/src/lib/constants.ts`. + +### Docling preset configurations + +These values are defined in `src/api/settings.py`. \ No newline at end of file From 90e5ed3d2dfe86e6b93ff24a215aae60227bfff0 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 17:25:03 -0400 Subject: [PATCH 02/21] tweaks-override-defaults --- README.md | 2 +- .../{configure => reference}/configuration.md | 27 ++++++++++++------- docs/sidebars.js | 12 +++------ 3 files changed, 22 insertions(+), 19 deletions(-) rename docs/docs/{configure => reference}/configuration.md (88%) diff --git a/README.md b/README.md index d79011a0..bc020dae 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ LANGFLOW_CHAT_FLOW_ID=your_chat_flow_id LANGFLOW_INGEST_FLOW_ID=your_ingest_flow_id NUDGES_FLOW_ID=your_nudges_flow_id ``` -See extended configuration, including ingestion and optional variables: [docs/configure/configuration.md](docs/docs/configure/configuration.md) +See extended configuration, including ingestion and optional variables: [docs/reference/configuration.md](docs/docs/reference/configuration.md) ### 3. Start OpenRAG ```bash diff --git a/docs/docs/configure/configuration.md b/docs/docs/reference/configuration.md similarity index 88% rename from docs/docs/configure/configuration.md rename to docs/docs/reference/configuration.md index 79a5226a..a8aeff5f 100644 --- a/docs/docs/configure/configuration.md +++ b/docs/docs/reference/configuration.md @@ -1,18 +1,19 @@ --- title: Environment variables and configuration values -slug: /configure/configuration +slug: /reference/configuration --- -OpenRAG supports multiple configuration methods with the following priority: +OpenRAG supports multiple configuration methods with the following priority, from highest to lowest: -1. **Environment Variables** (highest priority) -2. **Configuration File** (`config.yaml`) -3. **Default Values** (fallback) +1. [Environment variables](#environment-variables) +2. [Configuration file (`config.yaml`)](#configuration-file) +3. [Langflow runtime overrides](#langflow-runtime-overrides) +4. [Default or fallback values](#default-values-and-fallbacks) ## Environment variables -Environment variables will override configuration file settings. -You can create a `.env` file in the project root to set these variables. +Environment variables override configuration file settings. +You can create a `.env` file in the project root to set these variables, or set them in the TUI, which will create a `.env` file for you. ## Required variables @@ -90,7 +91,15 @@ These environment variables override settings in `config.yaml`: See `docker-compose-*.yml` files for runtime usage examples. -## Configuration file +## Langflow runtime overrides + +Langflow runtime overrides allow you to modify component settings at runtime without changing the base configuration. + +Runtime overrides are implemented through **tweaks** - parameter modifications that are passed to specific Langflow components during flow execution. + +For more information on tweaks, see [Input schema (tweaks)](https://docs.langflow.org/concepts-publish#input-schema). + +## Configuration file (`config.yaml) {#configuration-file} Create a `config.yaml` file in the project root to configure OpenRAG: @@ -115,7 +124,7 @@ agent: system_prompt: "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." ``` -## Default Values and Fallbacks +## Default values and fallbacks When no environment variables or configuration file values are provided, OpenRAG uses default values. These values can be found in the code base at the following locations. diff --git a/docs/sidebars.js b/docs/sidebars.js index 3048cb70..1e81a3cd 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -65,19 +65,13 @@ const sidebars = { }, { type: "category", - label: "Configuration", + label: "Reference", items: [ { type: "doc", - id: "configure/configuration", - label: "Environment Variables" + id: "reference/configuration", + label: "Environment Variables and Configuration File" }, - ], - }, - { - type: "category", - label: "Reference", - items: [ { type: "doc", id: "reference/troubleshooting", From 5a4cb3fa85476627c1c690d0e17c4b83a928b08f Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 17:46:11 -0400 Subject: [PATCH 03/21] fix-build-errors --- docs/docs/get-started/install.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index dcb5c5f1..65693875 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -178,8 +178,8 @@ To install OpenRAG with Docker Compose: LANGFLOW_SUPERUSER_PASSWORD=your_langflow_password LANGFLOW_SECRET_KEY=your_secret_key ``` - For more information on configuring OpenRAG with environment variables, see [Environment variables](/configure/configuration). - For additional configuration values, including `config.yaml`, see [Configuration](/configure/configuration). + For more information on configuring OpenRAG with environment variables, see [Environment variables](/reference/configuration). + For additional configuration values, including `config.yaml`, see [Configuration](/reference/configuration). 4. Deploy OpenRAG with Docker Compose based on your deployment type. From ddeeb7e5b6bbfd4fd86950aa83574e1c29499bc6 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 09:55:11 -0400 Subject: [PATCH 04/21] fix-error --- docs/docs/get-started/docker.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index 84f0fca6..594a26b9 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -39,8 +39,8 @@ To install OpenRAG with Docker Compose: LANGFLOW_SUPERUSER_PASSWORD=your_langflow_password LANGFLOW_SECRET_KEY=your_secret_key ``` - For more information on configuring OpenRAG with environment variables, see [Environment variables](/configure/configuration). - For additional configuration values, including `config.yaml`, see [Configuration](/configure/configuration). + For more information on configuring OpenRAG with environment variables, see [Environment variables](/reference/configuration). + For additional configuration values, including `config.yaml`, see [Configuration](/reference/configuration). 4. Deploy OpenRAG with Docker Compose based on your deployment type. From 717b864fec13bc486bb6002360a6e4e8acc76882 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 10:21:42 -0400 Subject: [PATCH 05/21] partial-for-onboarding --- docs/docs/_partial-onboarding.mdx | 51 +++++++++++++++++++++++++++++++ docs/docs/get-started/docker.mdx | 7 +++-- docs/docs/get-started/install.mdx | 41 ++----------------------- 3 files changed, 59 insertions(+), 40 deletions(-) create mode 100644 docs/docs/_partial-onboarding.mdx diff --git a/docs/docs/_partial-onboarding.mdx b/docs/docs/_partial-onboarding.mdx new file mode 100644 index 00000000..aaead4ad --- /dev/null +++ b/docs/docs/_partial-onboarding.mdx @@ -0,0 +1,51 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +### Application onboarding + +The first time you start OpenRAG, whether using the TUI or a `.env` file, a `config.yaml` file is generated if OpenRAG detects one doesn't exist. +The `config.yaml` file controls application configuration, including language model and embedding model provider, Docling ingestion settings, and API keys. + +Values input during onboarding can be changed later in the OpenRAG **Settings** page, except for the language model and embedding model _provider_. The provider can only be selected during onboarding, and you must use the same provider for your language model and embedding model. + +1. Select your language model and embedding model provider, and complete the required fields. + **Your provider can only be selected once, and you must use the same provider for your language model and embedding model.** + The language model can be changed, but the embeddings model cannot be changed. + To change your provider selection, you must restart OpenRAG and delete the `config.yml` file. + + + + 2. If you already entered a value for `OPENAI_API_KEY` in the TUI in Step 5, enable **Get API key from environment variable**. + 3. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. + 4. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 5. Click **Complete**. + + + + 2. Complete the fields for **watsonx.ai API Endpoint**, **IBM API key**, and **IBM Project ID**. + These values are found in your IBM watsonx deployment. + 3. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. + 4. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 5. Click **Complete**. + + + + :::tip + Ollama is not included with OpenRAG. To install Ollama, see the [Ollama documentation](https://docs.ollama.com/). + ::: + 2. Enter your Ollama server's base URL address. + The default Ollama server address is `http://localhost:11434`. + Since OpenRAG is running in a container, you may need to change `localhost` to access services outside of the container. For example, change `http://localhost:11434` to `http://host.docker.internal:11434` to connect to Ollama. + OpenRAG automatically sends a test connection to your Ollama server to confirm connectivity. + 3. Select the **Embedding Model** and **Language Model** your Ollama server is running. + OpenRAG automatically lists the available models from your Ollama server. + 4. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 5. Click **Complete**. + + + + +6. Continue with the [Quickstart](/quickstart). \ No newline at end of file diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index 594a26b9..219e9814 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -3,6 +3,8 @@ title: Docker deployment slug: /get-started/docker --- +import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; + There are two different Docker Compose files. They deploy the same applications and containers, but to different environments. @@ -34,7 +36,6 @@ To install OpenRAG with Docker Compose: ```bash OPENSEARCH_PASSWORD=your_secure_password OPENAI_API_KEY=your_openai_api_key - LANGFLOW_SUPERUSER=admin LANGFLOW_SUPERUSER_PASSWORD=your_langflow_password LANGFLOW_SECRET_KEY=your_secret_key @@ -75,7 +76,9 @@ To install OpenRAG with Docker Compose: - **Backend API**: http://localhost:8000 - **Langflow**: http://localhost:7860 -Continue with the [Quickstart](/quickstart). +6. To use the OpenRAG application and continue with application onboarding, access the frontend at `http://localhost:3000`. + + ## Rebuild all Docker containers diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 27cafb44..040f555f 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -5,6 +5,7 @@ slug: /install import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; OpenRAG can be installed in multiple ways: @@ -79,46 +80,10 @@ For more information on virtual environments, see [uv](https://docs.astral.sh/uv Command completed successfully ``` -7. To open the OpenRAG application, click **Open App**, press 6, or navigate to `http://localhost:3000`. +7. To open the OpenRAG application and continue with application onboarding, click **Open App**, press 6, or navigate to `http://localhost:3000`. The application opens. -8. Select your language model and embedding model provider, and complete the required fields. - **Your provider can only be selected once, and you must use the same provider for your language model and embedding model.** - The language model can be changed, but the embeddings model cannot be changed. - To change your provider selection, you must restart OpenRAG and delete the `config.yml` file. - - - 9. If you already entered a value for `OPENAI_API_KEY` in the TUI in Step 5, enable **Get API key from environment variable**. - 10. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. - 11. To load 2 sample PDFs, enable **Sample dataset**. - This is recommended, but not required. - 12. Click **Complete**. - - - - 9. Complete the fields for **watsonx.ai API Endpoint**, **IBM API key**, and **IBM Project ID**. - These values are found in your IBM watsonx deployment. - 10. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. - 11. To load 2 sample PDFs, enable **Sample dataset**. - This is recommended, but not required. - 12. Click **Complete**. - - - - 9. Enter your Ollama server's base URL address. - The default Ollama server address is `http://localhost:11434`. - Since OpenRAG is running in a container, you may need to change `localhost` to access services outside of the container. For example, change `http://localhost:11434` to `http://host.docker.internal:11434` to connect to Ollama. - OpenRAG automatically sends a test connection to your Ollama server to confirm connectivity. - 10. Select the **Embedding Model** and **Language Model** your Ollama server is running. - OpenRAG automatically lists the available models from your Ollama server. - 11. To load 2 sample PDFs, enable **Sample dataset**. - This is recommended, but not required. - 12. Click **Complete**. - - - - -13. Continue with the [Quickstart](/quickstart). + ### Advanced Setup {#advanced-setup} From 4dd7f5722f42f14817238a1c9b2ec6948f21f01a Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 10:30:31 -0400 Subject: [PATCH 06/21] clarify-yaml-and-make-configuration-mdx --- .../{configuration.md => configuration.mdx} | 58 +++++++++---------- 1 file changed, 27 insertions(+), 31 deletions(-) rename docs/docs/reference/{configuration.md => configuration.mdx} (85%) diff --git a/docs/docs/reference/configuration.md b/docs/docs/reference/configuration.mdx similarity index 85% rename from docs/docs/reference/configuration.md rename to docs/docs/reference/configuration.mdx index a8aeff5f..815397e1 100644 --- a/docs/docs/reference/configuration.md +++ b/docs/docs/reference/configuration.mdx @@ -5,8 +5,8 @@ slug: /reference/configuration OpenRAG supports multiple configuration methods with the following priority, from highest to lowest: -1. [Environment variables](#environment-variables) -2. [Configuration file (`config.yaml`)](#configuration-file) +1. [Environment variables](#environment-variables) - Environment variables in the `.env` control Langflow authentication, Oauth settings, and the required OpenAI API key. +2. [Configuration file (`config.yaml`)](#configuration-file) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding). If the same value is available in `.env` and `config.yaml`, the value in `.env` takes precedence. 3. [Langflow runtime overrides](#langflow-runtime-overrides) 4. [Default or fallback values](#default-values-and-fallbacks) @@ -58,9 +58,7 @@ You can create a `.env` file in the project root to set these variables, or set | `LANGFLOW_ENABLE_SUPERUSER_CLI` | Enable superuser CLI (default: `False`) | | `OPENRAG_DOCUMENTS_PATHS` | Document paths for ingestion (default: `./documents`) | -## OpenRAG configuration variables - -These environment variables override settings in `config.yaml`: +## OpenRAG configuration variables {#openrag-config-variables} ### Provider settings @@ -89,7 +87,30 @@ These environment variables override settings in `config.yaml`: | `LLM_MODEL` | Language model for the chat agent | `gpt-4o-mini` | | `SYSTEM_PROMPT` | System prompt for the agent | "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." | -See `docker-compose-*.yml` files for runtime usage examples. +## Configuration file (`config.yaml) {#configuration-file} + +The `config.yaml` file created during [Application onboarding](/install#application-onboarding) can control the variables in [OpenRAG configuration variables](#openrag-configuration-variables-openrag-config-variables), but is overridden by the `.env` if the variable is present both files. +The `config.yaml` file controls application configuration, including language model and embedding model provider, Docling ingestion settings, and API keys. + +```yaml +config.yaml: +provider: + model_provider: openai + api_key: ${PROVIDER_API_KEY} # optional: can be literal instead + endpoint: https://api.example.com + project_id: my-project + +knowledge: + embedding_model: text-embedding-3-small + chunk_size: 1000 + chunk_overlap: 200 + ocr: true + picture_descriptions: false + +agent: + llm_model: gpt-4o-mini + system_prompt: "You are a helpful AI assistant..." +``` ## Langflow runtime overrides @@ -99,31 +120,6 @@ Runtime overrides are implemented through **tweaks** - parameter modifications t For more information on tweaks, see [Input schema (tweaks)](https://docs.langflow.org/concepts-publish#input-schema). -## Configuration file (`config.yaml) {#configuration-file} - -Create a `config.yaml` file in the project root to configure OpenRAG: - -```yaml -# OpenRAG Configuration File -provider: - model_provider: "openai" # openai, anthropic, azure, etc. - api_key: "your-api-key" # or use OPENAI_API_KEY env var - endpoint: "" # For custom provider endpoints (e.g., Watson/IBM) - project_id: "" # For providers that need project IDs (e.g., Watson/IBM) - -knowledge: - embedding_model: "text-embedding-3-small" - chunk_size: 1000 - chunk_overlap: 200 - doclingPresets: "standard" # standard, ocr, picture_description, VLM - ocr: true - picture_descriptions: false - -agent: - llm_model: "gpt-4o-mini" - system_prompt: "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." -``` - ## Default values and fallbacks When no environment variables or configuration file values are provided, OpenRAG uses default values. From 9056461523319ab145428893a6aeca2166964596 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 10:32:39 -0400 Subject: [PATCH 07/21] better-title --- docs/docs/get-started/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 040f555f..0bb5919d 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -21,7 +21,7 @@ OpenRAG can be installed in multiple ways: - [Docker Compose](https://docs.docker.com/compose/install/) installed. If using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands. - For GPU support: (TBD) -## Python wheel {#install-python-wheel} +## Install the OpenRAG Python wheel {#install-python-wheel} The Python wheel is currently available internally, but will be available on PyPI at launch. The wheel installs the OpenRAG wheel, which includes the TUI for installing, running, and managing OpenRAG. From f9159b67127b27377620a5396c470774b31bb7e2 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 10:33:30 -0400 Subject: [PATCH 08/21] docs-broken-anchor --- docs/docs/reference/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 815397e1..fc29e2f7 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -89,7 +89,7 @@ You can create a `.env` file in the project root to set these variables, or set ## Configuration file (`config.yaml) {#configuration-file} -The `config.yaml` file created during [Application onboarding](/install#application-onboarding) can control the variables in [OpenRAG configuration variables](#openrag-configuration-variables-openrag-config-variables), but is overridden by the `.env` if the variable is present both files. +The `config.yaml` file created during [Application onboarding](/install#application-onboarding) can control the variables in [OpenRAG configuration variables](#openrag-config-variables), but is overridden by the `.env` if the variable is present both files. The `config.yaml` file controls application configuration, including language model and embedding model provider, Docling ingestion settings, and API keys. ```yaml From e81251db765fcf36745a4f71cf64dd306858c318 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 18:01:50 -0400 Subject: [PATCH 09/21] code-review --- docs/docs/reference/configuration.mdx | 127 +++++++++++++------------- 1 file changed, 64 insertions(+), 63 deletions(-) diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index fc29e2f7..e06d371f 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -5,14 +5,69 @@ slug: /reference/configuration OpenRAG supports multiple configuration methods with the following priority, from highest to lowest: -1. [Environment variables](#environment-variables) - Environment variables in the `.env` control Langflow authentication, Oauth settings, and the required OpenAI API key. -2. [Configuration file (`config.yaml`)](#configuration-file) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding). If the same value is available in `.env` and `config.yaml`, the value in `.env` takes precedence. +1. [Configuration file (`config.yaml`)](#configuration-file) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding), and configure the [OpenRAG configuration variables](#openrag-config-variables). These values configure OpenRAG application behavior. +2. [Environment variables](#environment-variables) - Environment variables control how OpenRAG connects to services. Environment variables in the `.env` control underlying services such as Langflow authentication, Oauth settings, and OpenSearch security. 3. [Langflow runtime overrides](#langflow-runtime-overrides) 4. [Default or fallback values](#default-values-and-fallbacks) +## Configuration file (`config.yaml) {#configuration-file} + +The `config.yaml` file controls what OpenRAG _does_, including language model and embedding model provider, Docling ingestion settings, and API keys. +The `config.yaml` file overrides values in the `.env` if the variable is present in both files. + +```yaml +config.yaml: +provider: + model_provider: openai + api_key: ${PROVIDER_API_KEY} # optional: can be literal instead + endpoint: https://api.example.com # optional: only for Ollama or IBM providers + project_id: my-project # optional: only for IBM providers + +knowledge: + embedding_model: text-embedding-3-small + chunk_size: 1000 + chunk_overlap: 200 + ocr: true + picture_descriptions: false + +agent: + llm_model: gpt-4o-mini + system_prompt: "You are a helpful AI assistant..." +``` + +## OpenRAG configuration variables {#openrag-config-variables} + +The OpenRAG configuration variables are generated during [Application onboarding](/install#application-onboarding). These values configure the OpenRAG application behavior. + +### Provider settings + +| Variable | Description | Default | +| -------------------- | ---------------------------------------- | -------- | +| `MODEL_PROVIDER` | Model provider (openai, anthropic, etc.) | `openai` | +| `PROVIDER_API_KEY` | API key for the model provider. | | +| `PROVIDER_ENDPOINT` | Custom provider endpoint. Only used for IBM or Ollama providers. | | +| `PROVIDER_PROJECT_ID`| Project ID for providers. Only required for the IBM watsonx.ai provider. | | +| `OPENAI_API_KEY` | OpenAI API key. | | + +### Knowledge settings + +| Variable | Description | Default | +| ------------------------------ | --------------------------------------- | ------------------------ | +| `EMBEDDING_MODEL` | Embedding model for vector search. | `text-embedding-3-small` | +| `CHUNK_SIZE` | Text chunk size for document processing. | `1000` | +| `CHUNK_OVERLAP` | Overlap between chunks. | `200` | +| `OCR_ENABLED` | Enable OCR for image processing. | `true` | +| `PICTURE_DESCRIPTIONS_ENABLED` | Enable picture descriptions. | `false` | + +### Agent settings + +| Variable | Description | Default | +| --------------- | --------------------------------- | ------------------------ | +| `LLM_MODEL` | Language model for the chat agent. | `gpt-4o-mini` | +| `SYSTEM_PROMPT` | System prompt for the agent. | "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." | + ## Environment variables -Environment variables override configuration file settings. You can create a `.env` file in the project root to set these variables, or set them in the TUI, which will create a `.env` file for you. ## Required variables @@ -23,18 +78,18 @@ You can create a `.env` file in the project root to set these variables, or set | `OPENSEARCH_PASSWORD` | Password for OpenSearch admin user | | `LANGFLOW_SUPERUSER` | Langflow admin username | | `LANGFLOW_SUPERUSER_PASSWORD` | Langflow admin password | -| `LANGFLOW_CHAT_FLOW_ID` | ID of your Langflow chat flow | -| `LANGFLOW_INGEST_FLOW_ID` | ID of your Langflow ingestion flow | -| `NUDGES_FLOW_ID` | ID of your Langflow nudges/suggestions flow | +| `LANGFLOW_CHAT_FLOW_ID` | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | +| `LANGFLOW_INGEST_FLOW_ID` | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | +| `NUDGES_FLOW_ID` | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | ## Ingestion configuration | Variable | Description | | ------------------------------ | ------------------------------------------------------ | -| `DISABLE_INGEST_WITH_LANGFLOW` | Disable Langflow ingestion pipeline (default: `false`) | +| `DISABLE_INGEST_WITH_LANGFLOW` | Disable Langflow ingestion pipeline. Default: `false`. | -- `false` or unset: Uses Langflow pipeline (upload → ingest → delete) -- `true`: Uses traditional OpenRAG processor for document ingestion +- `false` or unset: Uses Langflow pipeline (upload → ingest → delete). +- `true`: Uses traditional OpenRAG processor for document ingestion. ## Optional variables @@ -58,60 +113,6 @@ You can create a `.env` file in the project root to set these variables, or set | `LANGFLOW_ENABLE_SUPERUSER_CLI` | Enable superuser CLI (default: `False`) | | `OPENRAG_DOCUMENTS_PATHS` | Document paths for ingestion (default: `./documents`) | -## OpenRAG configuration variables {#openrag-config-variables} - -### Provider settings - -| Variable | Description | Default | -| -------------------- | ---------------------------------------- | -------- | -| `MODEL_PROVIDER` | Model provider (openai, anthropic, etc.) | `openai` | -| `PROVIDER_API_KEY` | API key for the model provider | | -| `PROVIDER_ENDPOINT` | Custom provider endpoint (e.g., Watson) | | -| `PROVIDER_PROJECT_ID`| Project ID for providers (e.g., Watson) | | -| `OPENAI_API_KEY` | OpenAI API key (backward compatibility) | | - -### Knowledge settings - -| Variable | Description | Default | -| ------------------------------ | --------------------------------------- | ------------------------ | -| `EMBEDDING_MODEL` | Embedding model for vector search | `text-embedding-3-small` | -| `CHUNK_SIZE` | Text chunk size for document processing | `1000` | -| `CHUNK_OVERLAP` | Overlap between chunks | `200` | -| `OCR_ENABLED` | Enable OCR for image processing | `true` | -| `PICTURE_DESCRIPTIONS_ENABLED` | Enable picture descriptions | `false` | - -### Agent settings - -| Variable | Description | Default | -| --------------- | --------------------------------- | ------------------------ | -| `LLM_MODEL` | Language model for the chat agent | `gpt-4o-mini` | -| `SYSTEM_PROMPT` | System prompt for the agent | "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." | - -## Configuration file (`config.yaml) {#configuration-file} - -The `config.yaml` file created during [Application onboarding](/install#application-onboarding) can control the variables in [OpenRAG configuration variables](#openrag-config-variables), but is overridden by the `.env` if the variable is present both files. -The `config.yaml` file controls application configuration, including language model and embedding model provider, Docling ingestion settings, and API keys. - -```yaml -config.yaml: -provider: - model_provider: openai - api_key: ${PROVIDER_API_KEY} # optional: can be literal instead - endpoint: https://api.example.com - project_id: my-project - -knowledge: - embedding_model: text-embedding-3-small - chunk_size: 1000 - chunk_overlap: 200 - ocr: true - picture_descriptions: false - -agent: - llm_model: gpt-4o-mini - system_prompt: "You are a helpful AI assistant..." -``` - ## Langflow runtime overrides Langflow runtime overrides allow you to modify component settings at runtime without changing the base configuration. From 5b81e3b841daaa11179ee7c01b6ccf93351d048b Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 18:16:12 -0400 Subject: [PATCH 10/21] docs-more-env-vars-cleanup --- docs/docs/reference/configuration.mdx | 31 ++------------------------- 1 file changed, 2 insertions(+), 29 deletions(-) diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index e06d371f..712d4082 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -5,39 +5,14 @@ slug: /reference/configuration OpenRAG supports multiple configuration methods with the following priority, from highest to lowest: -1. [Configuration file (`config.yaml`)](#configuration-file) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding), and configure the [OpenRAG configuration variables](#openrag-config-variables). These values configure OpenRAG application behavior. +1. [Configuration file (`config.yaml`)](#configuration-file) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding), and controls the [OpenRAG configuration variables](#openrag-config-variables). 2. [Environment variables](#environment-variables) - Environment variables control how OpenRAG connects to services. Environment variables in the `.env` control underlying services such as Langflow authentication, Oauth settings, and OpenSearch security. 3. [Langflow runtime overrides](#langflow-runtime-overrides) 4. [Default or fallback values](#default-values-and-fallbacks) -## Configuration file (`config.yaml) {#configuration-file} - -The `config.yaml` file controls what OpenRAG _does_, including language model and embedding model provider, Docling ingestion settings, and API keys. -The `config.yaml` file overrides values in the `.env` if the variable is present in both files. - -```yaml -config.yaml: -provider: - model_provider: openai - api_key: ${PROVIDER_API_KEY} # optional: can be literal instead - endpoint: https://api.example.com # optional: only for Ollama or IBM providers - project_id: my-project # optional: only for IBM providers - -knowledge: - embedding_model: text-embedding-3-small - chunk_size: 1000 - chunk_overlap: 200 - ocr: true - picture_descriptions: false - -agent: - llm_model: gpt-4o-mini - system_prompt: "You are a helpful AI assistant..." -``` - ## OpenRAG configuration variables {#openrag-config-variables} -The OpenRAG configuration variables are generated during [Application onboarding](/install#application-onboarding). These values configure the OpenRAG application behavior. +These values control what the OpenRAG application does. ### Provider settings @@ -68,8 +43,6 @@ The OpenRAG configuration variables are generated during [Application onboarding ## Environment variables -You can create a `.env` file in the project root to set these variables, or set them in the TUI, which will create a `.env` file for you. - ## Required variables | Variable | Description | From ccedc06edeb3ce2e5d99fbb3af1a29b91e8ebc5f Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Wed, 1 Oct 2025 11:31:52 -0400 Subject: [PATCH 11/21] docs-update-links-to-fix-build --- docs/docs/core-components/ingestion.mdx | 2 +- docs/docs/reference/configuration.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx index 7e5afb20..bbe878c4 100644 --- a/docs/docs/core-components/ingestion.mdx +++ b/docs/docs/core-components/ingestion.mdx @@ -43,7 +43,7 @@ If OpenRAG detects that the local machine is running on macOS, OpenRAG uses the ## Use OpenRAG default ingestion instead of Docling serve -If you want to use OpenRAG's built-in pipeline instead of Docling serve, set `DISABLE_INGEST_WITH_LANGFLOW=true` in [Environment variables](/configure/configuration#ingestion-configuration). +If you want to use OpenRAG's built-in pipeline instead of Docling serve, set `DISABLE_INGEST_WITH_LANGFLOW=true` in [Environment variables](/reference/configuration#ingestion-configuration). The built-in pipeline still uses the Docling processor, but uses it directly without the Docling Serve API. diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 712d4082..105cb7c5 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -5,7 +5,7 @@ slug: /reference/configuration OpenRAG supports multiple configuration methods with the following priority, from highest to lowest: -1. [Configuration file (`config.yaml`)](#configuration-file) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding), and controls the [OpenRAG configuration variables](#openrag-config-variables). +1. [Configuration file (`config.yaml`)](#openrag-config-variables) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding), and controls the [OpenRAG configuration variables](#openrag-config-variables). 2. [Environment variables](#environment-variables) - Environment variables control how OpenRAG connects to services. Environment variables in the `.env` control underlying services such as Langflow authentication, Oauth settings, and OpenSearch security. 3. [Langflow runtime overrides](#langflow-runtime-overrides) 4. [Default or fallback values](#default-values-and-fallbacks) From 8905f8fab993995d87cac97c74814632f86348b8 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Wed, 1 Oct 2025 14:48:23 -0400 Subject: [PATCH 12/21] add-config-yaml-section-combine-env-vars --- docs/docs/reference/configuration.mdx | 235 +++++++++++++++++--------- docs/sidebars.js | 2 +- 2 files changed, 156 insertions(+), 81 deletions(-) diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 105cb7c5..cb29105f 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -1,90 +1,177 @@ --- -title: Environment variables and configuration values +title: Environment variables slug: /reference/configuration --- -OpenRAG supports multiple configuration methods with the following priority, from highest to lowest: +import Icon from "@site/src/components/icon/icon"; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -1. [Configuration file (`config.yaml`)](#openrag-config-variables) - The `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding), and controls the [OpenRAG configuration variables](#openrag-config-variables). -2. [Environment variables](#environment-variables) - Environment variables control how OpenRAG connects to services. Environment variables in the `.env` control underlying services such as Langflow authentication, Oauth settings, and OpenSearch security. -3. [Langflow runtime overrides](#langflow-runtime-overrides) -4. [Default or fallback values](#default-values-and-fallbacks) +OpenRAG recognizes [supported environment variables](#supported-environment-variables) from the following sources: -## OpenRAG configuration variables {#openrag-config-variables} +* **[Environment variables](#supported-environment-variables)** - Values set in `.env` or `docker-compose.yml` file. +* **[Configuration file variables (`config.yaml`)](#configuration-file)** - Values generated during application onboarding and saved to `config.yaml`. +* **[Langflow runtime overrides](#langflow-runtime-overrides)** - Langflow components may tweak environment variables at runtime. +* **[Default or fallback values](#default-values-and-fallbacks)** - These values are default or fallback values if OpenRAG doesn't find a value. -These values control what the OpenRAG application does. +## Configure environment variables -### Provider settings +Environment variables can be set in a `.env` or `docker-compose.yml` file. -| Variable | Description | Default | -| -------------------- | ---------------------------------------- | -------- | -| `MODEL_PROVIDER` | Model provider (openai, anthropic, etc.) | `openai` | -| `PROVIDER_API_KEY` | API key for the model provider. | | -| `PROVIDER_ENDPOINT` | Custom provider endpoint. Only used for IBM or Ollama providers. | | -| `PROVIDER_PROJECT_ID`| Project ID for providers. Only required for the IBM watsonx.ai provider. | | -| `OPENAI_API_KEY` | OpenAI API key. | | +### Precedence -### Knowledge settings +Environment variables always take precedence over other variables, except when the same variable exists in both [config.yaml](#configuration-file) and the `.env`. In this case, the variable in `config.yaml` will take precedence. -| Variable | Description | Default | -| ------------------------------ | --------------------------------------- | ------------------------ | -| `EMBEDDING_MODEL` | Embedding model for vector search. | `text-embedding-3-small` | -| `CHUNK_SIZE` | Text chunk size for document processing. | `1000` | -| `CHUNK_OVERLAP` | Overlap between chunks. | `200` | -| `OCR_ENABLED` | Enable OCR for image processing. | `true` | -| `PICTURE_DESCRIPTIONS_ENABLED` | Enable picture descriptions. | `false` | +### Set environment variables -### Agent settings +To set environment variables, do the following: -| Variable | Description | Default | -| --------------- | --------------------------------- | ------------------------ | -| `LLM_MODEL` | Language model for the chat agent. | `gpt-4o-mini` | -| `SYSTEM_PROMPT` | System prompt for the agent. | "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." | + + -## Environment variables +Stop OpenRAG, set the values in the .env file, and then start OpenRAG. +```bash +OPENAI_API_KEY=your-api-key-here +EMBEDDING_MODEL=text-embedding-3-small +CHUNK_SIZE=1000 +``` + -## Required variables + +Stop OpenRAG, set the values in the `docker-compose.yml` file, and then start OpenRAG. +```yaml +environment: + - OPENAI_API_KEY=your-api-key-here + - EMBEDDING_MODEL=text-embedding-3-small + - CHUNK_SIZE=1000 +``` -| Variable | Description | -| ----------------------------- | ------------------------------------------- | -| `OPENAI_API_KEY` | Your OpenAI API key | -| `OPENSEARCH_PASSWORD` | Password for OpenSearch admin user | -| `LANGFLOW_SUPERUSER` | Langflow admin username | -| `LANGFLOW_SUPERUSER_PASSWORD` | Langflow admin password | -| `LANGFLOW_CHAT_FLOW_ID` | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | -| `LANGFLOW_INGEST_FLOW_ID` | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | -| `NUDGES_FLOW_ID` | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | + + -## Ingestion configuration +## Supported environment variables -| Variable | Description | -| ------------------------------ | ------------------------------------------------------ | -| `DISABLE_INGEST_WITH_LANGFLOW` | Disable Langflow ingestion pipeline. Default: `false`. | +All OpenRAG configuration can be controlled through environment variables. -- `false` or unset: Uses Langflow pipeline (upload → ingest → delete). -- `true`: Uses traditional OpenRAG processor for document ingestion. +### AI provider settings -## Optional variables +Configure which AI models and providers OpenRAG uses for language processing and embeddings. +For more information, see [Application onboarding](/install#application-onboarding). -| Variable | Description | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------ | -| `OPENSEARCH_HOST` | OpenSearch host (default: `localhost`) | -| `OPENSEARCH_PORT` | OpenSearch port (default: `9200`) | -| `OPENSEARCH_USERNAME` | OpenSearch username (default: `admin`) | -| `LANGFLOW_URL` | Langflow URL (default: `http://localhost:7860`) | -| `LANGFLOW_PUBLIC_URL` | Public URL for Langflow (default: `http://localhost:7860`) | -| `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET` | Google OAuth authentication | -| `MICROSOFT_GRAPH_OAUTH_CLIENT_ID` / `MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET` | Microsoft OAuth | -| `WEBHOOK_BASE_URL` | Base URL for webhook endpoints | -| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS integrations | -| `SESSION_SECRET` | Session management (default: auto-generated, change in production) | -| `LANGFLOW_KEY` | Explicit Langflow API key (auto-generated if not provided) | -| `LANGFLOW_SECRET_KEY` | Secret key for Langflow internal operations | -| `DOCLING_OCR_ENGINE` | OCR engine for document processing | -| `LANGFLOW_AUTO_LOGIN` | Enable auto-login for Langflow (default: `False`) | -| `LANGFLOW_NEW_USER_IS_ACTIVE` | New users are active by default (default: `False`) | -| `LANGFLOW_ENABLE_SUPERUSER_CLI` | Enable superuser CLI (default: `False`) | -| `OPENRAG_DOCUMENTS_PATHS` | Document paths for ingestion (default: `./documents`) | +| Variable | Default | Description | +|----------|---------|-------------| +| `EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model for vector search. | +| `LLM_MODEL` | `gpt-4o-mini` | Language model for the chat agent. | +| `MODEL_PROVIDER` | `openai` | Model provider, such as OpenAI or IBM watsonx.ai. | +| `OPENAI_API_KEY` | - | Your OpenAI API key. Required. | +| `PROVIDER_API_KEY` | - | API key for the model provider. | +| `PROVIDER_ENDPOINT` | - | Custom provider endpoint. Only used for IBM or Ollama providers. | +| `PROVIDER_PROJECT_ID` | - | Project ID for providers. Only required for the IBM watsonx.ai provider. | + +### Document processing + +Control how OpenRAG processes and ingests documents into your knowledge base. +For more information, see [Ingestion](/core-components/ingestion). + +| Variable | Default | Description | +|----------|---------|-------------| +| `CHUNK_OVERLAP` | `200` | Overlap between chunks. | +| `CHUNK_SIZE` | `1000` | Text chunk size for document processing. | +| `DISABLE_INGEST_WITH_LANGFLOW` | `false` | Disable Langflow ingestion pipeline. | +| `DOCLING_OCR_ENGINE` | - | OCR engine for document processing. | +| `OCR_ENABLED` | `false` | Enable OCR for image processing. | +| `OPENRAG_DOCUMENTS_PATHS` | `./documents` | Document paths for ingestion. | +| `PICTURE_DESCRIPTIONS_ENABLED` | `false` | Enable picture descriptions. | + +### Langflow settings + +Configure Langflow authentication. + +| Variable | Default | Description | +|----------|---------|-------------| +| `LANGFLOW_AUTO_LOGIN` | `False` | Enable auto-login for Langflow. | +| `LANGFLOW_CHAT_FLOW_ID` | pre-filled | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | +| `LANGFLOW_ENABLE_SUPERUSER_CLI` | `False` | Enable superuser CLI. | +| `LANGFLOW_INGEST_FLOW_ID` | pre-filled | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | +| `LANGFLOW_KEY` | auto-generated | Explicit Langflow API key. | +| `LANGFLOW_NEW_USER_IS_ACTIVE` | `False` | New users are active by default. | +| `LANGFLOW_PUBLIC_URL` | `http://localhost:7860` | Public URL for Langflow. | +| `LANGFLOW_SECRET_KEY` | - | Secret key for Langflow internal operations. | +| `LANGFLOW_SUPERUSER` | - | Langflow admin username. Required. | +| `LANGFLOW_SUPERUSER_PASSWORD` | - | Langflow admin password. Required. | +| `LANGFLOW_URL` | `http://localhost:7860` | Langflow URL. | +| `NUDGES_FLOW_ID` | pre-filled | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | +| `SYSTEM_PROMPT` | "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." | System prompt for the Langflow agent. | + + +### OAuth provider settings + +Configure OAuth providers and external service integrations. + +| Variable | Default | Description | +|----------|---------|-------------| +| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | - | AWS integrations. | +| `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET` | - | Google OAuth authentication. | +| `MICROSOFT_GRAPH_OAUTH_CLIENT_ID` / `MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET` | - | Microsoft OAuth. | +| `WEBHOOK_BASE_URL` | - | Base URL for webhook endpoints. | + +### OpenSearch settings + +Configure OpenSearch database authentication. + +| Variable | Default | Description | +|----------|---------|-------------| +| `OPENSEARCH_HOST` | `localhost` | OpenSearch host. | +| `OPENSEARCH_PASSWORD` | - | Password for OpenSearch admin user. Required. | +| `OPENSEARCH_PORT` | `9200` | OpenSearch port. | +| `OPENSEARCH_USERNAME` | `admin` | OpenSearch username. | + +### System settings + +Configure general system components, session management, and logging. + +| Variable | Default | Description | +|----------|---------|-------------| +| `LANGFLOW_KEY_RETRIES` | `15` | Number of retries for Langflow key generation. | +| `LANGFLOW_KEY_RETRY_DELAY` | `2.0` | Delay between retries in seconds. | +| `LOG_FORMAT` | - | Log format (set to "json" for JSON output). | +| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR). | +| `MAX_WORKERS` | - | Maximum number of workers for document processing. | +| `SERVICE_NAME` | `openrag` | Service name for logging. | +| `SESSION_SECRET` | auto-generated | Session management.. | + +## Configuration file (`config.yaml`) {#configuration-file} + +A `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding) and contains some of the same configuration variables as environment variables. The variables in `config.yaml` take precedence over environment variables. + +
+Which variables can `config.yaml` override? + +* CHUNK_OVERLAP +* CHUNK_SIZE +* EMBEDDING_MODEL +* LLM_MODEL +* MODEL_PROVIDER +* OCR_ENABLED +* OPENAI_API_KEY (backward compatibility) +* PICTURE_DESCRIPTIONS_ENABLED +* PROVIDER_API_KEY +* PROVIDER_ENDPOINT +* PROVIDER_PROJECT_ID +* SYSTEM_PROMPT +
+ +### Edit the `config.yaml` file + +To manually edit the `config.yaml` file, do the following: +1. Stop OpenRAG. +2. In the `config.yaml` file, change the value `edited:false` to `edited:true`. +4. Make your changes, and then save your file. +3. Start OpenRAG. + +The `config.yaml` value set for `MODEL_PROVIDER` can **not** be changed after onboarding. +If you change this value in `config.yaml`, it will have no effect on restart. +To change your `MODEL_PROVIDER`, you must [delete the OpenRAG containers](/tui#status), delete `config.yaml`, and [install OpenRAG](/install) again. ## Langflow runtime overrides @@ -101,20 +188,8 @@ These values can be found in the code base at the following locations. ### OpenRAG configuration defaults -These values are are defined in `src/config/config_manager.py`. +These values are defined in [`config_manager.py` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/src/config/config_manager.py). ### System configuration defaults -These fallback values are defined in `src/config/settings.py`. - -### TUI default values - -These values are defined in `src/tui/managers/env_manager.py`. - -### Frontend default values - -These values are defined in `frontend/src/lib/constants.ts`. - -### Docling preset configurations - -These values are defined in `src/api/settings.py`. \ No newline at end of file +These fallback values are defined in [`settings.py` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/src/config/settings.py). \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 6fd9a177..7f038137 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -75,7 +75,7 @@ const sidebars = { { type: "doc", id: "reference/configuration", - label: "Environment Variables and Configuration File" + label: "Environment variables" }, ], }, From 045f2090844488ff47d3a4cf59be29660d95569b Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Wed, 1 Oct 2025 14:50:52 -0400 Subject: [PATCH 13/21] docs-cleanup-and-links --- docs/docs/core-components/ingestion.mdx | 2 +- docs/docs/reference/configuration.mdx | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx index bbe878c4..a2d0fbdd 100644 --- a/docs/docs/core-components/ingestion.mdx +++ b/docs/docs/core-components/ingestion.mdx @@ -43,7 +43,7 @@ If OpenRAG detects that the local machine is running on macOS, OpenRAG uses the ## Use OpenRAG default ingestion instead of Docling serve -If you want to use OpenRAG's built-in pipeline instead of Docling serve, set `DISABLE_INGEST_WITH_LANGFLOW=true` in [Environment variables](/reference/configuration#ingestion-configuration). +If you want to use OpenRAG's built-in pipeline instead of Docling serve, set `DISABLE_INGEST_WITH_LANGFLOW=true` in [Environment variables](/reference/configuration#document-processing). The built-in pipeline still uses the Docling processor, but uses it directly without the Docling Serve API. diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index cb29105f..3fe9135d 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -71,7 +71,7 @@ For more information, see [Application onboarding](/install#application-onboardi ### Document processing Control how OpenRAG processes and ingests documents into your knowledge base. -For more information, see [Ingestion](/core-components/ingestion). +For more information, see [Ingestion](/ingestion). | Variable | Default | Description | |----------|---------|-------------| @@ -103,7 +103,6 @@ Configure Langflow authentication. | `NUDGES_FLOW_ID` | pre-filled | This value is pre-filled. The default value is found in [.env.example](https://github.com/langflow-ai/openrag/blob/main/.env.example). | | `SYSTEM_PROMPT` | "You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context." | System prompt for the Langflow agent. | - ### OAuth provider settings Configure OAuth providers and external service integrations. @@ -171,7 +170,7 @@ To manually edit the `config.yaml` file, do the following: The `config.yaml` value set for `MODEL_PROVIDER` can **not** be changed after onboarding. If you change this value in `config.yaml`, it will have no effect on restart. -To change your `MODEL_PROVIDER`, you must [delete the OpenRAG containers](/tui#status), delete `config.yaml`, and [install OpenRAG](/install) again. +To change your `MODEL_PROVIDER`, you must [delete the OpenRAG containers](/get-started/tui#status), delete `config.yaml`, and [install OpenRAG](/install) again. ## Langflow runtime overrides From 3d8ab8b23e8d50be0a458ad6b383f6a29d9cd81b Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 2 Oct 2025 10:28:36 -0400 Subject: [PATCH 14/21] add-config-yaml-to-configuration --- docs/docs/reference/configuration.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 3fe9135d..116a7cb5 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -143,7 +143,9 @@ Configure general system components, session management, and logging. A `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding) and contains some of the same configuration variables as environment variables. The variables in `config.yaml` take precedence over environment variables. -
+For an example `config.yaml` file, see [`config.example.yaml` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/config/config.example.yaml). + +
Which variables can `config.yaml` override? * CHUNK_OVERLAP From ab55049e1f0c5a64761c467e83ff593f57198e88 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 2 Oct 2025 11:23:52 -0400 Subject: [PATCH 15/21] config-yaml-behavior --- docs/docs/reference/configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 116a7cb5..31be7e15 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -141,9 +141,9 @@ Configure general system components, session management, and logging. ## Configuration file (`config.yaml`) {#configuration-file} -A `config.yaml` file is generated with values input during [Application onboarding](/install#application-onboarding) and contains some of the same configuration variables as environment variables. The variables in `config.yaml` take precedence over environment variables. +A `config.yaml` configuration file is generated with values input during [Application onboarding](/install#application-onboarding) and contains some of the same configuration variables as environment variables. The variables in `config.yaml` take precedence over environment variables. -For an example `config.yaml` file, see [`config.example.yaml` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/config/config.example.yaml). +The `config.yaml` file is stored in the `config/` directory of your OpenRAG installation, which is mounted as a volume in the `openrag-backend` Docker container. For an example `config.yaml` file, see [`config.example.yaml` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/config/config.example.yaml).
Which variables can `config.yaml` override? From 98cd715cf46f6a5e5ce1c39a9e35ee2b6e4c8cb2 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 2 Oct 2025 13:24:00 -0400 Subject: [PATCH 16/21] eng-review --- docs/docs/_partial-onboarding.mdx | 5 ++--- docs/docs/get-started/install.mdx | 7 +++---- docs/docs/support/troubleshoot.mdx | 6 +++--- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/docs/_partial-onboarding.mdx b/docs/docs/_partial-onboarding.mdx index 5efbf2eb..2d7fe8cb 100644 --- a/docs/docs/_partial-onboarding.mdx +++ b/docs/docs/_partial-onboarding.mdx @@ -36,10 +36,9 @@ To change your provider selection, you must completely reinstall OpenRAG. ::: 1. Enter your Ollama server's base URL address. The default Ollama server address is `http://localhost:11434`. - Since OpenRAG is running in a container, you may need to change `localhost` to access services outside of the container. For example, change `http://localhost:11434` to `http://host.docker.internal:11434` to connect to Ollama. - OpenRAG automatically sends a test connection to your Ollama server to confirm connectivity. + OpenRAG automatically transforms `localhost` to access services outside of the container, and sends a test connection to your Ollama server to confirm connectivity. 2. Select the **Embedding Model** and **Language Model** your Ollama server is running. - OpenRAG automatically lists the available models from your Ollama server. + OpenRAG retrieves the available models from your Ollama server. 3. To load 2 sample PDFs, enable **Sample dataset**. This is recommended, but not required. 4. Click **Complete**. diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 2fe09d1f..27e94c83 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -10,7 +10,7 @@ import PartialExternalPreview from '@site/docs/_partial-external-preview.mdx'; -[Install the OpenRAG Python wheel](#install-python-wheel) and then use the [OpenRAG Terminal User Interface(TUI)](#setup) to run and configure your OpenRAG deployment with a guided setup process. +[Install the OpenRAG Python wheel](#install-python-wheel), and then run the [OpenRAG Terminal User Interface(TUI)](#setup) to start your OpenRAG deployment with a guided setup process. If you prefer running Docker commands and manually editing `.env` files, see [Deploy with Docker](/get-started/docker). @@ -31,15 +31,14 @@ The `.whl` file is currently available as an internal download during public pre The OpenRAG wheel installs the Terminal User Interface (TUI) for running and managing OpenRAG. -1. Create a new project with a virtual environment using `uv`. - This creates and activates a virtual environment for your project. +1. Create a new project with a virtual environment using `uv init`. ```bash uv init YOUR_PROJECT_NAME cd YOUR_PROJECT_NAME ``` - The terminal prompt won't change like it would when using `venv`, but the `uv` commands will use the project's virtual environment. + The `(venv)` prompt doesn't change, but `uv` commands will automatically use the project's virtual environment. For more information on virtual environments, see the [uv documentation](https://docs.astral.sh/uv/pip/environments). 2. Add the local OpenRAG wheel to your project's virtual environment. diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx index dc62cf43..9946db38 100644 --- a/docs/docs/support/troubleshoot.mdx +++ b/docs/docs/support/troubleshoot.mdx @@ -13,12 +13,12 @@ This page provides troubleshooting advice for issues you might encounter when us ## OpenSearch fails to start -Check that `OPENSEARCH_PASSWORD` set in [Environment variables](/configure/configuration) meets requirements. +Check that `OPENSEARCH_PASSWORD` set in [Environment variables](/reference/configuration) meets requirements. The password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong. ## Langflow connection issues -Verify the `LANGFLOW_SUPERUSER` credentials set in [Environment variables](/configure/configuration) are correct. +Verify the `LANGFLOW_SUPERUSER` credentials set in [Environment variables](/reference/configuration) are correct. ## Memory errors @@ -108,4 +108,4 @@ To reset your local containers and pull new images, do the following: 3. In the OpenRAG TUI, click **Status**, and then click **Upgrade**. When the **Close** button is active, the upgrade is complete. -Close the window and open the OpenRAG appplication. +Close the window and open the OpenRAG appplication. \ No newline at end of file From 8f0612e494fae3ad452d7175ff45d3f52cc52cc0 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 2 Oct 2025 14:04:39 -0400 Subject: [PATCH 17/21] onboarding-selections --- docs/docs/_partial-onboarding.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/docs/_partial-onboarding.mdx b/docs/docs/_partial-onboarding.mdx index 2d7fe8cb..44222371 100644 --- a/docs/docs/_partial-onboarding.mdx +++ b/docs/docs/_partial-onboarding.mdx @@ -5,10 +5,12 @@ import TabItem from '@theme/TabItem'; The first time you start OpenRAG, whether using the TUI or a `.env` file, you must complete application onboarding. -Values input during onboarding can be changed later in the OpenRAG **Settings** page, except for the language model and embedding model _provider_. -**Your provider can only be selected once, and you must use the same provider for your language model and embedding model.** -The language model can be changed, but the embeddings model cannot be changed. -To change your provider selection, you must completely reinstall OpenRAG. +Most values from onboarding can be changed later in the OpenRAG **Settings** page, but there are important restrictions. + +The **language model provider** and **embeddings model provider** can only be selected at onboarding, and you must use the same provider for your language model and embedding model. +To change your provider selection later, you must completely reinstall OpenRAG. + +The **language model** can be changed later in **Settings**, but the **embeddings model** cannot be changed later. @@ -44,5 +46,4 @@ To change your provider selection, you must completely reinstall OpenRAG. 4. Click **Complete**. 5. Continue with the [Quickstart](/quickstart). - - + \ No newline at end of file From ac5ff9725e8acc0b292c6f08bf64228343cda337 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 2 Oct 2025 14:09:41 -0400 Subject: [PATCH 18/21] config-yaml-not-configurable --- docs/docs/reference/configuration.mdx | 59 ++++++++------------------- 1 file changed, 17 insertions(+), 42 deletions(-) diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 31be7e15..b6d6218d 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -9,10 +9,10 @@ import TabItem from '@theme/TabItem'; OpenRAG recognizes [supported environment variables](#supported-environment-variables) from the following sources: -* **[Environment variables](#supported-environment-variables)** - Values set in `.env` or `docker-compose.yml` file. -* **[Configuration file variables (`config.yaml`)](#configuration-file)** - Values generated during application onboarding and saved to `config.yaml`. -* **[Langflow runtime overrides](#langflow-runtime-overrides)** - Langflow components may tweak environment variables at runtime. -* **[Default or fallback values](#default-values-and-fallbacks)** - These values are default or fallback values if OpenRAG doesn't find a value. +* [Environment variables](#supported-environment-variables) - Values set in `.env` or `docker-compose.yml` file. +* [Configuration file variables (`config.yaml`)](#configuration-file) - Values generated during application onboarding and saved to `config.yaml`. These are internal OpenRAG application settings that are not user-configurable, but may override environment variables. +* [Langflow runtime overrides](#langflow-runtime-overrides) - Langflow components may tweak environment variables at runtime. +* [Default or fallback values](#default-values-and-fallbacks) - These values are default or fallback values if OpenRAG doesn't find a value. ## Configure environment variables @@ -20,34 +20,21 @@ Environment variables can be set in a `.env` or `docker-compose.yml` file. ### Precedence -Environment variables always take precedence over other variables, except when the same variable exists in both [config.yaml](#configuration-file) and the `.env`. In this case, the variable in `config.yaml` will take precedence. +Environment variables always take precedence over other variables, except when the same variable exists in both [config.yaml](#configuration-file) and the `.env`. In this case, the variable in `config.yaml` takes precedence. ### Set environment variables -To set environment variables, do the following: +To set environment variables, do the following. - - +1. Stop OpenRAG. , and then +2. Set the values in the `.env` file: + ```bash + OPENAI_API_KEY=your-api-key-here + CHUNK_SIZE=1000 + ``` +3. Start OpenRAG. -Stop OpenRAG, set the values in the .env file, and then start OpenRAG. -```bash -OPENAI_API_KEY=your-api-key-here -EMBEDDING_MODEL=text-embedding-3-small -CHUNK_SIZE=1000 -``` - - - -Stop OpenRAG, set the values in the `docker-compose.yml` file, and then start OpenRAG. -```yaml -environment: - - OPENAI_API_KEY=your-api-key-here - - EMBEDDING_MODEL=text-embedding-3-small - - CHUNK_SIZE=1000 -``` - - - +The Docker Compose files are also populated with values from your `.env`, so you don't need to edit the files manually. ## Supported environment variables @@ -141,9 +128,9 @@ Configure general system components, session management, and logging. ## Configuration file (`config.yaml`) {#configuration-file} -A `config.yaml` configuration file is generated with values input during [Application onboarding](/install#application-onboarding) and contains some of the same configuration variables as environment variables. The variables in `config.yaml` take precedence over environment variables. +A `config.yaml` configuration file is generated with values input during [Application onboarding](/install#application-onboarding) and contains some of the same configuration variables as environment variables. These are internal OpenRAG application settings that are not user-configurable, but may override environment variables. -The `config.yaml` file is stored in the `config/` directory of your OpenRAG installation, which is mounted as a volume in the `openrag-backend` Docker container. For an example `config.yaml` file, see [`config.example.yaml` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/config/config.example.yaml). +For an example `config.yaml` file, see [`config.example.yaml` in the OpenRAG repository](https://github.com/langflow-ai/openrag/blob/main/config/config.example.yaml).
Which variables can `config.yaml` override? @@ -154,7 +141,7 @@ The `config.yaml` file is stored in the `config/` directory of your OpenRAG inst * LLM_MODEL * MODEL_PROVIDER * OCR_ENABLED -* OPENAI_API_KEY (backward compatibility) +* OPENAI_API_KEY * PICTURE_DESCRIPTIONS_ENABLED * PROVIDER_API_KEY * PROVIDER_ENDPOINT @@ -162,18 +149,6 @@ The `config.yaml` file is stored in the `config/` directory of your OpenRAG inst * SYSTEM_PROMPT
-### Edit the `config.yaml` file - -To manually edit the `config.yaml` file, do the following: -1. Stop OpenRAG. -2. In the `config.yaml` file, change the value `edited:false` to `edited:true`. -4. Make your changes, and then save your file. -3. Start OpenRAG. - -The `config.yaml` value set for `MODEL_PROVIDER` can **not** be changed after onboarding. -If you change this value in `config.yaml`, it will have no effect on restart. -To change your `MODEL_PROVIDER`, you must [delete the OpenRAG containers](/get-started/tui#status), delete `config.yaml`, and [install OpenRAG](/install) again. - ## Langflow runtime overrides Langflow runtime overrides allow you to modify component settings at runtime without changing the base configuration. From 1598857552ac406182dab394b0bbd4735522b7a6 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 2 Oct 2025 14:21:30 -0400 Subject: [PATCH 19/21] slight-config-change --- docs/docs/get-started/install.mdx | 8 +++++--- docs/docs/reference/configuration.mdx | 6 +++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 27e94c83..1759e813 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -29,7 +29,7 @@ If you prefer running Docker commands and manually editing `.env` files, see [De The `.whl` file is currently available as an internal download during public preview, and will be published to PyPI in a future release. ::: -The OpenRAG wheel installs the Terminal User Interface (TUI) for running and managing OpenRAG. +The OpenRAG wheel installs the Terminal User Interface (TUI) for configuring and running OpenRAG. 1. Create a new project with a virtual environment using `uv init`. @@ -64,7 +64,9 @@ The OpenRAG wheel installs the Terminal User Interface (TUI) for running and man ## Set up OpenRAG with the TUI {#setup} -**Basic Setup** completes or auto-generates most of the required values to start OpenRAG. +The TUI creates a `.env` file in your OpenRAG directory root and starts OpenRAG. + +**Basic Setup** generates all of the required values except the OpenAI API key. **Basic Setup** does not set up OAuth connections for ingestion from Google Drive, OneDrive, or AWS. For OAuth setup, use **Advanced Setup**. @@ -120,4 +122,4 @@ If the TUI detects a `.env` file in the OpenRAG root directory, it will source a - + \ No newline at end of file diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index b6d6218d..a22f7900 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -16,7 +16,9 @@ OpenRAG recognizes [supported environment variables](#supported-environment-vari ## Configure environment variables -Environment variables can be set in a `.env` or `docker-compose.yml` file. +Environment variables are set in a `.env` file in the root of your OpenRAG project directory. + +The Docker Compose files are populated with values from your `.env`, so you don't need to edit the Compose files manually. ### Precedence @@ -34,8 +36,6 @@ To set environment variables, do the following. ``` 3. Start OpenRAG. -The Docker Compose files are also populated with values from your `.env`, so you don't need to edit the files manually. - ## Supported environment variables All OpenRAG configuration can be controlled through environment variables. From 9bc780ead32c1b5b7b910c9e511a6f497105c87c Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 2 Oct 2025 14:55:35 -0400 Subject: [PATCH 20/21] remove-config-yaml --- docs/docs/core-components/agents.mdx | 2 +- docs/docs/reference/configuration.mdx | 41 +++++++-------------------- 2 files changed, 11 insertions(+), 32 deletions(-) diff --git a/docs/docs/core-components/agents.mdx b/docs/docs/core-components/agents.mdx index 9b4adb4b..3ee4617b 100644 --- a/docs/docs/core-components/agents.mdx +++ b/docs/docs/core-components/agents.mdx @@ -52,7 +52,7 @@ This filter is the [Knowledge filter](/knowledge#create-knowledge-filters), and -For an example of changing out the agent's LLM in OpenRAG, see the [Quickstart](/quickstart#change-components). +For an example of changing out the agent's language model in OpenRAG, see the [Quickstart](/quickstart#change-components). To restore the flow to its initial state, in OpenRAG, click