🦫 OpenRag — Sovereign, Open Source RAG

OpenRag is a modular, production-grade Retrieval-Augmented Generation (RAG) framework. It runs entirely on your own infrastructure, with every parser, chunking strategy and retrieval method configurable — 100% open source, no black boxes, no lock-in.

Built by Linagora, OpenRag is a sovereign-by-design alternative to mainstream RAG stacks. It is the RAG engine behind Twake.ai.

• 🦫 OpenRag — Sovereign, Open Source RAG
• Table of Contents
• 🎯 Goals
• ✨ Key Features
• 🚧 Coming Soon
• 🚀 Installation
  • Prerequisites
  • Installation and Configuration
• 🔧 Troubleshooting
• 🤝 Support and Contributing
• 📜 License

• Run state-of-the-art RAG in production, on infrastructure you control
• Keep every component swappable — parsers, chunkers, retrievers, models
• Make answers verifiable, with citations back to the source document and page
• Build in the open, with the community

OpenRag supports a comprehensive range of file formats for seamless document ingestion:

• Text Files: txt, md
• Document Files: pdf, docx, doc, pptx - Advanced PDF parsing with OCR support and Office document processing
• E-mail: eml - Message body and headers, with attachments parsed through their own format's pipeline
• Audio Files: wav, mp3, flac, ogg, aac, wma - Audio transcription and content extraction
• Video Files: mp4, flv - Speech transcription from the audio track
• Images: png, jpeg, jpg, svg - Vision Language Model (VLM)-powered image captioning and analysis

All files are converted to Markdown format for consistent processing across document types. When image captioning is enabled, any image the parser can extract is replaced with an AI-generated description.

Manage OpenRAG through the bundled web interface.

Organize your knowledge base with flexible partition management:

• Multi-tenant support - isolate different document collections

Engage with your documents through our sophisticated chat interface:

OpenRag API is tailored to be compatible with the OpenAI format (see the openai-compatibility section for more details), enabling seamless integration of your deployed RAG into popular frontends and workflows such as OpenWebUI, LangChain, N8N, and more. This ensures flexibility and ease of adoption without requiring custom adapters.

Scale your RAG pipeline across multiple machines and GPUs.

OpenRag Leverages state-of-the-art retrieval techniques for superior accuracy.

• 📂 Expanded Format Support: Future updates will introduce compatibility with additional formats such as csv, odt, html, and other widely used open-source document types.
• 🔄 Unified Markdown Conversion: All files will continue to be converted to markdown using a consistent chunker. Format-specific chunkers (e.g., for CSV, HTML) are planned for enhanced processing.
• 🤖 Advanced Features: Upcoming releases will include Tool Calling, Agentic RAG, and MCP to elevate your RAG workflows.
• Enhanced Security: Ensures data encryption both during transit and at rest.

For comprehensive documentation and troubleshooting guidance, visit our documentation site.

• Python 3.12 or higher recommended
• Docker and Docker Compose
• For GPU capable machines, ensure you have the NVIDIA Container Toolkit installed. Refer to the NVIDIA documentation for installation instructions.

git clone --recurse-submodules git@github.com:linagora/openrag.git

cd openrag
git checkout main # or a given release

Create a .env file under infra/compose/, mirroring the structure of infra/compose/.env.example, to configure your environment and supply blank environment variables.

cp infra/compose/.env.example infra/compose/.env

All supported file format parsers are pre-configured. For PDF processing, PyMuPDFLoader is the default parser — a lightweight, fast, CPU-friendly engine well suited to searchable PDFs and quick local testing.

⚠️ Important: PyMuPDFLoader cannot process non-searchable (image-based / scanned) PDFs and does not run OCR or extract embedded images.

The full stack and its service configs live under infra/compose/. Place the .env you created there and run the commands from that directory (cd infra/compose):

# GPU deployment (recommended for optimal performance)
docker compose up -d
# docker compose down # to stop the application

# CPU deployment
docker compose --profile cpu up -d
# docker compose --profile cpu down # to stop the application

Once the app is up and running, visit http://localhost:APP_PORT or http:X.X.X.X:APP_PORT to access via:

1. /docs – FastAPI’s full API documentation. See this detailed overview of our api for more details on the endpoints.

2. /chainlit – Chainlit chat UI to chat with your partitions. To disable it (e.g., for backend-only use), set WITH_CHAINLIT_UI=False.

OpenRag supports two authentication modes:

• Token Mode (AUTH_MODE=token, default): Bearer token authentication via Authorization: Bearer <AUTH_TOKEN> header. Suitable for development and programmatic access.
• OIDC Mode (AUTH_MODE=oidc): OpenID Connect flow with an external identity provider (Keycloak, LemonLDAP::NG, etc.). Users authenticate via browser redirect to the IdP.

To enable OIDC, set AUTH_MODE=oidc and configure the required OIDC variables (see infra/compose/.env.example for the full list).

For comprehensive OIDC setup and configuration, see the OIDC Authentication Guide (or the SSO Quick Start for a faster path).

3. http://localhost:ADMIN_UI_PORT/app/ (default 8081) to access the admin UI for easy document ingestion, indexing, and management

To scale OpenRag in a distributed environment using Ray, follow the dedicated guide: ➡ Deploy OpenRag in a Ray cluster

To run all unit tests:

uv run pytest

For comprehensive documentation and troubleshooting guidance, visit our documentation site.

To run the documentation site locally for development:

npm i     # Install dependencies
npm run dev   # Start the development server

And then go to http://localhost:4321/openrag

error: Distribution `ray==2.43.0 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform

hint: You're using CPython 3.13 (`cp313`), but `ray` (v2.43.0) only has wheels with the following Python ABI tag: `cp312`

uv venv --python=3.12
uv sync

sudo mkdir /app/model_weights
sudo chmod 775 /app/model_weights

We ❤️ your contributions!

We encourage you to contribute to OpenRag! Here's how you can get involved:

1. Fork this repository.
2. Create a new branch for your feature or fix.
3. Submit a pull request for review.

Feel free to ask questions, suggest features, or report bugs via the GitHub Issues page. Your feedback helps us improve!

OpenRag is licensed under the AGPL-3.0. You are free to use, modify, and distribute this software in compliance with the terms of the license.

For more details, refer to the LICENSE file in the repository.