gmakstutis/openrag
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

start breaking up content into the new pages

Browse source
This commit is contained in:
April M 2025-12-03 20:24:48 -08:00
parent 20e67d0ce5
commit 9f085a8637
18 changed files with 406 additions and 172 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/docs/get-started/docker.mdx
View file

@ -1,5 +1,5 @@
--- ---
title: Install OpenRAG containers title: Deploy OpenRAG with self-managed containers
slug: /docker slug: /docker
--- ---
@ -8,6 +8,9 @@ import TabItem from '@theme/TabItem';
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
import PartialWsl from '@site/docs/_partial-wsl-install.mdx'; import PartialWsl from '@site/docs/_partial-wsl-install.mdx';
You can use Docker or Podman to deploy self-managed OpenRAG containers.
Use this option if you don't want to use the TUI for container management, or you need to run OpenRAG in an environment where using the TUI is unfeasible.
OpenRAG has two Docker Compose files. Both files deploy the same applications and containers locally, but they are for different environments: OpenRAG has two Docker Compose files. Both files deploy the same applications and containers locally, but they are for different environments:
- [`docker-compose.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose.yml) is an OpenRAG deployment with GPU support for accelerated AI processing. This Docker Compose file requires an NVIDIA GPU with [CUDA](https://docs.nvidia.com/cuda/) support. - [`docker-compose.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose.yml) is an OpenRAG deployment with GPU support for accelerated AI processing. This Docker Compose file requires an NVIDIA GPU with [CUDA](https://docs.nvidia.com/cuda/) support.
@ -172,9 +175,10 @@ uv run python scripts/docling_ctl.py stop
## Container management commands ## Container management commands
Manage your OpenRAG containers with the following commands. Manage your OpenRAG containers with the following commands.
These commands are also available in the TUI's [Status menu](/install#status).
### Upgrade containers {#upgrade-containers} ### Upgrade containers
<!-- also on /upgrade -->
Upgrade your containers to the latest version while preserving your data. Upgrade your containers to the latest version while preserving your data.
@ -185,6 +189,8 @@ docker compose up -d --force-recreate
### Reset containers (destructive) {#reset-containers} ### Reset containers (destructive) {#reset-containers}
<!-- part of this needs to be on /reinstall and /uninstall -->
:::warning :::warning
These are destructive operations that reset your OpenRAG deployment to an initial state. These are destructive operations that reset your OpenRAG deployment to an initial state.
Be aware that data is lost and cannot be recovered after running these commands. Be aware that data is lost and cannot be recovered after running these commands.

30
docs/docs/get-started/install-options.mdx
View file

@ -0,0 +1,30 @@
---
title: Choose an installation method
slug: /install-options
---
The [OpenRAG architecture](/#openrag-architecture) is lightweight and container-based with a central OpenRAG backend that orchestrates the various services and external connectors.
Depending on your use case, OpenRAG can assist with container management, or you can manage the containers yourself.
Choose the installation method that best fits your needs:
* **Use the [Terminal User Interface (TUI)](/tui) to manage containers**: For guided configuration and simplified container management, install OpenRAG with TUI-managed containers.
* [**Automatic installer script**](/install): Run one script to install the required dependencies and install OpenRAG with `uvx`.
* [**`uv`**](/install-uv): Install OpenRAG as a dependency of a new or existing Python project.
* [**`uvx`**](/install-uvx): Invoke OpenRAG without permanently installing it in a Python project.
* [**Install OpenRAG on Microsoft Windows**](/install-wsl): On Windows machines, you must install OpenRAG within the Windows Subsystem for Linux (WSL).
OpenRAG doesn't support nested virtualization; don't run OpenRAG on a WSL distribution that is inside a Windows VM.
* [**Manage your own containers**](/docker): You can use Docker or Podman to deploy self-managed OpenRAG containers.
The first time you start OpenRAG, you must complete application onboarding.
This is required for all installation methods because it prepares the minimum required configuration for OpenRAG to run.
For more information, see the instructions for your chosen installation method.
Your OpenRAG configuration is stored in a `.env` file in the OpenRAG installation directory.
When using TUI-managed containers, the TUI prompts you for any missing values during setup and onboarding, and any values detected in a preexisting `.env` file are automatically populated.
When using self-managed containers, you must predefine these values in a `.env` file, as you would for any container deployment.
For more information, see the instructions for your chosen installation method and [Environment variables](/reference/configuration).

0
docs/docs/get-started/install-uv-add.mdx
View file

0
docs/docs/get-started/install-uv-pip.mdx
View file

26
docs/docs/get-started/install-uv.mdx Normal file
View file

@ -0,0 +1,26 @@
---
title: Install OpenRAG in a Python project with uv
slug: /install-uv
---
For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
You can use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) to install OpenRAG as a managed or unmanaged dependency in a new or existing Python project.
For other installation methods, see [Choose an installation method](/install-options).
* **`uv pip install`**: Install OpenRAG as an unmanaged dependency in a virtual environment.
* **`uv add`** (Recommended): Install OpenRAG as a managed dependency in a new or existing Python project.
## Next steps
* [Manage OpenRAG containers](/manage-containers)
* [Chat](/chat)
* [Upload documents](/ingestion)

27
docs/docs/get-started/install-uvx.mdx
View file

@ -0,0 +1,27 @@
---
title: Invoke OpenRAG with uvx
slug: /install-uvx
---
For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
You can use [`uvx`](https://docs.astral.sh/uvx/getting-started/installation/) to invoke OpenRAG without permanently installing it in a Python project.
`uvx` installs OpenRAG in an ephemeral, isolated virtual environment.
This method is best when you want to test OpenRAG outside of a Python project or you don't need to preserve the OpenRAG installation.
Depending on your project structure, `uvx` might not be suitable for production deployments.
:::tip
The [automatic installer script](/install) also uses `uvx` to install OpenRAG.
:::
For other installation methods, see [Choose an installation method](/install-options).
## Next steps
* [Manage OpenRAG containers](/manage-containers)
* [Chat](/chat)
* [Upload documents](/ingestion)

18
docs/docs/get-started/install-windows.mdx
View file

@ -0,0 +1,18 @@
---
title: Install OpenRAG on Microsoft Windows
slug: /install-windows
---
If you're using Windows, you must install OpenRAG within the Windows Subsystem for Linux (WSL).
For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
For self-managed containers, deploy OpenRAG with Docker or Podman inside your WSL distribution.
## Next steps
* [Manage OpenRAG containers](/manage-containers)
* [Chat](/chat)
* [Upload documents](/ingestion)

160
docs/docs/get-started/install.mdx
View file

@ -1,5 +1,5 @@
--- ---
title: Install OpenRAG with TUI title: Install OpenRAG with the automatic installer script
slug: /install slug: /install
--- ---
@ -8,17 +8,16 @@ import TabItem from '@theme/TabItem';
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
import PartialWsl from '@site/docs/_partial-wsl-install.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. :::tip
For a fully guided installation and preview of OpenRAG's core features, try the [quickstart](/quickstart).
:::
The OpenRAG Terminal User Interface (TUI) allows you to set up, configure, and monitor your OpenRAG deployment directly from the terminal. For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg) The installer script detects and installs any missing dependencies, and then installs OpenRAG with [`uvx`](https://docs.astral.sh/uvx/getting-started/installation/).
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. Because `uvx` installs OpenRAG in an ephemeral, isolated virtual environment, this installation method isn't suitable for all use cases.
For other installation methods, see [Choose an installation method](/install-options).
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 ## Prerequisites
@ -174,7 +173,9 @@ Choose an installation method based on your needs:
</TabItem> </TabItem>
</Tabs> </Tabs>
Continue with [Set up OpenRAG with the TUI](#setup). When the Terminal User Interface (TUI) starts, continue to [Set up OpenRAG with the TUI](#setup).
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)
If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot). If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
@ -263,15 +264,6 @@ If OpenRAG detects OAuth credentials, it recommends **Advanced Setup**.
<PartialOnboarding /> <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} ## Manage OpenRAG containers with the TUI {#tui-container-management}
After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers. After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers.
@ -288,7 +280,7 @@ Here you can check container health, find your service ports, view logs, and upg
* **Logs**: To view streaming logs, select the container you want to view, and press <kbd>l</kbd>. * **Logs**: To view streaming logs, select the container you want to view, and press <kbd>l</kbd>.
To copy the logs, click **Copy to Clipboard**. To copy the logs, click **Copy to Clipboard**.
* **Upgrade**: Check for updates. For more information, see [upgrade OpenRAG](#upgrade). * **Upgrade**: Check for updates. For more information, see [upgrade OpenRAG](/upgrade).
* **Factory Reset**: This is a destructive action that [resets your containers](#reset-containers). * **Factory Reset**: This is a destructive action that [resets your containers](#reset-containers).
@ -318,7 +310,7 @@ This operation _doesn't_ remove the `.env` file or the contents of the `./openra
docker system prune -f docker system prune -f
``` ```
2. If you reset your containers as part of reinstalling OpenRAG, continue the [reinstallation process](#reinstall) after resetting the containers. 2. If you reset your containers as part of reinstalling OpenRAG, continue the [reinstallation process](/reinstall) after resetting the containers.
Otherwise, in the TUI **Setup** menu, repeat the [setup process](#setup) to start the services and launch the OpenRAG app. Your OpenRAG passwords, OAuth credentials (if previously set), and onboarding configuration are restored from the `.env` file. Otherwise, in the TUI **Setup** menu, repeat the [setup process](#setup) to start the services and launch the OpenRAG app. Your OpenRAG passwords, OAuth credentials (if previously set), and onboarding configuration are restored from the `.env` file.
### Start all services {#start-all-services} ### Start all services {#start-all-services}
@ -344,126 +336,8 @@ A _native service_ in OpenRAG is a service that runs locally on your machine, no
From the **Status** menu, you can view the status, port, and process ID (PID) of the OpenRAG native services. From the **Status** menu, you can view the status, port, and process ID (PID) of the OpenRAG native services.
You can also click **Stop** or **Restart** to stop and start OpenRAG native services. You can also click **Stop** or **Restart** to stop and start OpenRAG native services.
## Upgrade OpenRAG {#upgrade} ## Next steps
To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers. * [Manage OpenRAG containers](/manage-containers)
* [Chat](/chat)
This is a two part process because upgrading the OpenRAG Python package updates the TUI and Python code, but the container versions are controlled by environment variables in your `.env` file. * [Upload documents](/ingestion)
1. Stop your OpenRAG containers: In the OpenRAG TUI, go to the **Status** menu, and then click **Stop Services**.
2. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
<Tabs groupId="Installation method">
<TabItem value="installer" label="Automatic installer or uvx" default>
Use these steps to upgrade the Python package if you installed OpenRAG using the automatic installer or `uvx`:
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
```
</TabItem>
<TabItem value="uv-add" label="Python project (uv add)">
Use these steps to upgrade the Python package if you installed OpenRAG in a 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
```
</TabItem>
<TabItem value="uv-pip" label="Virtual environment (uv pip install)">
Use these steps to upgrade the Python package if you installed OpenRAG in a venv 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
```
</TabItem>
</Tabs>
3. Start the upgraded OpenRAG containers: In the OpenRAG TUI, click **Start All Services**, and then wait while the containers start.
After upgrading the Python package, OpenRAG runs `docker compose pull` to get the appropriate container images matching the version specified in your OpenRAG `.env` file. Then, it recreates the containers with the new images using `docker compose up -d --force-recreate`.
In the `.env` file, the `OPENRAG_VERSION` [environment variable](/reference/configuration#system-settings) is set to `latest` by default, which it pulls the `latest` available container images.
To pin a specific container image version, you can set `OPENRAG_VERSION` to the desired container image version, such as `OPENRAG_VERSION=0.1.33`.
However, when you upgrade the Python package, OpenRAG automatically attempts to keep the `OPENRAG_VERSION` synchronized with the Python package version.
You might need to edit the `.env` file after upgrading the Python package to enforce a different container version.
The TUI warns you if it detects a version mismatch.
If you get an error that `langflow container already exists` error during upgrade, see [Langflow container already exists during upgrade](/support/troubleshoot#langflow-container-already-exists-during-upgrade).
4. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
## Reinstall OpenRAG {#reinstall}
Reset your OpenRAG deployment by recreating the containers and, optionally, removing related data:
1. In the TUI, [reset your containers](#reset-containers) to destroy the following:
* All existing OpenRAG containers, volumes, and local images
* Any additional Docker objects
* The contents of OpenRAG's `config` and `./opensearch-data` directories
* The `conversations.json` file
2. Optional: Remove data that wasn't deleted by the **Factory Reset** operation. For a completely fresh installation, delete all of this data.
* **OpenRAG's `.env` file**: Contains your OpenRAG configuration, including OpenRAG passwords, API keys, OAuth settings, and other [environment variables](/reference/configuration). If you delete this file, you must either repeat the [setup process](#setup) to create a new `.env` file, or add a populated `.env` file to your OpenRAG installation directory before restarting OpenRAG.
* **The contents of the `./openrag-documents` directory**: Contains documents that you uploaded to OpenRAG. Delete these files to prevent documents from being reingested to your knowledge base after restarting OpenRAG. However, you might want to preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
3. In the TUI **Setup** menu, repeat the [setup process](#setup) to configure OpenRAG, restart the services, and launch the OpenRAG app, and repeat [application onboarding](#application-onboarding).
If OpenRAG detects a `.env` file, it automatically populates any OpenRAG passwords, OAuth credentials, and onboarding configuration set in that file.

32
docs/docs/get-started/manage-containers.mdx
View file

@ -0,0 +1,32 @@
---
title: Manage OpenRAG containers
slug: /manage-containers
---
Container management is an essential part of maintaining your OpenRAG deployment.
## Manage containers with the TUI
If you [installed OpenRAG](/install-options) with the automated installer script, `uv`, or `uvx`, you can use the [Terminal User Interface (TUI)](/tui) to manage your containers:
* Start and stop OpenRAG containers.
* Start and stop OpenRAG's native services (Docling).
* View the status of your OpenRAG services.
* Access container logs for troubleshooting.
* Upgrade your OpenRAG containers to the latest version.
* Reset your OpenRAG containers to an initial state (destructive).
## Manage containers with Docker or Podman
If you [deployed OpenRAG with self-managed containers](/docker), run Docker or Podman commands to manage your OpenRAG containers.
* Start containers
* Stop containers
* View container status
* Access container logs for troubleshooting
* Upgrade your OpenRAG containers to the latest version
* Reset your OpenRAG containers to an initial state (destructive)
## See also
* [Uninstall OpenRAG](/uninstall)

21
docs/docs/get-started/quickstart.mdx
View file

@ -30,10 +30,11 @@ For other providers, see the complete [installation guide](/install).
</details> </details>
## Install OpenRAG ## Install OpenRAG
For this quickstart, install OpenRAG with the automatic installer script and basic setup: For this quickstart, install OpenRAG with the automatic installer script and basic setup.
This script installs OpenRAG dependencies, including Docker or Podman, installs OpenRAG with [`uvx`](https://docs.astral.sh/uvx/getting-started/installation/), and creates a `.env` file and `docker-compose` files in the current working directory.
1. Create a directory to store the OpenRAG configuration files, and then change to that directory: 1. Create a directory to store the OpenRAG configuration files, and then change to that directory:
@ -48,10 +49,13 @@ For this quickstart, install OpenRAG with the automatic installer script and bas
bash run_openrag_with_prereqs.sh bash run_openrag_with_prereqs.sh
``` ```
This script installs OpenRAG and its dependencies, including Docker or Podman, and it creates a `.env` file and `docker-compose` files in the current working directory. Wait while the installer script prepares your environment and installs OpenRAG.
You might be prompted to install certain dependencies if they aren't already present in your environment. You might be prompted to install certain dependencies if they aren't already present in your environment.
This process can take a few minutes.
Once the environment is ready, OpenRAG starts. The entire process can take a few minutes.
Once the environment is ready, the OpenRAG Terminal User Interface (TUI) starts.
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)
3. Click **Basic Setup**. 3. Click **Basic Setup**.
@ -66,7 +70,7 @@ For this quickstart, install OpenRAG with the automatic installer script and bas
5. Click **Save Configuration**, and then click **Start All Services**. 5. Click **Save Configuration**, and then click **Start All Services**.
Wait a few minutes while the startup process pulls and runs the necessary container images. Wait a few minutes while the startup process pulls and runs the necessary container images.
Proceed when you see the following messages in the terminal user interface (TUI): Proceed when you see the following messages in the TUI:
```bash ```bash
Services started successfully Services started successfully
@ -158,9 +162,8 @@ You can send and receive requests with the Langflow API using Python, TypeScript
## Next steps ## Next steps
* **Reinstall OpenRAG with your preferred settings**: This quickstart used a minimal setup to demonstrate OpenRAG's core functionality. * **Reinstall OpenRAG with your preferred settings**: This quickstart used `uvx` and a minimal setup to demonstrate OpenRAG's core functionality.
It is recommended that you [reinstall OpenRAG](/install#reinstall) with your preferred configuration because some settings are immutable after initial setup. It is recommended that you [reinstall OpenRAG](/reinstall) with your preferred configuration and [installation method](/install-options).
For all installation options, see [Install OpenRAG with TUI](/install) and [Install OpenRAG with containers](/docker).
* **Learn more about OpenRAG**: Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality. * **Learn more about OpenRAG**: Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality.

28
docs/docs/get-started/reinstall.mdx Normal file
View file

@ -0,0 +1,28 @@
---
title: Reinstall OpenRAG
slug: /reinstall
---
You can reset your OpenRAG deployment to its initial state by recreating the containers and deleting accessory data like the `.env` file and ingested documents.
## Reinstall TUI-managed containers
1. In the TUI, [reset your containers](/manage-containers#reset-containers) to destroy the following:
* All existing OpenRAG containers, volumes, and local images
* Any additional Docker objects
* The contents of OpenRAG's `config` and `./opensearch-data` directories
* The `conversations.json` file
2. Optional: Remove data that wasn't deleted by the **Factory Reset** operation.
For a completely fresh installation, delete all of this data.
* **OpenRAG's `.env` file**: Contains your OpenRAG configuration, including OpenRAG passwords, API keys, OAuth settings, and other [environment variables](/reference/configuration). If you delete this file, you must either repeat the [setup process](#setup) to create a new `.env` file, or add a populated `.env` file to your OpenRAG installation directory before restarting OpenRAG.
* **The contents of the `./openrag-documents` directory**: Contains documents that you uploaded to OpenRAG. Delete these files to prevent documents from being reingested to your knowledge base after restarting OpenRAG. However, you might want to preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
3. In the TUI **Setup** menu, repeat the [setup process](#setup) to configure OpenRAG, restart the services, and launch the OpenRAG app, and repeat [application onboarding](#application-onboarding).
If OpenRAG detects a `.env` file, it automatically populates any OpenRAG passwords, OAuth credentials, and onboarding configuration set in that file.
## Reinstall self-managed containers
If you manage your own OpenRAG containers with Docker or Podman, follow these steps to reinstall OpenRAG:

0
docs/docs/get-started/reset-reinstall.mdx
View file

31
docs/docs/get-started/tui.mdx
View file

@ -0,0 +1,31 @@
---
title: Use the TUI
slug: /tui
---
The OpenRAG Terminal User Interface (TUI) provides a simplified and guided experience for configuring, managing, and monitoring your OpenRAG deployment directly from the terminal.
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)
The TUI is used when you install OpenRAG with the [automatic installer script](/install), [`uv`](/install-uv), or [`uvx`](/install-uvx).
It guides you through the initial setup, creates your `.env` file automatically, and provides convenient access to [container management](/manage-containers) controls.
In contrast, when you [deploy OpenRAG with self-managed containers](/docker), you must manually configure OpenRAG by preparing a `.env` file and using Docker or Podman commands to deploy and manage your containers.
## Access the TUI {#access-the-tui}
If you installed OpenRAG with `uv`, access the TUI with `uv run openrag`.
If you installed OpenRAG with the automatic installer script or `uvx`, access the TUI with `uvx openrag`.
## Exit the OpenRAG TUI
To exit the OpenRAG TUI, go to the TUI main menu, and then press <kbd>q</kbd>.
Your OpenRAG containers continue to run until they are stopped.
To restart the TUI, see [Access the TUI](#access-the-tui).
## See also
* [Manage containers](/manage-containers)

14
docs/docs/get-started/uninstall.mdx
View file

@ -0,0 +1,14 @@
---
title: Remove OpenRAG
slug: /uninstall
---
:::tip
If you want to reset your OpenRAG containers without removing OpenRAG entirely, see [Reset OpenRAG containers](/manage-containers#reset-containers) and [Reinstall OpenRAG](/reinstall).
:::
If you used the [automated installer script](/install) or [`uvx`](/install-uvx) to install OpenRAG, run `uv cache clean openrag` to remove the cached OpenRAG environment.
If you used [`uv`](/install-uv) to install OpenRAG, run `uv remove openrag` in your Python project.
For self-managed containers, destroy the containers, prune any additional Docker objects, and delete any remaining OpenRAG files, as explained in [Reset OpenRAG containers](/manage-containers#reset-containers).

134
docs/docs/get-started/upgrade.mdx
View file

@ -0,0 +1,134 @@
---
title: Upgrade OpenRAG
slug: /upgrade
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Use these steps to upgrade your OpenRAG deployment to the latest version or a specific version.
## Upgrade TUI-managed containers
To upgrade OpenRAG, you need to upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers.
This is a two part process because upgrading the OpenRAG Python package updates the TUI and Python code, but the container versions are controlled by environment variables in your `.env` file.
1. Stop your OpenRAG containers: In the OpenRAG TUI, go to the **Status** menu, and then click **Stop Services**.
2. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
<Tabs groupId="Installation method">
<TabItem value="installer" label="Automatic installer or uvx" default>
Use these steps to upgrade the Python package if you installed OpenRAG using the automatic installer or `uvx`:
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
```
</TabItem>
<TabItem value="uv-add" label="Python project (uv add)">
Use these steps to upgrade the Python package if you installed OpenRAG in a 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
```
</TabItem>
<TabItem value="uv-pip" label="Virtual environment (uv pip install)">
Use these steps to upgrade the Python package if you installed OpenRAG in a venv 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
```
</TabItem>
</Tabs>
3. Start the upgraded OpenRAG containers: In the OpenRAG TUI, click **Start All Services**, and then wait while the containers start.
After upgrading the Python package, OpenRAG runs `docker compose pull` to get the appropriate container images matching the version specified in your OpenRAG `.env` file. Then, it recreates the containers with the new images using `docker compose up -d --force-recreate`.
In the `.env` file, the `OPENRAG_VERSION` [environment variable](/reference/configuration#system-settings) is set to `latest` by default, which it pulls the `latest` available container images.
To pin a specific container image version, you can set `OPENRAG_VERSION` to the desired container image version, such as `OPENRAG_VERSION=0.1.33`.
However, when you upgrade the Python package, OpenRAG automatically attempts to keep the `OPENRAG_VERSION` synchronized with the Python package version.
You might need to edit the `.env` file after upgrading the Python package to enforce a different container version.
The TUI warns you if it detects a version mismatch.
If you get an error that `langflow container already exists` error during upgrade, see [Langflow container already exists during upgrade](/support/troubleshoot#langflow-container-already-exists-during-upgrade).
4. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
## Upgrade self-managed containers
By default, OpenRAG's `docker-compose.yml` file pulls the latest container images that are available when you run `docker compose up -d`.
To fetch and apply the latest container images while preserving your OpenRAG data, run the commands for your container management tool:
* Docker Compose:
```bash
docker compose pull
docker compose up -d --force-recreate
```
* Podman Compose:
```bash
podman-compose pull
podman-compose up -d --force-recreate
```

4
docs/docs/reference/configuration.mdx
View file

@ -43,7 +43,7 @@ To set mutable environment variables, do the following:
Certain environment variables that you set during [application onboarding](/install#application-onboarding), such as provider API keys and provider endpoints, require resetting the containers after modifying the `.env` file. Certain environment variables that you set during [application onboarding](/install#application-onboarding), such as provider API keys and provider endpoints, require resetting the containers after modifying the `.env` file.
To change immutable variables with TUI-managed containers, you must [reinstall OpenRAG](/install#reinstall) and either delete or modify the `.env` file before you repeat the setup and onboarding process in the TUI. To change immutable variables with TUI-managed containers, you must [reinstall OpenRAG](/reinstall) and either delete or modify the `.env` file before you repeat the setup and onboarding process in the TUI.
To change immutable variables with self-managed containers, do the following: To change immutable variables with self-managed containers, do the following:
@ -153,7 +153,7 @@ Configure general system components, session management, and logging.
| `LOG_FORMAT` | Disabled | Set to `json` to enabled JSON-formatted log output. | | `LOG_FORMAT` | Disabled | Set to `json` to enabled JSON-formatted log output. |
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR). | | `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR). |
| `MAX_WORKERS` | `1` | Maximum number of workers for document processing. | | `MAX_WORKERS` | `1` | Maximum number of workers for document processing. |
| `OPENRAG_VERSION` | `latest` | The version of the OpenRAG Docker images to run. For more information, see [Upgrade OpenRAG](/install#upgrade) | | `OPENRAG_VERSION` | `latest` | The version of the OpenRAG Docker images to run. For more information, see [Upgrade OpenRAG](/upgrade) |
| `SERVICE_NAME` | `openrag` | Service name for logging. | | `SERVICE_NAME` | `openrag` | Service name for logging. |
| `SESSION_SECRET` | Automatically generated | Session management. | | `SESSION_SECRET` | Automatically generated | Session management. |

12
docs/docs/support/troubleshoot.mdx
View file

@ -120,17 +120,13 @@ To resolve this issue, do the following:
</TabItem> </TabItem>
</Tabs> </Tabs>
2. Retry the upgrade: 2. Retry the [upgrade](/upgrade).
* [Upgrade self-managed containers](/docker#upgrade-containers) 3. If reinstalling the Langflow container doesn't resolve the issue, then you must [reset all containers](/manage-containers) or [reinstall OpenRAG](/reinstall).
* [Upgrade TUI-managed containers](/install#upgrade)
3. If reinstalling the Langflow container doesn't resolve the issue, you must reset your OpenRAG deployment: 4. Retry the [upgrade](/upgrade).
* [Reset self-managed containers](/docker#reset-containers) If no updates are available after reinstalling OpenRAG, then you reinstalled at the latest version, and your deployment is up to date.
* [Reset TUI-managed containers](/install#reset-containers)
4. Retry the upgrade.
## Document ingestion or similarity search issues ## Document ingestion or similarity search issues

29
docs/sidebars.js
View file

@ -27,19 +27,34 @@ const sidebars = {
label: "Installation", label: "Installation",
items: [ items: [
"get-started/install-options", "get-started/install-options",
"get-started/install", { type: "doc",
"get-started/install-uv-add", id: "get-started/install",
"get-started/install-uv-pip", label: "Run the installer script",
},
{ type: "doc",
id: "get-started/install-uv",
label: "Install OpenRAG with uv",
},
"get-started/install-uvx", "get-started/install-uvx",
"get-started/install-windows", { type: "doc",
"get-started/docker", id: "get-started/install-windows",
label: "Install OpenRAG on Windows",
},
{ type: "doc",
id: "get-started/docker",
label: "Deploy self-managed containers",
},
"get-started/upgrade", "get-started/upgrade",
"get-started/reset-reinstall", "get-started/reinstall",
"get-started/uninstall", "get-started/uninstall",
], ],
}, },
"get-started/tui", "get-started/tui",
"get-started/manage-containers", {
type: "doc",
id: "get-started/manage-containers",
label: "Manage containers",
},
{ {
type: "doc", type: "doc",
id: "core-components/agents", id: "core-components/agents",