Install OpenRAG

Install the OpenRAG Python wheel, and then run the OpenRAG Terminal User Interface(TUI) 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.

Prerequisites

• Python Version 3.10 to 3.13
• uv
• Podman (recommended) or Docker installed
• Docker Compose installed. If using Podman, use podman-compose or alias Docker compose commands to Podman commands.
• Create an OpenAI API key. This key is required to start OpenRAG, but you can choose a different model provider during Application Onboarding.
• Optional: GPU support requires an NVIDIA GPU with CUDA support and compatible NVIDIA drivers installed on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment.

Install the OpenRAG Python wheel

important

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 configuring and running OpenRAG.

1. Create a new project with a virtual environment using uv init.

   uv init YOUR_PROJECT_NAME
   cd YOUR_PROJECT_NAME

   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.

2. Add the local OpenRAG wheel to your project's virtual environment.

   uv add PATH/TO/openrag-VERSION-py3-none-any.whl

   Replace PATH/TO/ and VERSION with the path and version of your downloaded OpenRAG .whl file.

   For example, if your .whl file is in the ~/Downloads directory, the command is uv add ~/Downloads/openrag-0.1.8-py3-none-any.whl.

3. Ensure all dependencies are installed and updated in your virtual environment.

   uv sync

4. Start the OpenRAG TUI.

   uv run openrag

5. Continue with Setup OpenRAG with the TUI.

Set up OpenRAG with the TUI

The TUI creates a .env file in your OpenRAG directory root and starts OpenRAG. If the TUI detects a .env file in the OpenRAG root directory, it sources any variables from the .env file. If the TUI detects OAuth credentials, it enforces the Advanced Setup path.

Basic Setup generates all of the required values for OpenRAG except the OpenAI API key. Basic Setup does not set up OAuth connections for ingestion from cloud providers. For OAuth setup, use Advanced Setup.

Basic Setup and Advanced Setup enforce the same authentication settings for the Langflow server, but manage document access differently. For more information, see Authentication and document access.

Basic setup

1. To install OpenRAG with Basic Setup, click Basic Setup or press 1.
2. Click Generate Passwords to generate passwords for OpenSearch and Langflow.
3. Paste your OpenAI API key in the OpenAI API key field.
4. Click Save Configuration.
5. To start OpenRAG, click Start Container Services. Startup pulls container images and runs them, so it can take some time. When startup is complete, the TUI displays the following:

   Services started successfully
   Command completed successfully

6. To open the OpenRAG application, click Open App.
7. Continue with Application Onboarding.

Advanced setup

1. To install OpenRAG with Advanced Setup, click Advanced Setup or press 2.

2. Click Generate Passwords to generate passwords for OpenSearch and Langflow.

3. Paste your OpenAI API key in the OpenAI API key field.

4. Add your client and secret values for Google, Azure, or AWS OAuth. These values can be found in your OAuth provider.

5. The OpenRAG TUI presents redirect URIs for your OAuth app. These are the URLs your OAuth provider will redirect back to after user sign-in. Register these redirect values with your OAuth provider as they are presented in the TUI.

6. Click Save Configuration.

7. To start OpenRAG, click Start Container Services. Startup pulls container images and runs them, so it can take some time. When startup is complete, the TUI displays the following:

   Services started successfully
   Command completed successfully

8. To open the OpenRAG application, click Open App, press 6, or navigate to http://localhost:3000. You will be presented with your provider's OAuth sign-in screen, and be redirected to the redirect URI after sign-in. Continue with Application Onboarding.

   Two additional variables are available for Advanced Setup:

   The LANGFLOW_PUBLIC_URL controls where the Langflow web interface can be accessed. This is where users interact with their flows in a browser.

   The WEBHOOK_BASE_URL controls where the endpoint for /connectors/CONNECTOR_TYPE/webhook will be available. This connection enables real-time document synchronization with external services. For example, for Google Drive file synchronization the webhook URL is /connectors/google_drive/webhook.

9. Continue with Application Onboarding.

Application onboarding

The first time you start OpenRAG, whether using the TUI or a .env file, you must complete application onboarding.

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.

OpenAI

1. Enable Get API key from environment variable to automatically enter your key from the TUI-generated .env file.
2. Under Advanced settings, select your Embedding Model and Language Model.
3. To load 2 sample PDFs, enable Sample dataset. This is recommended, but not required.
4. Click Complete.
5. Continue with the Quickstart.

IBM watsonx.ai

1. Complete the fields for watsonx.ai API Endpoint, IBM API key, and IBM Project ID. These values are found in your IBM watsonx deployment.
2. Under Advanced settings, select your Embedding Model and Language Model.
3. To load 2 sample PDFs, enable Sample dataset. This is recommended, but not required.
4. Click Complete.
5. Continue with the Quickstart.

Ollama

tip

Ollama is not included with OpenRAG. To install Ollama, see the Ollama documentation.

1. Enter your Ollama server's base URL address. The default Ollama server address is http://localhost:11434. 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 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.
5. Continue with the Quickstart.