OpenRAG Documentation

OpenRAG is an open-source platform designed for building agentic Retrieval-Augmented Generation (RAG) systems. It integrates orchestration tools, databases, and LLM providers into a single platform.

OpenRAG is built by combining three core technologies:

• Langflow: Used for building and deploying AI agents and MCP servers. OpenRAG provides full access to Langflow features via an embedded visual editor, allowing you to customize flows, change language models, or replace components.
• OpenSearch: Serves as the underlying database for storing documents and vector embeddings, providing hybrid search capabilities.
• Docling: Handles document parsing and chunking for documents stored in the OpenSearch knowledge base.

OpenRAG provides several SDKs to interact with the system programmatically or integrate it into your own applications:

• Python SDK: For Python-based applications.
• TypeScript/JavaScript SDK: For web or Node.js-based applications.
• MCP API: For connecting MCP clients via the /mcp endpoint.

The OpenRAG operator uses a three-level priority system to manage environment variables for Langflow, Backend, and Frontend components. When multiple values are defined for the same variable, the system resolves them based on the following priority (highest to lowest):

1. CR Spec Env Vars (Highest): Defined directly in the OpenRAG Custom Resource spec.
2. Operator Environment (Medium): Set in the operator's own deployment using component-specific prefixes.
3. Hardcoded Defaults (Lowest): Built-in defaults within the operator code.

This hierarchy allows you to set organization-wide defaults via the operator deployment while still allowing individual OpenRAG instances to have unique configurations via their CR spec.

OpenRAG uses a lightweight, container-based architecture to orchestrate its components. The architecture consists of:

• OpenRAG backend: The central orchestration service that coordinates all other components.
• Langflow container: Runs a Langflow instance providing the visual editor for flow creation and connects to OpenSearch for data retrieval.
• Docling Serve: A local document processing service managed by the OpenRAG backend.
• OpenSearch container: Used for document and vector data storage.
• OpenRAG frontend: The user interface for interacting with the platform.
• External connectors: OAuth-authorized connectors that allow the backend to load documents from third-party cloud storage services into the OpenSearch knowledge base.

The OpenSearch Ingestion flow runs in the background when you upload documents locally or via cloud storage connectors. It is responsible for processing documents and storing them in your knowledge base.

By default, the flow uses Docling Serve to import and process documents. You can inspect and customize this flow in Langflow to change knowledge ingestion settings.

OpenRAG supports cloud storage connectors for AWS S3, Google Drive, Microsoft OneDrive, and Microsoft Sharepoint. To use these, you must register an OAuth application with your cloud provider to obtain a client ID and secret key, then add these credentials to your OpenRAG configuration.

Supported Services:

• AWS S3
• Google Drive
• Microsoft OneDrive
• Microsoft Sharepoint

Note on Google OAuth: Providing Google OAuth credentials also enables OAuth mode for OpenRAG and your OpenSearch knowledge base.

You can install OpenRAG and its dependencies (including Docker or Podman) using uvx. This method automatically manages the environment and dependencies.

1. Create and enter a workspace directory:

   mkdir openrag-workspace
   cd openrag-workspace

2. Run the installation command:

   uvx --python 3.13 openrag

3. Follow the terminal prompts:
   • Provide or autogenerate passwords for OpenSearch and Langflow Admin.
   • For most other configuration prompts, press N to use default values.
   • When asked Start services now?, press Y.
4. Once services are running, if the app doesn't open automatically, select Open OpenRAG in browser in the terminal.
5. During onboarding, select OpenAI as the model provider and enter your OpenAI API key.

When contributing documentation, follow these requirements:

1. File Location: Work with .mdx files in openrag/docs/docs. Navigation is managed in openrag/docs/sidebars.js.
2. Linking: Use slug for cross-referencing. For a page with slug: /cool-page, link using [Cool page](/cool-page).
3. Validation: Run npm run build locally to check for broken links before submitting.
4. PR Format:
   • Title: Use the format Docs: <summary of change> (e.g., Docs: fix broken link on contributing page).
   • Description: Explain why and how changes were made. Use Closes #NUMBER if the PR resolves an issue.
   • Labels: Add the documentation label to your PR.
5. AI Disclosure: If significant portions of the documentation were generated by AI, disclose this in the PR description.

Use Docker or Podman to manage self-hosted OpenRAG services when terminal interaction is unavailable or when you prefer not to use the OpenRAG TUI. This method deploys the Backend, Frontend, Langflow, OpenSearch, and OpenSearch Dashboards as containers. Note that docling serve must be run as a separate native service on the host machine and cannot run inside a container.

Prerequisites

Ensure you have the following installed and configured:

• Windows (if applicable)
• Python
• uv
• Docker or Podman
• Model providers (e.g., OpenAI, Anthropic, Ollama, or Watsonx)
• GPU (optional, for acceleration)