start breaking up content into the new pages
This commit is contained in:
April M
parent
20e67d0ce5
commit
9f085a8637
18 changed files with 406 additions and 172 deletions
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Install OpenRAG containers
|
||||
title: Deploy OpenRAG with self-managed containers
|
||||
slug: /docker
|
||||
---
|
||||
|
||||
|
|
@ -8,6 +8,9 @@ import TabItem from '@theme/TabItem';
|
|||
import PartialOnboarding from '@site/docs/_partial-onboarding.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:
|
||||
|
||||
- [`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
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -185,6 +189,8 @@ docker compose up -d --force-recreate
|
|||
|
||||
### Reset containers (destructive) {#reset-containers}
|
||||
|
||||
<!-- part of this needs to be on /reinstall and /uninstall -->
|
||||
|
||||
:::warning
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
26
docs/docs/get-started/install-uv.mdx
Normal file
26
docs/docs/get-started/install-uv.mdx
Normal 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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Install OpenRAG with TUI
|
||||
title: Install OpenRAG with the automatic installer script
|
||||
slug: /install
|
||||
---
|
||||
|
||||
|
|
@ -8,17 +8,16 @@ 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.
|
||||
:::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).
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
|
@ -174,7 +173,9 @@ Choose an installation method based on your needs:
|
|||
</TabItem>
|
||||
</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).
|
||||
|
||||
|
||||
|
||||
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 />
|
||||
|
||||
## 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.
|
||||
|
|
@ -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>.
|
||||
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).
|
||||
|
||||
|
|
@ -318,7 +310,7 @@ This operation _doesn't_ remove the `.env` file or the contents of the `./openra
|
|||
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.
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
* [Manage OpenRAG containers](/manage-containers)
|
||||
* [Chat](/chat)
|
||||
* [Upload documents](/ingestion)
|
||||
|
|
@ -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)
|
||||
|
|
@ -30,10 +30,11 @@ For other providers, see the complete [installation guide](/install).
|
|||
|
||||
</details>
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
|
|
@ -48,10 +49,13 @@ For this quickstart, install OpenRAG with the automatic installer script and bas
|
|||
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.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
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
|
||||
Services started successfully
|
||||
|
|
@ -158,9 +162,8 @@ You can send and receive requests with the Langflow API using Python, TypeScript
|
|||
|
||||
## Next steps
|
||||
|
||||
* **Reinstall OpenRAG with your preferred settings**: This quickstart used 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.
|
||||
For all installation options, see [Install OpenRAG with TUI](/install) and [Install OpenRAG with containers](/docker).
|
||||
* **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](/reinstall) with your preferred configuration and [installation method](/install-options).
|
||||
|
||||
* **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
28
docs/docs/get-started/reinstall.mdx
Normal 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,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.
|
||||
|
||||
|
||||
|
||||
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)
|
||||
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -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_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR). |
|
||||
| `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. |
|
||||
| `SESSION_SECRET` | Automatically generated | Session management. |
|
||||
|
||||
|
|
|
|||
|
|
@ -120,17 +120,13 @@ To resolve this issue, do the following:
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
2. Retry the upgrade:
|
||||
2. Retry the [upgrade](/upgrade).
|
||||
|
||||
* [Upgrade self-managed containers](/docker#upgrade-containers)
|
||||
* [Upgrade TUI-managed containers](/install#upgrade)
|
||||
3. If reinstalling the Langflow container doesn't resolve the issue, then you must [reset all containers](/manage-containers) or [reinstall OpenRAG](/reinstall).
|
||||
|
||||
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)
|
||||
* [Reset TUI-managed containers](/install#reset-containers)
|
||||
|
||||
4. Retry the upgrade.
|
||||
If no updates are available after reinstalling OpenRAG, then you reinstalled at the latest version, and your deployment is up to date.
|
||||
|
||||
## Document ingestion or similarity search issues
|
||||
|
||||
|
|
|
|||
|
|
@ -27,19 +27,34 @@ const sidebars = {
|
|||
label: "Installation",
|
||||
items: [
|
||||
"get-started/install-options",
|
||||
"get-started/install",
|
||||
"get-started/install-uv-add",
|
||||
"get-started/install-uv-pip",
|
||||
{ type: "doc",
|
||||
id: "get-started/install",
|
||||
label: "Run the installer script",
|
||||
},
|
||||
{ type: "doc",
|
||||
id: "get-started/install-uv",
|
||||
label: "Install OpenRAG with uv",
|
||||
},
|
||||
"get-started/install-uvx",
|
||||
"get-started/install-windows",
|
||||
"get-started/docker",
|
||||
{ type: "doc",
|
||||
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/reset-reinstall",
|
||||
"get-started/reinstall",
|
||||
"get-started/uninstall",
|
||||
],
|
||||
},
|
||||
"get-started/tui",
|
||||
"get-started/manage-containers",
|
||||
{
|
||||
type: "doc",
|
||||
id: "get-started/manage-containers",
|
||||
label: "Manage containers",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "core-components/agents",
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue