matanor · matanor · Jan 19, 2026 · Jan 19, 2026 · Jan 24, 2026 · Jan 29, 2026
diff --git a/.env.example b/.env.example
@@ -14,7 +14,7 @@ INGEST_SAMPLE_DATA=true
 # LANGFLOW_TIMEOUT=2400
 # LANGFLOW_CONNECT_TIMEOUT=30
 
-# Per-file processing timeout for document ingestion tasks (in seconds)
+# OPTIONAL: Per-file processing timeout for document ingestion tasks (in seconds)
 # Should be >= LANGFLOW_TIMEOUT to allow long-running ingestion to complete
 # Default: 3600 seconds (60 minutes) total timeout
 # INGESTION_TIMEOUT=3600
@@ -45,6 +45,11 @@ OPENSEARCH_PASSWORD=
 # Default: ./opensearch-data
 OPENSEARCH_DATA_PATH=./opensearch-data
 
+# OpenSearch Connection
+OPENSEARCH_HOST=opensearch
+OPENSEARCH_PORT=9200
+OPENSEARCH_USERNAME=admin
+
 # OpenSearch index name for storing documents
 # Default: documents
 # Change this if you want to use a different index name or avoid conflicts
@@ -123,7 +128,51 @@ NEXT_ALLOWED_DEV_ORIGINS=
 # LANGFLOW_WORKERS=2    # Langflow workers (default: 1)
 # DOCLING_WORKERS=2     # Docling workers (default: 1)
 
+# OPTIONAL: Set the logging level for the Backend service
+# - Supported values: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# - Default: INFO
+# LOG_LEVEL=DEBUG
+
+# OPTIONAL: Disable colored log output (https://no-color.org)
+# - When set (to any value), ANSI color codes are omitted from log output
+# NO_COLOR=1
+
 # OPTIONAL: Enable or disable HTTP access logging events
 # - e.g. INFO:     127.0.0.1:45132 - "GET /tasks HTTP/1.1" 200 OK
 # - Default: true
 # ACCESS_LOG=false
+
+# OpenRAG Configuration
+# The version tag for OpenRAG Docker images (e.g., 'latest', 'v1.0.0').
+# This is automatically managed by the TUI during updates to match the Python package version,
+# but can be pinned here to lock the deployment to a specific version when running OpenRAG with Make commands.
+OPENRAG_VERSION=latest
+
+# The local documents path for ingestion.
+OPENRAG_DOCUMENTS_PATH=./openrag-documents
+
+# Langflow Configuration
+# API Key for authenticating with Langflow.
+# If not provided, OpenRAG will automatically generate one using the superuser credentials
+# (LANGFLOW_SUPERUSER and LANGFLOW_SUPERUSER_PASSWORD).
+LANGFLOW_KEY=
+
+# Number of retry attempts when generating the Langflow API key (default: 15)
+LANGFLOW_KEY_RETRIES=
+
+# Delay in seconds between API key generation retry attempts (default: 2.0)
+LANGFLOW_KEY_RETRY_DELAY=
+
+# Version of Langflow (informational/future use)
+# LANGFLOW_VERSION=
+
+# Logging and Service
+# Format for log messages (default: json)
+LOG_FORMAT=
+# Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+LOG_LEVEL=
+# Service name used in logs (default: openrag)
+SERVICE_NAME=openrag
+# Secret key for session management (auto-generated if not provided)
+SESSION_SECRET=
+
diff --git a/Makefile b/Makefile
@@ -70,7 +70,7 @@ endef
 .PHONY: help check_tools help_docker help_dev help_test help_local help_utils \
        dev dev-cpu dev-local dev-local-cpu stop clean build logs \
        shell-backend shell-frontend install \
-       test test-integration test-ci test-ci-local test-sdk test-os-jwt lint \
+       test test-unit test-integration test-ci test-ci-local test-sdk test-os-jwt lint \
        backend frontend docling docling-stop install-be install-fe build-be build-fe build-os build-lf logs-be logs-fe logs-lf logs-os \
        shell-be shell-lf shell-os restart status health db-reset clear-os-data flow-upload setup factory-reset \
        dev-branch build-langflow-dev stop-dev clean-dev logs-dev logs-lf-dev shell-lf-dev restart-dev status-dev
@@ -226,6 +226,7 @@ help_test: ## Show testing commands
 	@echo ''
 	@echo "$(PURPLE)Unit & Integration Tests:$(NC)"
 	@echo "  $(PURPLE)make test$(NC)            - Run all backend tests"
+	@echo "  $(PURPLE)make test-unit$(NC)       - Run unit tests only (tests/unit/)"
 	@echo "  $(PURPLE)make test-integration$(NC) - Run integration tests (requires infra)"
 	@echo ''
 	@echo "$(PURPLE)CI Tests:$(NC)"
@@ -608,6 +609,11 @@ test: ## Run all backend tests
 	uv run pytest tests/ -v
 	@echo "$(PURPLE)Tests complete.$(NC)"
 
+test-unit: ## Run unit tests only
+	@echo "$(YELLOW)Running unit tests...$(NC)"
+	uv run pytest tests/unit/ -v
+	@echo "$(PURPLE)Unit tests complete.$(NC)"
+
 test-integration: ## Run integration tests (requires infrastructure)
 	@echo "$(YELLOW)Running integration tests (requires infrastructure)...$(NC)"
 	@echo "$(CYAN)Make sure to run 'make dev-local' first!$(NC)"

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -37,8 +37,8 @@ services:
     depends_on:
       - opensearch
     environment:
-      OPENSEARCH_HOSTS: '["https://opensearch:9200"]'
-      OPENSEARCH_USERNAME: "admin"
+      OPENSEARCH_HOSTS: '["https://${OPENSEARCH_HOST:-opensearch}:${OPENSEARCH_PORT:-9200}"]'
+      OPENSEARCH_USERNAME: "${OPENSEARCH_USERNAME:-admin}"
       OPENSEARCH_PASSWORD: ${OPENSEARCH_PASSWORD}
     ports:
       - "5601:5601"
@@ -52,7 +52,7 @@ services:
     depends_on:
       - langflow
     environment:
-      - OPENSEARCH_HOST=opensearch
+      - OPENSEARCH_HOST=${OPENSEARCH_HOST:-opensearch}
       - LANGFLOW_URL=http://langflow:7860
       - LANGFLOW_PUBLIC_URL=${LANGFLOW_PUBLIC_URL}
       - LANGFLOW_AUTO_LOGIN=${LANGFLOW_AUTO_LOGIN}
@@ -64,8 +64,8 @@ services:
       - DISABLE_INGEST_WITH_LANGFLOW=${DISABLE_INGEST_WITH_LANGFLOW:-false}
       - INGEST_SAMPLE_DATA=${INGEST_SAMPLE_DATA:-true}
       - NUDGES_FLOW_ID=${NUDGES_FLOW_ID}
-      - OPENSEARCH_PORT=9200
-      - OPENSEARCH_USERNAME=admin
+      - OPENSEARCH_PORT=${OPENSEARCH_PORT:-9200}
+      - OPENSEARCH_USERNAME=${OPENSEARCH_USERNAME:-admin}
       - OPENSEARCH_PASSWORD=${OPENSEARCH_PASSWORD}
       - OPENAI_API_KEY=${OPENAI_API_KEY}
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
@@ -81,6 +81,21 @@ services:
       - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
       - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
       - OPENSEARCH_INDEX_NAME=${OPENSEARCH_INDEX_NAME:-documents}
+      - LANGFLOW_KEY=${LANGFLOW_KEY}
+      - LANGFLOW_KEY_RETRIES=${LANGFLOW_KEY_RETRIES}
+      - LANGFLOW_KEY_RETRY_DELAY=${LANGFLOW_KEY_RETRY_DELAY}
+      - LANGFLOW_VERSION=${LANGFLOW_VERSION}
+      - LOG_FORMAT=${LOG_FORMAT}
+      - SERVICE_NAME=${SERVICE_NAME}
+      - SESSION_SECRET=${SESSION_SECRET}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+      - NO_COLOR=${NO_COLOR:-}
+      - ACCESS_LOG=${ACCESS_LOG:-true}
+      - LANGFLOW_TIMEOUT=${LANGFLOW_TIMEOUT:-2400}
+      - LANGFLOW_CONNECT_TIMEOUT=${LANGFLOW_CONNECT_TIMEOUT:-30}
+      - INGESTION_TIMEOUT=${INGESTION_TIMEOUT:-3600}
+      - UPLOAD_BATCH_SIZE=${UPLOAD_BATCH_SIZE:-25}
+      - MAX_WORKERS=${MAX_WORKERS:-4}
     volumes:
       - ${OPENRAG_DOCUMENTS_PATH:-./openrag-documents}:/app/openrag-documents:Z
       - ${OPENRAG_KEYS_PATH:-./keys}:/app/keys:U,z

diff --git a/docs/docs/_partial-prereq-no-script.mdx → docs/docs/_partial-prereq-docker.mdx b/docs/docs/_partial-prereq-no-script.mdx → docs/docs/_partial-prereq-docker.mdx
@@ -1,5 +1,3 @@
-* Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
-
 * Install [Podman](https://podman.io/docs/installation) or [Docker](https://docs.docker.com/get-docker/).
 
    The OpenRAG team recommends, at minimum, 8 GB of RAM for container VMs.

diff --git a/docs/docs/_partial-prereq-gpu.mdx b/docs/docs/_partial-prereq-gpu.mdx
@@ -0,0 +1,3 @@
+* Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine.
+If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment that is suitable for most use cases.
+The default CPU-only deployment doesn't prevent you from using GPU acceleration in external services, such as Ollama servers.
diff --git a/docs/docs/_partial-prereq-common.mdx → docs/docs/_partial-prereq-models.mdx b/docs/docs/_partial-prereq-common.mdx → docs/docs/_partial-prereq-models.mdx
@@ -12,8 +12,4 @@
 
    Language models must support tool calling to be compatible with OpenRAG.
 
-   For more information, see [Complete the application onboarding process](#application-onboarding).
-
-* Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine.
-If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment that is suitable for most use cases.
-The default CPU-only deployment doesn't prevent you from using GPU acceleration in external services, such as Ollama servers.
+   For more information, see [Complete the application onboarding process](#application-onboarding).
diff --git a/docs/docs/_partial-prereq-python.mdx b/docs/docs/_partial-prereq-python.mdx
@@ -1 +1 @@
-* Install [Python](https://www.python.org/downloads/release/python-3100/) version 3.13 or later.
+* Install [Python](https://www.python.org/downloads/release/python-3100/) version 3.12 or later.
diff --git a/docs/docs/_partial-prereq-uv.mdx b/docs/docs/_partial-prereq-uv.mdx
@@ -0,0 +1 @@
+* Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
diff --git a/docs/docs/core-components/knowledge-browse.mdx b/docs/docs/core-components/knowledge-browse.mdx
@@ -6,7 +6,7 @@ slug: /knowledge-browse
 import Icon from "@site/src/components/icon/icon";
 import PartialAnonymousUserOwner from '@site/docs/_partial-anonymous-user-owner.mdx';
 
-The **Knowledge** page lists the documents that have been [ingested](/ingestion) into your [OpenSearch knowledge base](/knowledge), specifically in an [OpenSearch index](/knowledge#index) named `documents`.
+The **Knowledge** page lists the documents that have been [ingested](/ingestion) into your [OpenSearch knowledge base](/knowledge), specifically in an [OpenSearch index](/knowledge#index).
 
 To explore the contents of your knowledge base, click <Icon name="Library" aria-hidden="true"/> **Knowledge** to get a list of all ingested documents.
 

diff --git a/docs/docs/core-components/knowledge-connectors.mdx b/docs/docs/core-components/knowledge-connectors.mdx
@@ -117,6 +117,15 @@ You can do this during [initial set up](/docker#setup), or you can add the crede
 </TabItem>
 </Tabs>
 
+## Ingest documents with cloud connectors
+
+See [Ingest files from cloud storage](/ingestion#oauth-ingestion).
+
+## Disconnect and reconnect cloud storage connectors
+
+In OpenRAG, click <Icon name="Settings2" aria-hidden="true"/> **Settings** to manage cloud storage connections.
+You can connect, disconnect, reconnect, and trigger ingestion for each configured connector.
+
 ## See also
 
 * [About knowledge](/knowledge)

diff --git a/docs/docs/core-components/knowledge.mdx b/docs/docs/core-components/knowledge.mdx
@@ -27,13 +27,7 @@ An [OpenSearch index](https://docs.opensearch.org/latest/getting-started/intro/#
 
 By default, all documents you upload to your OpenRAG knowledge base are stored in an index named `documents`.
 
-<!-- TBD - better way to rename -->
-
-It is possible to change the index name by [editing the ingestion flow](/agents#inspect-and-modify-flows).
-However, this can impact dependent processes, such as the [filters](/knowledge-filters) and [**Chat**](/chat), that reference the `documents` index by default.
-Make sure you edit other flows as needed to ensure all processes use the same index name.
-
-If you encounter errors or unexpected behavior after changing the index name, you can [revert the flows to their original configuration](/agents#revert-a-built-in-flow-to-its-original-configuration), or [delete knowledge](/knowledge-browse#delete-knowledge) to clear the existing documents from your knowledge base.
+To change the OpenRAG index name, edit the `OPENSEARCH_INDEX_NAME` [environment variable](/reference/configuration#opensearch-settings).
 
 ## OpenSearch service port
 

diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx
@@ -6,8 +6,10 @@ slug: /docker
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
-import PartialPrereqCommon from '@site/docs/_partial-prereq-common.mdx';
-import PartialPrereqNoScript from '@site/docs/_partial-prereq-no-script.mdx';
+import PartialPrereqModels from '@site/docs/_partial-prereq-models.mdx';
+import PartialPrereqUv from '@site/docs/_partial-prereq-uv.mdx';
+import PartialPrereqGpu from '@site/docs/_partial-prereq-gpu.mdx';
+import PartialPrereqDocker from '@site/docs/_partial-prereq-docker.mdx';
 import PartialPrereqWindows from '@site/docs/_partial-prereq-windows.mdx';
 import PartialPrereqPython from '@site/docs/_partial-prereq-python.mdx';
 import PartialInstallNextSteps from '@site/docs/_partial-install-next-steps.mdx';
@@ -26,9 +28,13 @@ Use this installation method if you don't want to [use the Terminal User Interfa
 
 <PartialPrereqPython />
 
-<PartialPrereqNoScript />
+<PartialPrereqUv />
 
-<PartialPrereqCommon />
+<PartialPrereqDocker />
+
+<PartialPrereqModels />
+
+<PartialPrereqGpu />
 
 ## Prepare your deployment {#setup}
 

diff --git a/docs/docs/get-started/install-options.mdx b/docs/docs/get-started/install-options.mdx
@@ -10,9 +10,8 @@ Select the installation method that best fits your needs:
 
 * **Use the [Terminal User Interface (TUI)](/tui) to manage services**: For guided configuration and simplified service management, install OpenRAG with TUI-managed services. Use one of the following options:
 
-   * [**Automatic installer script**](/install): Run one script to install the required dependencies and OpenRAG.
    * [**`uv`**](/install-uv): Install OpenRAG as a dependency of a new or existing Python project.
-   * [**`uvx`**](/install-uvx): Install OpenRAG without creating a project or modifying your project's dependencies.
+   * [**`uvx`**](/install-uvx): Install OpenRAG without creating a project or modifying your project's dependencies. This option also automatically installs Docker or Podman if neither is present in your environment.
 
 * [**Install OpenRAG on Microsoft Windows**](/install-windows): On Windows machines, you must install OpenRAG within the Windows Subsystem for Linux (WSL).
 

diff --git a/docs/docs/get-started/install-uv.mdx b/docs/docs/get-started/install-uv.mdx
@@ -8,8 +8,10 @@ import TabItem from '@theme/TabItem';
 import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
 import PartialSetup from '@site/docs/_partial-setup.mdx';
 import PartialOAuthCredentials from '@site/docs/_partial-oauth-credentials.mdx';
-import PartialPrereqCommon from '@site/docs/_partial-prereq-common.mdx';
-import PartialPrereqNoScript from '@site/docs/_partial-prereq-no-script.mdx';
+import PartialPrereqModels from '@site/docs/_partial-prereq-models.mdx';
+import PartialPrereqUv from '@site/docs/_partial-prereq-uv.mdx';
+import PartialPrereqGpu from '@site/docs/_partial-prereq-gpu.mdx';
+import PartialPrereqDocker from '@site/docs/_partial-prereq-docker.mdx';
 import PartialPrereqWindows from '@site/docs/_partial-prereq-windows.mdx';
 import PartialPrereqPython from '@site/docs/_partial-prereq-python.mdx';
 import PartialInstallNextSteps from '@site/docs/_partial-install-next-steps.mdx';
@@ -28,9 +30,13 @@ For other installation methods, see [Select an installation method](/install-opt
 
 <PartialPrereqPython />
 
-<PartialPrereqNoScript />
+<PartialPrereqUv />
 
-<PartialPrereqCommon />
+<PartialPrereqDocker />
+
+<PartialPrereqModels />
+
+<PartialPrereqGpu />
 
 ## Install and start OpenRAG with uv
 
@@ -48,12 +54,12 @@ If you encounter errors during installation, see [Troubleshoot OpenRAG](/support
 1. Create a new `uv`-managed Python project:
 
    ```bash
-   uv init PROJECT_NAME --python 3.13
+   uv init PROJECT_NAME --python 3.12
    ```
 
    The `--python` flag ensures that your project uses the minimum required Python version for OpenRAG.
    You can use a later Python version, if you prefer.
-   Or, you can omit this flag if your system's default Python version is 3.13 or later.
+   Or, you can omit this flag if your system's default Python version is 3.12 or later.
 
 2. Change into your new project directory:
 

diff --git a/docs/docs/get-started/install-uvx.mdx b/docs/docs/get-started/install-uvx.mdx
@@ -8,8 +8,9 @@ import TabItem from '@theme/TabItem';
 import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
 import PartialSetup from '@site/docs/_partial-setup.mdx';
 import PartialOAuthCredentials from '@site/docs/_partial-oauth-credentials.mdx';
-import PartialPrereqCommon from '@site/docs/_partial-prereq-common.mdx';
-import PartialPrereqNoScript from '@site/docs/_partial-prereq-no-script.mdx';
+import PartialPrereqModels from '@site/docs/_partial-prereq-models.mdx';
+import PartialPrereqUv from '@site/docs/_partial-prereq-uv.mdx';
+import PartialPrereqGpu from '@site/docs/_partial-prereq-gpu.mdx';
 import PartialPrereqWindows from '@site/docs/_partial-prereq-windows.mdx';
 import PartialPrereqPython from '@site/docs/_partial-prereq-python.mdx';
 import PartialInstallNextSteps from '@site/docs/_partial-install-next-steps.mdx';
@@ -18,28 +19,30 @@ import PartialWatsonxModels from '@site/docs/_partial-watsonx-models.mdx';
 
 Use [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools) to invoke OpenRAG outside of a Python project or without modifying your project's dependencies.
 
-:::tip
-The [automatic installer script](/install) also uses `uvx` to install OpenRAG.
-:::
+This installation method is best for testing OpenRAG by running it outside of a Python project.
+For other installation methods, see [Select an installation method](/install-options).
 
 When you install OpenRAG with `uvx`, you will use the [Terminal User Interface (TUI)](/tui) to configure and manage your OpenRAG deployment.
 
-This installation method is best for testing OpenRAG by running it outside of a Python project.
-For other installation methods, see [Select an installation method](/install-options).
+:::info
+`uvx openrag` installs the latest version of OpenRAG and dependencies, like Docker or Podman, if they aren't already present in your environment.
+:::
 
 ## Prerequisites
 
 <PartialPrereqWindows />
 
 <PartialPrereqPython />
 
-<PartialPrereqNoScript />
+<PartialPrereqUv />
+
+<PartialPrereqModels />
 
-<PartialPrereqCommon />
+<PartialPrereqGpu />
 
 ## Install and run OpenRAG with uvx
 
-1. Create a directory to store your OpenRAG configuration files and data, and then change to that directory:
+1. Create a directory for your OpenRAG configuration files and data, and then change to that directory:
 
    ```bash
    mkdir openrag-workspace
@@ -48,22 +51,23 @@ For other installation methods, see [Select an installation method](/install-opt
 
 2. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), create one at `~/.openrag/tui` before invoking OpenRAG.
 
-3. Invoke OpenRAG:
+3. Invoke OpenRAG and install any missing dependencies:
 
    ```bash
    uvx openrag
    ```
 
-   You can invoke a specific version using any of the [`uvx` version specifiers](https://docs.astral.sh/uv/guides/tools/#requesting-specific-versions), such as `--from`:
+   You can invoke a specific version using any of the [`uvx` version specifiers](https://docs.astral.sh/uv/guides/tools/#requesting-specific-versions), such as `uvx --from openrag==0.1.30 openrag`.
 
-   ```bash
-   uvx --from openrag==0.1.30 openrag
-   ```
+4. If needed, respond to any prompts to install and configure dependencies like Docker or Podman.
+
+The entire setup process can take a few minutes.
+Once the environment is ready, the OpenRAG [Terminal User Interface (TUI)](/tui) starts.
 
-   Invoking OpenRAG with `uvx openrag` creates a cached, ephemeral environment for the TUI in your local `uv` cache.
-   By invoking OpenRAG in a specific directory, your OpenRAG configuration files and data are stored separately from the `uv` cache.
-   Clearing the `uv` cache doesn't remove your entire OpenRAG installation.
-   After clearing the cache, you can re-invoke OpenRAG (`uvx openrag`) to restart the TUI with your preserved configuration and data.
+Invoking OpenRAG with `uvx openrag` creates a cached, ephemeral environment for the TUI in your local `uv` cache.
+Your OpenRAG configuration files and data are stored in `~/.openrag`, which is separate from the `uv` cache.
+Clearing the `uv` cache doesn't remove your entire OpenRAG installation; it only clears `uv` dependencies.
+After clearing the cache, you can re-invoke OpenRAG (`uvx openrag`) to restart the TUI with your preserved configuration and data.
 
 If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		* Install [Python](https://www.python.org/downloads/release/python-3100/) version 3.13 or later.
		* Install [Python](https://www.python.org/downloads/release/python-3100/) version 3.12 or later.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		* Install [uv](https://docs.astral.sh/uv/getting-started/installation/).