From 9f085a8637de772d8236c37d870bdfbe38c184ce Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Wed, 3 Dec 2025 20:24:48 -0800 Subject: [PATCH] start breaking up content into the new pages --- docs/docs/get-started/docker.mdx | 12 +- docs/docs/get-started/install-options.mdx | 30 ++++ docs/docs/get-started/install-uv-add.mdx | 0 docs/docs/get-started/install-uv-pip.mdx | 0 docs/docs/get-started/install-uv.mdx | 26 ++++ docs/docs/get-started/install-uvx.mdx | 27 ++++ docs/docs/get-started/install-windows.mdx | 18 +++ docs/docs/get-started/install.mdx | 160 +++----------------- docs/docs/get-started/manage-containers.mdx | 32 ++++ docs/docs/get-started/quickstart.mdx | 21 +-- docs/docs/get-started/reinstall.mdx | 28 ++++ docs/docs/get-started/reset-reinstall.mdx | 0 docs/docs/get-started/tui.mdx | 31 ++++ docs/docs/get-started/uninstall.mdx | 14 ++ docs/docs/get-started/upgrade.mdx | 134 ++++++++++++++++ docs/docs/reference/configuration.mdx | 4 +- docs/docs/support/troubleshoot.mdx | 12 +- docs/sidebars.js | 29 +++- 18 files changed, 406 insertions(+), 172 deletions(-) delete mode 100644 docs/docs/get-started/install-uv-add.mdx delete mode 100644 docs/docs/get-started/install-uv-pip.mdx create mode 100644 docs/docs/get-started/install-uv.mdx create mode 100644 docs/docs/get-started/reinstall.mdx delete mode 100644 docs/docs/get-started/reset-reinstall.mdx diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index 64555bbb..407cf1f0 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -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 + + 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} + + :::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. diff --git a/docs/docs/get-started/install-options.mdx b/docs/docs/get-started/install-options.mdx index e69de29b..a9c6d8cf 100644 --- a/docs/docs/get-started/install-options.mdx +++ b/docs/docs/get-started/install-options.mdx @@ -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). \ No newline at end of file diff --git a/docs/docs/get-started/install-uv-add.mdx b/docs/docs/get-started/install-uv-add.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/docs/get-started/install-uv-pip.mdx b/docs/docs/get-started/install-uv-pip.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/docs/get-started/install-uv.mdx b/docs/docs/get-started/install-uv.mdx new file mode 100644 index 00000000..916df9e7 --- /dev/null +++ b/docs/docs/get-started/install-uv.mdx @@ -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) \ No newline at end of file diff --git a/docs/docs/get-started/install-uvx.mdx b/docs/docs/get-started/install-uvx.mdx index e69de29b..0611ea70 100644 --- a/docs/docs/get-started/install-uvx.mdx +++ b/docs/docs/get-started/install-uvx.mdx @@ -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) \ No newline at end of file diff --git a/docs/docs/get-started/install-windows.mdx b/docs/docs/get-started/install-windows.mdx index e69de29b..08564754 100644 --- a/docs/docs/get-started/install-windows.mdx +++ b/docs/docs/get-started/install-windows.mdx @@ -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) \ No newline at end of file diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 789f12c8..1b4f4417 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -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). -![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. - -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: -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). @@ -263,15 +264,6 @@ If OpenRAG detects OAuth credentials, it recommends **Advanced Setup**. -## Exit the OpenRAG TUI - -To exit the OpenRAG TUI, navigate to the main menu, and then press q. -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 l. 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/). - - - - - 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 - ``` - - - - - 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 - ``` - - - - - 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 - ``` - - - - -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. \ No newline at end of file +* [Manage OpenRAG containers](/manage-containers) +* [Chat](/chat) +* [Upload documents](/ingestion) \ No newline at end of file diff --git a/docs/docs/get-started/manage-containers.mdx b/docs/docs/get-started/manage-containers.mdx index e69de29b..584701fa 100644 --- a/docs/docs/get-started/manage-containers.mdx +++ b/docs/docs/get-started/manage-containers.mdx @@ -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) \ No newline at end of file diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx index f8b227bd..2359d6ae 100644 --- a/docs/docs/get-started/quickstart.mdx +++ b/docs/docs/get-started/quickstart.mdx @@ -30,10 +30,11 @@ For other providers, see the complete [installation guide](/install). - ## 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. + + ![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg) 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. diff --git a/docs/docs/get-started/reinstall.mdx b/docs/docs/get-started/reinstall.mdx new file mode 100644 index 00000000..22f803f0 --- /dev/null +++ b/docs/docs/get-started/reinstall.mdx @@ -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: \ No newline at end of file diff --git a/docs/docs/get-started/reset-reinstall.mdx b/docs/docs/get-started/reset-reinstall.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx index e69de29b..24bc4bc0 100644 --- a/docs/docs/get-started/tui.mdx +++ b/docs/docs/get-started/tui.mdx @@ -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 q. + +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) \ No newline at end of file diff --git a/docs/docs/get-started/uninstall.mdx b/docs/docs/get-started/uninstall.mdx index e69de29b..bdce92cc 100644 --- a/docs/docs/get-started/uninstall.mdx +++ b/docs/docs/get-started/uninstall.mdx @@ -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). \ No newline at end of file diff --git a/docs/docs/get-started/upgrade.mdx b/docs/docs/get-started/upgrade.mdx index e69de29b..b81063da 100644 --- a/docs/docs/get-started/upgrade.mdx +++ b/docs/docs/get-started/upgrade.mdx @@ -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/). + + + + + 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 + ``` + + + + + 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 + ``` + + + + + 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 + ``` + + + + +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 + ``` \ No newline at end of file diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index 97d71a2c..412108cb 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -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. | diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx index 98cd7d55..70a80d35 100644 --- a/docs/docs/support/troubleshoot.mdx +++ b/docs/docs/support/troubleshoot.mdx @@ -120,17 +120,13 @@ To resolve this issue, do the following: -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 diff --git a/docs/sidebars.js b/docs/sidebars.js index dae7199a..736a658e 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -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",