From ef85366d18f66c8dee5bd2d9b49a766e546c5e17 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Wed, 3 Dec 2025 16:58:01 -0800 Subject: [PATCH 01/17] add empty files --- docs/docs/get-started/install-options.mdx | 0 docs/docs/get-started/install-uv-add.mdx | 0 docs/docs/get-started/install-uv-pip.mdx | 0 docs/docs/get-started/install-uvx.mdx | 0 docs/docs/get-started/install-windows.mdx | 0 docs/docs/get-started/manage-containers.mdx | 0 docs/docs/get-started/reset-reinstall.mdx | 0 docs/docs/get-started/tui.mdx | 0 docs/docs/get-started/upgrade.mdx | 0 9 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/docs/get-started/install-options.mdx create mode 100644 docs/docs/get-started/install-uv-add.mdx create mode 100644 docs/docs/get-started/install-uv-pip.mdx create mode 100644 docs/docs/get-started/install-uvx.mdx create mode 100644 docs/docs/get-started/install-windows.mdx create mode 100644 docs/docs/get-started/manage-containers.mdx create mode 100644 docs/docs/get-started/reset-reinstall.mdx create mode 100644 docs/docs/get-started/tui.mdx create mode 100644 docs/docs/get-started/upgrade.mdx diff --git a/docs/docs/get-started/install-options.mdx b/docs/docs/get-started/install-options.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/install-uv-add.mdx b/docs/docs/get-started/install-uv-add.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/install-uv-pip.mdx b/docs/docs/get-started/install-uv-pip.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/install-uvx.mdx b/docs/docs/get-started/install-uvx.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/install-windows.mdx b/docs/docs/get-started/install-windows.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/manage-containers.mdx b/docs/docs/get-started/manage-containers.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/reset-reinstall.mdx b/docs/docs/get-started/reset-reinstall.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/get-started/upgrade.mdx b/docs/docs/get-started/upgrade.mdx new file mode 100644 index 00000000..e69de29b From 20e67d0ce525a363030704ba8f8ec9a61ee1e9ec Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:05:44 -0800 Subject: [PATCH 02/17] one more page and fix typo --- docs/docs/get-started/uninstall.mdx | 0 docs/docs/support/troubleshoot.mdx | 2 +- docs/sidebars.js | 20 ++++++++++++++++++-- 3 files changed, 19 insertions(+), 3 deletions(-) create mode 100644 docs/docs/get-started/uninstall.mdx diff --git a/docs/docs/get-started/uninstall.mdx b/docs/docs/get-started/uninstall.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx index 546bddf2..98cd7d55 100644 --- a/docs/docs/support/troubleshoot.mdx +++ b/docs/docs/support/troubleshoot.mdx @@ -123,7 +123,7 @@ To resolve this issue, do the following: 2. Retry the upgrade: * [Upgrade self-managed containers](/docker#upgrade-containers) - * [Upgrade TUI-managed containers](/install#upgrade-containers) + * [Upgrade TUI-managed containers](/install#upgrade) 3. If reinstalling the Langflow container doesn't resolve the issue, you must reset your OpenRAG deployment: diff --git a/docs/sidebars.js b/docs/sidebars.js index 3549d62e..dae7199a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -22,8 +22,24 @@ const sidebars = { label: "About OpenRAG" }, "get-started/quickstart", - "get-started/install", - "get-started/docker", + { + type: "category", + label: "Installation", + items: [ + "get-started/install-options", + "get-started/install", + "get-started/install-uv-add", + "get-started/install-uv-pip", + "get-started/install-uvx", + "get-started/install-windows", + "get-started/docker", + "get-started/upgrade", + "get-started/reset-reinstall", + "get-started/uninstall", + ], + }, + "get-started/tui", + "get-started/manage-containers", { type: "doc", id: "core-components/agents", 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 03/17] 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", From 81d14dd1c9c4004609e397d7a675ac0f671caa49 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Thu, 4 Dec 2025 10:35:11 -0800 Subject: [PATCH 04/17] broken links --- docs/docs/get-started/install-options.mdx | 2 +- docs/docs/get-started/reinstall.mdx | 10 ++++++---- docs/docs/get-started/uninstall.mdx | 4 ++-- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/docs/get-started/install-options.mdx b/docs/docs/get-started/install-options.mdx index a9c6d8cf..8e68daa8 100644 --- a/docs/docs/get-started/install-options.mdx +++ b/docs/docs/get-started/install-options.mdx @@ -14,7 +14,7 @@ Choose the installation method that best fits your needs: * [**`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). +* [**Install OpenRAG on Microsoft Windows**](/install-windows): 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. diff --git a/docs/docs/get-started/reinstall.mdx b/docs/docs/get-started/reinstall.mdx index 22f803f0..be20b6db 100644 --- a/docs/docs/get-started/reinstall.mdx +++ b/docs/docs/get-started/reinstall.mdx @@ -7,7 +7,7 @@ You can reset your OpenRAG deployment to its initial state by recreating the con ## Reinstall TUI-managed containers -1. In the TUI, [reset your containers](/manage-containers#reset-containers) to destroy the following: +1. In the TUI, [reset your containers](/manage-containers) to destroy the following: * All existing OpenRAG containers, volumes, and local images * Any additional Docker objects @@ -17,11 +17,13 @@ You can reset your OpenRAG deployment to its initial state by recreating the con 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. + * **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, OpenRAG automatically generates a new one after you repeat the initial setup and onboarding process. Alternatively, you can add a prepopulated `.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. +3. In the TUI **Setup** menu, repeat the **Basic/Advanced Setup** process to configure OpenRAG and restart all services. +Then, launch the OpenRAG app and repeat application onboarding. + + If OpenRAG detects a `.env` file during start up, it automatically populates any OpenRAG passwords, OAuth credentials, and onboarding configuration set in that file. ## Reinstall self-managed containers diff --git a/docs/docs/get-started/uninstall.mdx b/docs/docs/get-started/uninstall.mdx index bdce92cc..e438fdd4 100644 --- a/docs/docs/get-started/uninstall.mdx +++ b/docs/docs/get-started/uninstall.mdx @@ -4,11 +4,11 @@ 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 want to reset your OpenRAG containers without removing OpenRAG entirely, see [Reset OpenRAG containers](/manage-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 +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). \ No newline at end of file From e2c4d0a9e5f88f060cb60d9ccd0809796d6efe30 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Thu, 4 Dec 2025 10:56:21 -0800 Subject: [PATCH 05/17] breaking out install tabs to separate pages --- docs/docs/get-started/install-uv.mdx | 58 +++++++++ docs/docs/get-started/install-uvx.mdx | 28 ++++ docs/docs/get-started/install-windows.mdx | 9 ++ docs/docs/get-started/install.mdx | 149 +++------------------- 4 files changed, 115 insertions(+), 129 deletions(-) diff --git a/docs/docs/get-started/install-uv.mdx b/docs/docs/get-started/install-uv.mdx index 916df9e7..7e15e66e 100644 --- a/docs/docs/get-started/install-uv.mdx +++ b/docs/docs/get-started/install-uv.mdx @@ -15,9 +15,67 @@ For other installation methods, see [Choose an installation method](/install-opt * **`uv add`** (Recommended): Install OpenRAG as a managed dependency in a new or existing Python project. +## uv add (Recommended) + + Use `uv add` to install OpenRAG as a dependency in your Python project. This adds OpenRAG to your `pyproject.toml` and lockfile, making your installation reproducible and version-controlled. + + 1. Create a new project with a virtual environment: + ```bash + uv init YOUR_PROJECT_NAME + cd YOUR_PROJECT_NAME + ``` + + The `(venv)` prompt doesn't change, but `uv` commands will automatically use the project's virtual environment. + + 2. Add the OpenRAG package to your project: + ```bash + uv add openrag + ``` + + To add a specific version: + ```bash + uv add openrag==0.1.30 + ``` + + If you downloaded the OpenRAG wheel to your local machine, install OpenRAG by specifying the path and name of the OpenRAG `.whl` file: + + ```bash + uv add PATH/TO/openrag-VERSION-py3-none-any.whl + ``` + + 3. Start the OpenRAG TUI: + ```bash + uv run openrag + ``` +If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot). +## uv pip install + Use `uv pip install` to install OpenRAG into an existing virtual environment that isn't managed by `uv`. + + :::tip + For new projects, `uv add` is recommended as it manages dependencies in your project's lockfile. + ::: + + 1. Activate your virtual environment. + + 2. Install OpenRAG: + ```bash + uv pip install openrag + ``` + + 3. Run OpenRAG: + ```bash + uv run openrag + ``` + If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot). + +## Set up OpenRAG with the TUI + +When the Terminal User Interface (TUI) starts, you must complete the initial setup to configure OpenRAG. + +![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg) ## Next steps diff --git a/docs/docs/get-started/install-uvx.mdx b/docs/docs/get-started/install-uvx.mdx index 0611ea70..82e9263e 100644 --- a/docs/docs/get-started/install-uvx.mdx +++ b/docs/docs/get-started/install-uvx.mdx @@ -17,7 +17,35 @@ The [automatic installer script](/install) also uses `uvx` to install OpenRAG. For other installation methods, see [Choose an installation method](/install-options). +## Install and run OpenRAG with uvx + Use `uvx` to quickly run OpenRAG without creating a project or modifying any files. + + 1. Create a directory to store the OpenRAG configuration files: + ```bash + mkdir openrag-workspace + cd openrag-workspace + ``` + + 2. Run OpenRAG: + ```bash + uvx openrag + ``` + + To run a specific version: + ```bash + uvx --from openrag==0.1.30 openrag + ``` + + When you install OpenRAG with `uvx`, OpenRAG creates its `.env` and `docker-compose.yml` files in the current working directory. + + If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot). + +## Set up OpenRAG with the TUI + +When the Terminal User Interface (TUI) starts, you must complete the initial setup to configure OpenRAG. + +![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg) ## Next steps diff --git a/docs/docs/get-started/install-windows.mdx b/docs/docs/get-started/install-windows.mdx index 08564754..cbcc3f6b 100644 --- a/docs/docs/get-started/install-windows.mdx +++ b/docs/docs/get-started/install-windows.mdx @@ -3,13 +3,22 @@ title: Install OpenRAG on Microsoft Windows slug: /install-windows --- +import PartialWsl from '@site/docs/_partial-wsl-install.mdx'; + 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. +## Nested virtualization isn't supported +## Prepare your WSL environment + + +## Install OpenRAG within the WSL + + ## Next steps diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 1b4f4417..f21bc32d 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -6,7 +6,6 @@ slug: /install import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; -import PartialWsl from '@site/docs/_partial-wsl-install.mdx'; :::tip For a fully guided installation and preview of OpenRAG's core features, try the [quickstart](/quickstart). @@ -29,14 +28,8 @@ For other installation methods, see [Choose an installation method](/install-opt - [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/). - [`podman-compose`](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or [Docker Compose](https://docs.docker.com/compose/install/). To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands. -- Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL). - -
- Install WSL for OpenRAG - - - -
+- To run OpenRAG on Microsoft Windows, you must use the Windows Subsystem for Linux (WSL). +See [Install OpenRAG on Windows](/install-windows). - Prepare model providers and credentials. @@ -55,131 +48,29 @@ For other installation methods, see [Choose an installation method](/install-opt ## Install OpenRAG {#install} -Choose an installation method based on your needs: +The script detects and installs uv, Docker/Podman, and Docker Compose prerequisites, then runs OpenRAG with `uvx`. -* For new users, the automatic installer script detects and installs prerequisites and then runs OpenRAG. -* For a quick test, use `uvx` to run OpenRAG without creating a project or modifying files. -* Use `uv add` to install OpenRAG as a managed dependency in a new or existing Python project. -* Use `uv pip install` to install OpenRAG into an existing virtual environment. - - - - - The script detects and installs uv, Docker/Podman, and Docker Compose prerequisites, then runs OpenRAG with `uvx`. - - 1. Create a directory to store the OpenRAG configuration files: - ```bash - mkdir openrag-workspace - cd openrag-workspace - ``` - - 2. Run the installer: - ```bash - curl -fsSL https://docs.openr.ag/files/run_openrag_with_prereqs.sh | bash - ``` - - The TUI creates a `.env` file and docker-compose files in the current working directory. - - - - - Use `uvx` to quickly run OpenRAG without creating a project or modifying any files. - - 1. Create a directory to store the OpenRAG configuration files: - ```bash - mkdir openrag-workspace - cd openrag-workspace - ``` - - 2. Run OpenRAG: - ```bash - uvx openrag - ``` - - To run a specific version: - ```bash - uvx --from openrag==0.1.30 openrag - ``` - - The TUI creates a `.env` file and docker-compose files in the current working directory. - - - - - Use `uv add` to install OpenRAG as a dependency in your Python project. This adds OpenRAG to your `pyproject.toml` and lockfile, making your installation reproducible and version-controlled. - - 1. Create a new project with a virtual environment: - ```bash - uv init YOUR_PROJECT_NAME - cd YOUR_PROJECT_NAME - ``` - - The `(venv)` prompt doesn't change, but `uv` commands will automatically use the project's virtual environment. - - 2. Add OpenRAG to your project: - ```bash - uv add openrag - ``` - - To add a specific version: - ```bash - uv add openrag==0.1.30 - ``` - - 3. Start the OpenRAG TUI: - ```bash - uv run openrag - ``` - -
- Install a local wheel - - If you downloaded the OpenRAG wheel to your local machine, install it by specifying its path: - - 1. Add the wheel to your project: - ```bash - uv add PATH/TO/openrag-VERSION-py3-none-any.whl - ``` - - Replace `PATH/TO/` and `VERSION` with the path and version of your downloaded OpenRAG `.whl` file. - - 2. Run OpenRAG: - ```bash - uv run openrag - ``` -
- - - - - Use `uv pip install` to install OpenRAG into an existing virtual environment that isn't managed by `uv`. - - :::tip - For new projects, `uv add` is recommended as it manages dependencies in your project's lockfile. - ::: - - 1. Activate your virtual environment. - - 2. Install OpenRAG: - ```bash - uv pip install openrag - ``` - - 3. Run OpenRAG: - ```bash - uv run openrag - ``` - - - - -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) +1. Create a directory to store the OpenRAG configuration files: + ```bash + mkdir openrag-workspace + cd openrag-workspace + ``` +2. Run the installer: + ```bash + curl -fsSL https://docs.openr.ag/files/run_openrag_with_prereqs.sh | bash + ``` + +The installer script installs OpenRAG with `uvx`. +When installed in this way, OpenRAG creates its `.env` and `docker-compose.yml` files in the current working directory. + If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot). ## Set up OpenRAG with the TUI {#setup} + +When the Terminal User Interface (TUI) starts, you must complete the initial setup to configure OpenRAG. + +![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg) The OpenRAG setup process creates a `.env` file at the root of your OpenRAG directory, and then starts OpenRAG. If it detects a `.env` file in the OpenRAG root directory, it sources any variables from the `.env` file. From d578e7832e67882d6d3da4721629f2861bca494f Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Thu, 4 Dec 2025 17:17:00 -0800 Subject: [PATCH 06/17] revised setup, explain uv cache, rename svc mgmt --- docs/docs/core-components/ingestion.mdx | 8 +- docs/docs/core-components/knowledge.mdx | 25 ++- docs/docs/get-started/docker.mdx | 9 +- docs/docs/get-started/install-options.mdx | 15 +- docs/docs/get-started/install-uv.mdx | 4 +- docs/docs/get-started/install-uvx.mdx | 34 +-- docs/docs/get-started/install-windows.mdx | 6 +- docs/docs/get-started/install.mdx | 237 ++++++++++---------- docs/docs/get-started/manage-containers.mdx | 32 --- docs/docs/get-started/manage-services.mdx | 103 +++++++++ docs/docs/get-started/quickstart.mdx | 35 +-- docs/docs/get-started/reinstall.mdx | 2 +- docs/docs/get-started/tui.mdx | 8 +- docs/docs/get-started/uninstall.mdx | 6 +- docs/docs/get-started/upgrade.mdx | 10 +- docs/docs/reference/configuration.mdx | 45 ++-- docs/docs/support/troubleshoot.mdx | 30 ++- docs/sidebars.js | 6 +- 18 files changed, 347 insertions(+), 268 deletions(-) delete mode 100644 docs/docs/get-started/manage-containers.mdx create mode 100644 docs/docs/get-started/manage-services.mdx diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx index 3e991176..33fb1420 100644 --- a/docs/docs/core-components/ingestion.mdx +++ b/docs/docs/core-components/ingestion.mdx @@ -64,11 +64,11 @@ To enable multiple connectors, you must register an app and generate credentials -If you use the TUI to manage your OpenRAG containers, provide OAuth credentials in the **Advanced Setup**. +If you use the TUI to manage your OpenRAG services, provide OAuth credentials in the **Advanced Setup**. You can do this during [installation](/install#setup), or you can add the credentials afterwards: -1. If OpenRAG is running, stop it: Go to [**Status**](/install#tui-container-management), and then click **Stop Services**. +1. If OpenRAG is running, stop it: Go to [**Status**](/manage-services#tui-container-management), and then click **Stop Services**. 2. Click **Advanced Setup**, and then add the OAuth credentials for the cloud storage providers that you want to use: @@ -83,12 +83,12 @@ These are the URLs your OAuth provider will redirect back to after users authent OpenRAG regenerates the [`.env`](/reference/configuration) file with the given credentials. -5. Click **Start Container Services**. +5. Click **Start All Services**. -If you [install OpenRAG with self-managed containers](/docker), set OAuth credentials in the `.env` file for Docker Compose. +If you [installed OpenRAG with self-managed services](/docker), set OAuth credentials in the `.env` file for Docker Compose. You can do this during [initial set up](/docker#install-openrag-with-docker-compose), or you can add the credentials afterwards: diff --git a/docs/docs/core-components/knowledge.mdx b/docs/docs/core-components/knowledge.mdx index 3edf5a55..86604cbb 100644 --- a/docs/docs/core-components/knowledge.mdx +++ b/docs/docs/core-components/knowledge.mdx @@ -32,20 +32,21 @@ It is recommended that you keep these documents, and use [filters](/knowledge-fi ## OpenSearch authentication and document access {#auth} -When you [install OpenRAG](/install), you can choose between two setup modes: **Basic Setup** and **Advanced Setup**. -The mode you choose determines how OpenRAG authenticates with OpenSearch and controls access to documents: +When you [install OpenRAG](/install-options), you provide the initial configuration values for your OpenRAG services. +This includes authentication credentials for OpenSearch and OAuth connectors. +This configuration determines how OpenRAG authenticates with OpenSearch and controls access to documents in your knowledge base: -* **Basic Setup (no-auth mode)**: If you choose **Basic Setup**, then OpenRAG is installed in no-auth mode. -This mode uses one, anonymous JWT token for OpenSearch authentication. -There is no differentiation between users. -All users that access your OpenRAG instance can access all documents uploaded to your OpenSearch knowledge base. +* **No-auth mode (basic setup)**: If you choose **Basic Setup** in the [TUI](/tui), or your `.env` file doesn't include OAuth credentials, then OpenRAG runs in no-auth mode. -* **Advanced Setup (OAuth mode)**: If you choose **Advanced Setup**, then OpenRAG is installed in OAuth mode. -This mode uses a unique JWT token for each OpenRAG user, and each document is tagged with user ownership. Documents are filtered by user owner. -This means users see only the documents that they uploaded or have access to. + This mode uses one anonymous JWT token for OpenSearch authentication. + There is no differentiation between users; all users that access your OpenRAG instance can access all documents uploaded to your knowledge base. -You can enable OAuth mode after installation. -For more information, see [Ingest files with OAuth connectors](/ingestion#oauth-ingestion). +* **OAuth mode (advanced setup)**: If you choose **Advanced Setup** in the [TUI](/tui), or your `.env` file includes OAuth credentials, then OpenRAG runs in OAuth mode. + + This mode uses a unique JWT token for each OpenRAG user, and each document is tagged with user ownership. + Documents are filtered by user owner; users see only the documents that they uploaded or have access to through their cloud storage accounts. + + You can enable OAuth mode after installation, as explained in [Ingest files with OAuth connectors](/ingestion#oauth-ingestion). ## OpenSearch indexes @@ -119,7 +120,7 @@ To modify the Docling ingestion and embedding parameters, click - 1. To install OpenRAG with **Basic Setup**, click **Basic Setup** or press 1. - 2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow. + 1. In the TUI, click **Basic Setup** or press 1. - The OpenSearch password is required. The Langflow admin password is optional. - If no Langflow admin password is generated, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required. + 2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically. + + The OpenSearch password is required. + + The Langflow password is optional. + If the Langflow password is empty, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) without password authentication. + + 3. Optional: Enter your OpenAI API key, or leave this field empty if you want to configure model provider credentials later during application onboarding. - 3. Optional: Paste your OpenAI API key in the OpenAI API key field. You can also provide this during onboarding or choose a different model provider. 4. Click **Save Configuration**. - Your passwords are saved in the `.env` file used to start OpenRAG. - 5. To start OpenRAG, click **Start All Services**. - Startup pulls container images and runs them, so it can take some time. - When startup is complete, the TUI displays the following: - ```bash + + Your passwords and API key, if provided, are stored in the `.env` file in your OpenRAG installation directory. + If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file. + + 5. Click **Start All Services** to start the OpenRAG services that run in containers. + + This process can take some time while OpenRAG pulls and runs the container images. + If all services start successfully, the TUI prints a confirmation message: + + ```text Services started successfully Command completed successfully ``` - 6. To start the Docling service, under **Native Services**, click **Start**. - 7. To open the OpenRAG application, navigate to the TUI main menu, and then click **Open App**. - Alternatively, in your browser, navigate to `localhost:3000`. + + 6. Under [**Native Services**](/manage-services), click **Start** to start the Docling service. + + 7. Launch the OpenRAG application: + + * From the TUI main menu, click **Open App**. + * In your browser, navigate to `localhost:3000`. + 8. Continue with [application onboarding](#application-onboarding). + - 1. To install OpenRAG with **Advanced Setup**, click **Advanced Setup** or press 2. - 2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow. + 1. In the TUI, click **Advanced Setup** or press 2. - The OpenSearch password is required. The Langflow admin password is optional. - If no Langflow admin password is generated, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required. + 2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically. - 3. Paste your OpenAI API key in the OpenAI API key field. - 4. If you want to upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in a `.env` file in the OpenRAG installation directory. + The OpenSearch password is required. + + The Langflow password is optional. + If the Langflow password is empty, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) without password authentication. + + 3. Optional: Enter your OpenAI API key, or leave this field empty if you want to configure model provider credentials later during application onboarding. + + 4. To upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in a `.env` file in the OpenRAG installation directory. * **Amazon**: Provide your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on [Configuring access to AWS applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html). * **Google**: Provide your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). For more information, see the [Google OAuth client documentation](https://developers.google.com/identity/protocols/oauth2). @@ -122,113 +170,54 @@ If OpenRAG detects OAuth credentials, it recommends **Advanced Setup**. 5. The OpenRAG TUI presents redirect URIs for your OAuth app. These are the URLs your OAuth provider will redirect back to after user sign-in. Register these redirect values with your OAuth provider as they are presented in the TUI. + 6. Click **Save Configuration**. - 7. To start OpenRAG, click **Start All Services**. - Startup pulls container images and runs them, so it can take some time. - When startup is complete, the TUI displays the following: - ```bash + + Your passwords, API key (if provided), and OAuth credentials (if provided) are stored in the `.env` file in your OpenRAG installation directory. + If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file. + + 7. Click **Start All Services** to start the OpenRAG services that run in containers. + + This process can take some time while OpenRAG pulls and runs the container images. + If all services start successfully, the TUI prints a confirmation message: + + ```text Services started successfully Command completed successfully ``` - 8. To start the Docling service, under **Native Services**, click **Start**. - 9. To open the OpenRAG application, navigate to the TUI main menu, and then click **Open App**. - Alternatively, in your browser, navigate to `localhost:3000`. + + 8. Under [**Native Services**](/manage-services), click **Start** to start the Docling service. + + 9. Launch the OpenRAG application: + + * From the TUI main menu, click **Open App**. + * In your browser, navigate to `localhost:3000`. 10. If you enabled OAuth connectors, you must sign in to your OAuth provider before being redirected to your OpenRAG instance. - 11. Two additional variables are available for **Advanced Setup** at this point. - Only change these variables if you have a non-default network configuration for your deployment, such as using a reverse proxy or custom domain. + 11. If required, you can edit the following additional environment variables. + Only change these variables if your OpenRAG deployment has a non-default network configuration, such as a reverse proxy or custom domain. * `LANGFLOW_PUBLIC_URL`: Sets the base address to access the Langflow web interface. This is where users interact with flows in a browser. - * `WEBHOOK_BASE_URL`: Sets the base address of the OpenRAG OAuth connector endpoint. - Supported webhook endpoints: + * `WEBHOOK_BASE_URL`: Sets the base address for the following OpenRAG OAuth connector endpoints: - Amazon S3: Not applicable. - - Google Drive: `/connectors/google_drive/webhook` - - OneDrive: `/connectors/onedrive/webhook` - - SharePoint: `/connectors/sharepoint/webhook` + - Google Drive: `WEBHOOK_BASE_URL/connectors/google_drive/webhook` + - OneDrive: `WEBHOOK_BASE_URL/connectors/onedrive/webhook` + - SharePoint: `WEBHOOK_BASE_URL/connectors/sharepoint/webhook` 12. Continue with [application onboarding](#application-onboarding). + +The first time you start the OpenRAG application, you must complete application onboarding to select language and embedding models that are essential for OpenRAG features like the [**Chat**](/chat). + -## Manage OpenRAG containers with the TUI {#tui-container-management} - -After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers. - -### Diagnostics - -The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. - -### Status {#status} - -The **Status** menu displays information on your container deployment. -Here you can check container health, find your service ports, view logs, and upgrade your containers. - -* **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). - -* **Factory Reset**: This is a destructive action that [resets your containers](#reset-containers). - -* **Native services**: [View and manage OpenRAG services](#start-all-services) that run directly on your local machine instead of a container. - -### Reset containers {#reset-containers} - -Reset your OpenRAG deployment by recreating the containers and removing some related data. - -:::warning -This is a destructive action that destroys the following: - -* All OpenRAG containers, volumes, and local images -* Any additional Docker objects -* The contents of OpenRAG's `config` and `./opensearch-data` directories -* The `conversations.json` file - -This operation _doesn't_ remove the `.env` file or the contents of the `./openrag-documents` directory. -::: - -1. To destroy and recreate your OpenRAG containers, go to the TUI [**Status** menu](#status), and then click **Factory Reset**. - - This function runs the following commands _and_ deletes the contents of OpenRAG's `config` and `./opensearch-data` directories. - - ```bash - docker compose down --volumes --remove-orphans --rmi local - docker system prune -f - ``` - -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} - -Through the TUI, you can view and manage OpenRAG services that run in containers and directly on your local machine. - -#### Start containers - -On the TUI main page or the **Setup** menu, click **Start All Services** to start the OpenRAG containers and launch OpenRAG itself. - -When you start all services, the following processes happen: - -1. OpenRAG automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for `CUDA`, `NVIDIA_SMI`, and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses. - -2. OpenRAG pulls the OpenRAG container images with `docker compose pull` if any images are missing. - -3. OpenRAG deploys the containers with `docker compose up -d`. - -#### Start native services (Docling) - -A _native service_ in OpenRAG is a service that runs locally on your machine, not within a container. For example, the `docling serve` process is an OpenRAG native service because this document processing service runs on your local machine, separate from the OpenRAG containers. - -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. - ## Next steps -* [Manage OpenRAG containers](/manage-containers) +* [Manage OpenRAG services](/manage-services) * [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 deleted file mode 100644 index 584701fa..00000000 --- a/docs/docs/get-started/manage-containers.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -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/manage-services.mdx b/docs/docs/get-started/manage-services.mdx new file mode 100644 index 00000000..082ee59a --- /dev/null +++ b/docs/docs/get-started/manage-services.mdx @@ -0,0 +1,103 @@ +--- +title: Manage OpenRAG containers and services +slug: /manage-services +--- + +Service management is an essential part of maintaining your OpenRAG deployment. + +Most OpenRAG services run in containers. + +_Native services_, like Docling, run directly on the local machine where you installed OpenRAG. + +## Manage containers and services with the TUI {#tui-container-management} + +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 services: + +* Start and stop OpenRAG container-based services. +* 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). + +### Diagnostics + +The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. + +### Status {#status} + +The TUI's **Status** menu provides information about your OpenRAG services, including health, ports, logs, and controls: + +* **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 to OpenRAG. For more information, see [upgrade OpenRAG](/upgrade). + +* **Factory Reset**: This is a destructive action that [resets your containers](#reset-containers). + +* **Native services**: [View and manage OpenRAG's native services](#start-all-services) that run directly on the local machine instead of a container. + +### Reset containers {#reset-containers} + +Reset your OpenRAG deployment by recreating the containers and removing some related data. + +:::warning +This is a destructive action that destroys the following: + +* All OpenRAG containers, volumes, and local images +* Any additional Docker objects +* The contents of OpenRAG's `config` and `./opensearch-data` directories +* The `conversations.json` file + +This operation _doesn't_ remove the `.env` file or the contents of the `./openrag-documents` directory. +::: + +1. To destroy and recreate your OpenRAG containers, go to the TUI [**Status** menu](#status), and then click **Factory Reset**. + + This function runs the following commands _and_ deletes the contents of OpenRAG's `config` and `./opensearch-data` directories. + + ```bash + docker compose down --volumes --remove-orphans --rmi local + docker system prune -f + ``` + +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} + +Through the TUI, you can stop and start OpenRAG services. + +#### Start containers + +On the TUI main page or the **Setup** menu, click **Start All Services** to start the OpenRAG containers. + +When you start all services, the following processes happen: + +1. OpenRAG automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for `CUDA`, `NVIDIA_SMI`, and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses. + +2. OpenRAG pulls the OpenRAG container images with `docker compose pull` if any images are missing. + +3. OpenRAG deploys the containers with `docker compose up -d`. + +#### Start native services (Docling) + +A _native service_ in OpenRAG is a service that runs locally on your machine, not within a container. For example, the `docling serve` process is an OpenRAG native service because this document processing service runs on your local machine, separate from the OpenRAG containers. + +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. + +## 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 2359d6ae..5789e3ed 100644 --- a/docs/docs/get-started/quickstart.mdx +++ b/docs/docs/get-started/quickstart.mdx @@ -33,10 +33,9 @@ For other providers, see the complete [installation guide](/install). ## Install OpenRAG For this quickstart, install OpenRAG with the automatic installer script and basic setup. +The script installs OpenRAG dependencies, including Docker or Podman, and then it installs and runs OpenRAG with [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools). -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 for your OpenRAG installation, and then change to that directory: ```bash mkdir openrag-workspace @@ -53,39 +52,41 @@ This script installs OpenRAG dependencies, including Docker or Podman, installs You might be prompted to install certain dependencies if they aren't already present in your environment. The entire process can take a few minutes. - Once the environment is ready, the OpenRAG Terminal User Interface (TUI) starts. + Once the environment is ready, the OpenRAG [Terminal User Interface (TUI)](/tui) starts. ![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg) -3. Click **Basic Setup**. +3. In the TUI, click **Basic Setup**. -4. Create passwords for your OpenRAG installation's OpenSearch and Langflow services. You can click **Generate Passwords** to automatically generate passwords. +4. Click **Generate Passwords** to create administrator passwords for your OpenRAG OpenSearch and Langflow services. - The OpenSearch password is required. The Langflow admin password is optional. - If you don't generate a Langflow admin password, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required. +5. Leave the **OpenAI API key** field empty. Your passwords are saved in the `.env` file that is used to start OpenRAG. You can find this file in your OpenRAG installation directory. -5. Click **Save Configuration**, and then click **Start All Services**. +6. 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 TUI: + This process can take some time while OpenRAG pulls and runs the container images. + If all services start successfully, the TUI prints a confirmation message: - ```bash + ```text Services started successfully Command completed successfully ``` -6. To open the OpenRAG application, go to the TUI main menu, and then click **Open App**. -Alternatively, in your browser, navigate to `localhost:3000`. + Your [OpenRAG configuration](/reference/configuration) is stored in a `.env` file that is created automatically in the directory where you ran the installer script. + Container definitions are stored in a `docker-compose.yml` file in the same directory. -7. Select the **OpenAI** model provider, enter your OpenAI API key, and then click **Complete**. +7. Under [**Native Services**](/manage-services), click **Start** to start the Docling service. - For this quickstart, you can use the default options for the model settings. +8. From the TUI main menu, click **Open App** to launch the OpenRAG application and start the application onboarding process. -8. Click through the overview slides for a brief introduction to OpenRAG and basic setup, or click