446 lines
No EOL
20 KiB
Text
446 lines
No EOL
20 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';
|
|
import PartialWsl from '@site/docs/_partial-wsl-install.mdx';
|
|
|
|
[Install OpenRAG](#install) 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](/docker).
|
|
|
|
## Prerequisites
|
|
|
|
- All OpenRAG installations require [Python](https://www.python.org/downloads/release/python-3100/) version 3.10 to 3.13.
|
|
|
|
- If you aren't using the automatic installer script, install the following:
|
|
|
|
- [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
- [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/).
|
|
- [`podman-compose`](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or [Docker Compose](https://docs.docker.com/compose/install/). To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands.
|
|
|
|
- Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL).
|
|
|
|
<details>
|
|
<summary>Install WSL for OpenRAG</summary>
|
|
|
|
<PartialWsl />
|
|
|
|
</details>
|
|
|
|
- Prepare model providers and credentials.
|
|
|
|
During [Application Onboarding](#application-onboarding), you must select language model and embedding model providers.
|
|
If your chosen provider offers both types, you can use the same provider for both selections.
|
|
If your provider offers only one type, such as Anthropic, you must select two providers.
|
|
|
|
Gather the credentials and connection details for your chosen model providers before starting onboarding:
|
|
|
|
- OpenAI: Create an [OpenAI API key](https://platform.openai.com/api-keys).
|
|
- Anthropic language models: Create an [Anthropic API key](https://www.anthropic.com/docs/api/reference).
|
|
- IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment.
|
|
- Ollama: Use the [Ollama documentation](https://docs.ollama.com/) to set up your Ollama instance locally, in the cloud, or on a remote server, and then get your Ollama server's base URL.
|
|
|
|
- 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.
|
|
|
|
## Install OpenRAG {#install}
|
|
|
|
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.
|
|
|
|
<Tabs groupId="Installation method">
|
|
<TabItem value="installer" label="Automatic installer" default>
|
|
|
|
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:
|
|
```bash
|
|
mkdir openrag-workspace
|
|
cd openrag-workspace
|
|
```
|
|
|
|
2. Run the installer:
|
|
```bash
|
|
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.
|
|
|
|
</TabItem>
|
|
<TabItem value="uvx" label="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:
|
|
```bash
|
|
mkdir openrag-workspace
|
|
cd openrag-workspace
|
|
```
|
|
|
|
2. Run OpenRAG:
|
|
```bash
|
|
uvx openrag
|
|
```
|
|
|
|
To run a specific version:
|
|
```bash
|
|
uvx --from openrag==0.1.30 openrag
|
|
```
|
|
|
|
The TUI creates a `.env` file and docker-compose files in the current working directory.
|
|
|
|
</TabItem>
|
|
<TabItem value="uv-add" label="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:
|
|
```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.
|
|
|
|
2. Add OpenRAG to your project:
|
|
```bash
|
|
uv add openrag
|
|
```
|
|
|
|
To add a specific version:
|
|
```bash
|
|
uv add openrag==0.1.30
|
|
```
|
|
|
|
3. Start the OpenRAG TUI:
|
|
```bash
|
|
uv run openrag
|
|
```
|
|
|
|
<details closed>
|
|
<summary>Install a local wheel</summary>
|
|
|
|
If you downloaded the OpenRAG wheel to your local machine, install it by specifying its path:
|
|
|
|
1. Add the wheel to your project:
|
|
```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.
|
|
|
|
2. Run OpenRAG:
|
|
```bash
|
|
uv run openrag
|
|
```
|
|
</details>
|
|
|
|
</TabItem>
|
|
<TabItem value="uv-pip" label="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:
|
|
```bash
|
|
uv pip install openrag
|
|
```
|
|
|
|
3. Run OpenRAG:
|
|
```bash
|
|
uv run openrag
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
Continue with [Set up OpenRAG with the TUI](#setup).
|
|
|
|
If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
|
|
|
|
## Set up OpenRAG with the TUI {#setup}
|
|
|
|
The OpenRAG setup process creates a `.env` file at the root of your OpenRAG directory, and then starts OpenRAG.
|
|
If it detects a `.env` file in the OpenRAG root directory, it sources any variables from the `.env` file.
|
|
|
|
The TUI offers two setup methods to populate the required values. **Basic Setup** can generate all minimum required values for OpenRAG. However, **Basic Setup** doesn't enable [OAuth connectors for cloud storage](/knowledge#auth). If you want to use OAuth connectors to upload documents from cloud storage, select **Advanced Setup**.
|
|
If OpenRAG detects OAuth credentials, it recommends **Advanced Setup**.
|
|
|
|
<Tabs groupId="Setup method">
|
|
<TabItem value="Basic setup" label="Basic setup" default>
|
|
|
|
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. Optional: Paste your OpenAI API key in the OpenAI API key field. You can also provide this during onboarding or choose a different model provider.
|
|
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 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](#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. If you want to upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in a `.env` file in the OpenRAG installation directory.
|
|
|
|
* **Amazon**: Provide your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on [Configuring access to AWS applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html).
|
|
* **Google**: Provide your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). For more information, see the [Google OAuth client documentation](https://developers.google.com/identity/protocols/oauth2).
|
|
* **Microsoft**: For the Microsoft OAuth Client ID and Microsoft OAuth Client Secret, provide [Azure application registration credentials for SharePoint and OneDrive](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/app-registration?view=odsp-graph-online). For more information, see the [Microsoft Graph OAuth client documentation](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/graph-oauth).
|
|
|
|
You can [manage OAuth credentials](/ingestion#oauth-ingestion) later, but it is recommended to configure them during initial set up.
|
|
|
|
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 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`.
|
|
|
|
10. If you enabled OAuth connectors, you must sign in to your OAuth provider before being redirected to your OpenRAG instance.
|
|
|
|
11. Two additional variables are available for **Advanced Setup** at this point.
|
|
Only change these variables if you have a non-default network configuration for your deployment, such as using a reverse proxy or custom domain.
|
|
|
|
* `LANGFLOW_PUBLIC_URL`: Sets the base address to access the Langflow web interface. This is where users interact with flows in a browser.
|
|
|
|
* `WEBHOOK_BASE_URL`: Sets the base address of the OpenRAG OAuth connector endpoint.
|
|
Supported webhook endpoints:
|
|
|
|
- Amazon S3: Not applicable.
|
|
- Google Drive: `/connectors/google_drive/webhook`
|
|
- OneDrive: `/connectors/onedrive/webhook`
|
|
- SharePoint: `/connectors/sharepoint/webhook`
|
|
|
|
12. Continue with [Application Onboarding](#application-onboarding).
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
<PartialOnboarding />
|
|
|
|
## Exit the OpenRAG TUI
|
|
|
|
To exit the OpenRAG TUI, navigate to the main menu, and then press <kbd>q</kbd>.
|
|
The OpenRAG containers continue to run until they are stopped.
|
|
For more information, see [Manage OpenRAG containers with the TUI ](#tui-container-management).
|
|
|
|
To relaunch the TUI, run `uv run openrag`.
|
|
If you installed OpenRAG with `uvx`, run `uvx 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`.
|
|
For more information, see [Upgrade OpenRAG containers with the TUI](#upgrade-openrag-containers-with-the-tui).
|
|
|
|
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).
|
|
|
|
## Upgrade OpenRAG {#upgrade}
|
|
|
|
To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers using the OpenRAG TUI.
|
|
|
|
Upgrading the OpenRAG Python package updates the TUI and Python code, but container versions are controlled separately by environment variables in your `.env` file.
|
|
|
|
### Upgrade OpenRAG python package
|
|
|
|
Use the following steps to upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
|
|
After upgrading the Python package, you should also [upgrade your OpenRAG containers](#upgrade-openrag-containers-with-the-tui).
|
|
|
|
<Tabs groupId="Installation method">
|
|
<TabItem value="installer" label="Automatic installer / uvx" default>
|
|
|
|
If you installed OpenRAG using the [automatic installer](#install) or [uvx](#install), follow these steps to upgrade:
|
|
|
|
1. Navigate to your OpenRAG workspace directory:
|
|
```bash
|
|
cd openrag-workspace
|
|
```
|
|
|
|
2. Upgrade the OpenRAG package:
|
|
```bash
|
|
uvx --from openrag openrag
|
|
```
|
|
|
|
To upgrade to a specific version:
|
|
```bash
|
|
uvx --from openrag==0.1.33 openrag
|
|
```
|
|
|
|
3. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui).
|
|
|
|
</TabItem>
|
|
<TabItem value="uv-add" label="Python project with uv add">
|
|
|
|
1. Navigate to your project directory:
|
|
```bash
|
|
cd YOUR_PROJECT_NAME
|
|
```
|
|
|
|
2. Update OpenRAG to the latest version:
|
|
```bash
|
|
uv add --upgrade openrag
|
|
```
|
|
|
|
To upgrade to a specific version:
|
|
```bash
|
|
uv add --upgrade openrag==0.1.33
|
|
```
|
|
|
|
3. Start the OpenRAG TUI:
|
|
```bash
|
|
uv run openrag
|
|
```
|
|
|
|
4. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui).
|
|
|
|
</TabItem>
|
|
<TabItem value="uv-pip" label="Existing virtual environment with uv pip install">
|
|
|
|
1. Activate your virtual environment.
|
|
|
|
2. Upgrade OpenRAG:
|
|
```bash
|
|
uv pip install --upgrade openrag
|
|
```
|
|
|
|
To upgrade to a specific version:
|
|
```bash
|
|
uv pip install --upgrade openrag==0.1.33
|
|
```
|
|
|
|
3. Start the OpenRAG TUI:
|
|
```bash
|
|
uv run openrag
|
|
```
|
|
|
|
4. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui).
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Upgrade OpenRAG containers with the TUI {#upgrade-openrag-containers-with-the-tui}
|
|
|
|
After upgrading the OpenRAG Python package, upgrade your containers to ensure they match the `latest` version.
|
|
**Upgrade** runs `docker compose pull`, which pulls container images based on versions specified in your `.env` file.
|
|
`OPENRAG_VERSION` is set to `latest` by default, so it pulls the `latest` available container images.
|
|
|
|
1. In the OpenRAG TUI, click **Status**, and then click **Upgrade**.
|
|
2. When the upgrade completes, close the **Status** window and continue using OpenRAG.
|
|
|
|
If you encounter a `langflow container already exists` error during upgrade, see [Langflow container already exists during upgrade](/support/troubleshoot#langflow-container-already-exists-during-upgrade) in the troubleshooting guide.
|
|
|
|
To pin container versions to a specific release other than `latest`, set the `OPENRAG_VERSION` in your `.env` file:
|
|
```bash
|
|
OPENRAG_VERSION=0.1.33
|
|
```
|
|
|
|
For more information, see [System settings environment variables](/reference/configuration#system-settings).
|
|
|
|
## Diagnostics
|
|
|
|
The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.
|
|
|
|
## Reinstall OpenRAG {#reinstall}
|
|
|
|
To reinstall OpenRAG with a completely fresh setup:
|
|
|
|
1. Reset your containers using the **Reset** button in the [TUI status](#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](#setup) process again to create a new configuration.
|
|
|
|
3. In the TUI Setup menu, follow these steps from [Basic Setup](#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](#application-onboarding). |