Install OpenRAG with TUI

Install OpenRAG and then run the OpenRAG Terminal User Interface(TUI) to start your OpenRAG deployment with a guided setup process.

The OpenRAG Terminal User Interface (TUI) allows you to set up, configure, and monitor your OpenRAG deployment directly from the terminal.

Instead of starting OpenRAG using Docker commands and manually editing values in the .env file, the TUI walks you through the setup. It prompts for variables where required, creates a .env file for you, and then starts OpenRAG.

Once OpenRAG is running, use the TUI to monitor your application, control your containers, and retrieve logs.

If you prefer running Podman or Docker containers and manually editing .env files, see Install OpenRAG Containers.

Prerequisites

• Install Python Version 3.10 to 3.13
• Install uv
• Install Podman (recommended) or Docker
• Install Docker Compose. 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: Install GPU support with an NVIDIA GPU, 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.

Install OpenRAG

Windows users

To use OpenRAG on Windows, use WSL (Windows Subsystem for Linux).

Choose an installation method based on your needs:

• For new users, the automatic installer script detects and installs prerequisites and then runs OpenRAG.
• For a quick test, use uvx to run OpenRAG without creating a project or modifying files.
• Use uv add to install OpenRAG as a managed dependency in a new or existing Python project.
• Use uv pip install to install OpenRAG into an existing virtual environment.

Automatic installer

The script detects and installs uv, Docker/Podman, and Docker Compose prerequisites, then runs OpenRAG with uvx.

1. Create a directory to store the OpenRAG configuration files:

   mkdir openrag-workspace
   cd openrag-workspace

2. Run the installer:

   curl -fsSL https://docs.openr.ag/files/run_openrag_with_prereqs.sh | bash

The TUI creates a .env file and docker-compose files in the current working directory.

Quick test with uvx

Use uvx to quickly run OpenRAG without creating a project or modifying any files.

1. Create a directory to store the OpenRAG configuration files:

   mkdir openrag-workspace
   cd openrag-workspace

2. Run OpenRAG:

   uvx openrag

   To run a specific version:

   uvx --from openrag==0.1.30 openrag

The TUI creates a .env file and docker-compose files in the current working directory.

Python project with uv add

Use uv add to install OpenRAG as a dependency in your Python project. This adds OpenRAG to your pyproject.toml and lockfile, making your installation reproducible and version-controlled.

1. Create a new project with a virtual environment:

   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.

2. Add OpenRAG to your project:

   uv add openrag

   To add a specific version:

   uv add openrag==0.1.30

3. Start the OpenRAG TUI:

   uv run openrag

Install a local wheel

If you downloaded the OpenRAG wheel to your local machine, install it by specifying its path:

1. Add the wheel to your project:

   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.

2. Run OpenRAG:

   uv run openrag

Existing virtual environment with uv pip install

Use uv pip install to install OpenRAG into an existing virtual environment that isn't managed by uv.

tip

For new projects, uv add is recommended as it manages dependencies in your project's lockfile.

1. Activate your virtual environment.

2. Install OpenRAG:

   uv pip install openrag

3. Run OpenRAG:

   openrag

Continue with Set up 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

Basic Setup can generate 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. For information about the difference between basic (no auth) and OAuth in OpenRAG, see Authentication and document access.

1. To install OpenRAG with Basic Setup, click Basic Setup or press 1.

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

   The OpenSearch password is required. The Langflow admin password is optional. If no Langflow admin password is generated, Langflow runs in autologin mode with no password required.

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

4. Click Save Configuration. Your passwords are saved in the .env file used to start OpenRAG.

5. To start OpenRAG, click Start All 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 start the Docling service, under Native Services, click Start.

7. To open the OpenRAG application, navigate to the TUI main menu, and then click Open App. Alternatively, in your browser, navigate to localhost:3000.

8. 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.

   The OpenSearch password is required. The Langflow admin password is optional. If no Langflow admin password is generated, Langflow runs in autologin mode with no password required.

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

4. Add your client and secret values for Google or Microsoft OAuth. These values can be found with your OAuth provider. For more information, see the Google OAuth client or Microsoft Graph OAuth client documentation.

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 All 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 start the Docling service, under Native Services, click Start.

9. To open the OpenRAG application, navigate to the TUI main menu, and then click Open App. Alternatively, in your browser, navigate to localhost:3000. You are presented with your provider's OAuth sign-in screen. After sign-in, you are redirected to the redirect URI.

   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. Supported webhook endpoints:

   • Google Drive: /connectors/google_drive/webhook
   • OneDrive: /connectors/onedrive/webhook
   • SharePoint: /connectors/sharepoint/webhook

10. Continue with Application Onboarding.

Application onboarding

The first time you start OpenRAG, whether using the TUI or a .env file, it's recommended that you complete application onboarding.

To skip onboarding, click Skip onboarding.

warning

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. To change your provider selection later, you must reinstall OpenRAG.

You must use the same provider for your language model and embedding model, unless you're using Ollama.

Choose one LLM provider and complete only those steps:

OpenAI

1. Enable Get API key from environment variable to automatically enter your key from the TUI-generated .env file. Alternatively, paste an OpenAI API key into the field.
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. To complete the onboarding tasks, click What is OpenRAG, and then click Add a Document.
6. Continue with the Quickstart.

IBM watsonx.ai

1. Complete the fields for watsonx.ai API Endpoint, IBM Project ID, and IBM API key. 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. To complete the onboarding tasks, click What is OpenRAG, and then click Add a Document.
6. 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. To complete the onboarding tasks, click What is OpenRAG, and then click Add a Document.
6. Continue with the Quickstart.

Close the OpenRAG TUI

To close the OpenRAG TUI, press q. The OpenRAG containers will continue to be served until the containers are stopped. For more information, see Manage OpenRAG containers with the TUI .

To start the TUI again, run uv run openrag.

Manage OpenRAG containers with the TUI

After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers.

Start all services

Click Start All Services to start the OpenRAG containers. The TUI automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for CUDA, NVIDIA_SMI, and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses. The TUI then pulls the images and deploys the containers with the following command.

docker compose up -d

If images are missing, the TUI runs docker compose pull, then runs docker compose up -d.

Status

The Status menu displays information on your container deployment. Here you can check container health, find your service ports, view logs, and upgrade your containers.

To view streaming logs, select the container you want to view, and press l. To copy your logs, click Copy to Clipboard.

To upgrade your containers, click Upgrade. Upgrade runs docker compose pull and then docker compose up -d --force-recreate. The first command pulls the latest images of OpenRAG. The second command recreates the containers with your data persisted.

To reset your containers, click Reset. Reset gives you a completely fresh start. Reset deletes all of your data, including OpenSearch data, uploaded documents, and authentication. Reset runs two commands. It first stops and removes all containers, volumes, and local images.

docker compose down --volumes --remove-orphans --rmi local

When the first command is complete, OpenRAG removes any additional Docker objects with prune.

docker system prune -f

Native services status

A native service in OpenRAG refers to a service run locally on your machine, and not within a container. The docling serve process is a native service in OpenRAG, because it's a document processing service that is run on your local machine, and controlled separately from the containers.

To start or stop docling serve or any other native services, in the TUI Status menu, click Stop or Restart.

To view the status, port, or PID of a native service, in the TUI main menu, click Status.

Diagnostics

The Diagnostics menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.

Reinstall OpenRAG

To reinstall OpenRAG with a completely fresh setup:

1. Reset your containers using the Reset button in the TUI status menu. This removes all containers, volumes, and data.

2. Optional: Delete your project's .env file. The Reset operation does not remove your project's .env file, so your passwords, API keys, and OAuth settings can be preserved. If you delete the .env file, run the Set up OpenRAG with the TUI process again to create a new configuration.

3. In the TUI Setup menu, follow these steps from Basic Setup:

   1. Click Start All Services to pull container images and start them.
   2. Under Native Services, click Start to start the Docling service.
   3. Click Open App to open the OpenRAG application.
   4. Continue with Application Onboarding.