232 lines
No EOL
11 KiB
Text
232 lines
No EOL
11 KiB
Text
---
|
|
title: Install OpenRAG with TUI
|
|
slug: /install
|
|
---
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
|
|
|
|
[Install the OpenRAG Python wheel](#install-python-wheel), and then run the [OpenRAG Terminal User Interface(TUI)](#setup) 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](/get-started/docker).
|
|
|
|
## Prerequisites
|
|
|
|
- Install [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/)
|
|
- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
|
|
- Install [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/)
|
|
- Install [Docker Compose](https://docs.docker.com/compose/install/). If using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands.
|
|
- Create an [OpenAI API key](https://platform.openai.com/api-keys). This key is **required** to start OpenRAG, but you can choose a different model provider during [Application Onboarding](#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.
|
|
|
|
:::note Windows users
|
|
The OpenRAG TUI has limited compatibility with PowerShell. To use the TUI, use [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install). Alternatively, skip the TUI and follow the [OpenRAG container installation](/get-started/docker) steps instead.
|
|
:::
|
|
|
|
## Install the OpenRAG Python wheel {#install-python-wheel}
|
|
|
|
The OpenRAG wheel installs the Terminal User Interface (TUI) for configuring and running OpenRAG.
|
|
|
|
To quickly install and start OpenRAG, run `uvx openrag`.
|
|
|
|
To first set up a project and then install OpenRAG, do the following:
|
|
|
|
1. Create a new project with a virtual environment using `uv init`.
|
|
|
|
```bash
|
|
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](https://docs.astral.sh/uv/pip/environments).
|
|
|
|
2. Ensure all dependencies are installed and updated in your virtual environment.
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
3. Install and start the OpenRAG TUI.
|
|
```bash
|
|
uvx openrag
|
|
```
|
|
|
|
To install a specific version of the Langflow package, add the required version to the command, such as `uvx --from openrag==0.1.25 openrag`.
|
|
|
|
<details closed>
|
|
<summary>Install a local wheel without uvx</summary>
|
|
|
|
If you downloaded the OpenRAG wheel to your local machine, follow these steps:
|
|
|
|
1. Add the wheel to your project's virtual environment.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
uv add ~/Downloads/openrag-0.1.8-py3-none-any.whl
|
|
```
|
|
|
|
2. Run OpenRAG.
|
|
|
|
```bash
|
|
uv run openrag
|
|
```
|
|
|
|
</details>
|
|
4. Continue with [Set up OpenRAG with the TUI](#setup).
|
|
|
|
## Set up OpenRAG with the TUI {#setup}
|
|
|
|
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.
|
|
|
|
<Tabs groupId="Setup method">
|
|
<TabItem value="Basic setup" label="Basic setup" default>
|
|
|
|
**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**.
|
|
For information about the difference between basic (no auth) and OAuth in OpenRAG, see [Authentication and document access](/knowledge#auth).
|
|
|
|
1. To install OpenRAG with **Basic Setup**, click **Basic Setup** or press <kbd>1</kbd>.
|
|
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](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) 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:
|
|
```bash
|
|
Services started successfully
|
|
Command completed successfully
|
|
```
|
|
6. To open the OpenRAG application, click **Open App**.
|
|
7. Continue with [Application Onboarding](#application-onboarding).
|
|
</TabItem>
|
|
<TabItem value="Advanced setup" label="Advanced setup">
|
|
|
|
1. To install OpenRAG with **Advanced Setup**, click **Advanced Setup** or press <kbd>2</kbd>.
|
|
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](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) 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](https://developers.google.com/identity/protocols/oauth2) or [Microsoft Graph OAuth client](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/graph-oauth) 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:
|
|
```bash
|
|
Services started successfully
|
|
Command completed successfully
|
|
```
|
|
8. To open the OpenRAG application, click **Open App**.
|
|
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`
|
|
|
|
9. Continue with [Application Onboarding](#application-onboarding).
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
<PartialOnboarding />
|
|
|
|
## Close the OpenRAG TUI
|
|
|
|
To close the OpenRAG TUI, press <kbd>q</kbd>.
|
|
The OpenRAG containers will continue to be served until the containers are stopped.
|
|
For more information, see [Manage OpenRAG containers with the TUI ](#tui-container-management).
|
|
|
|
To start the TUI again, run `uv run openrag`.
|
|
|
|
## Manage OpenRAG containers with the TUI {#tui-container-management}
|
|
|
|
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.
|
|
```bash
|
|
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 <kbd>l</kbd>.
|
|
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](#status).
|
|
|
|
## Diagnostics
|
|
|
|
The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. |