diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 03f71637..da513712 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -276,171 +276,180 @@ If you installed OpenRAG with `uvx`, run `uvx openrag`. After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers. -### Start all services +### Diagnostics -Click **Start All Services** to start the OpenRAG containers. -The TUI automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for `CUDA`, `NVIDIA_SMI`, and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses. -The TUI then pulls the images and deploys the containers with the following command. -```bash -docker compose up -d -``` +The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. -If images are missing, the TUI runs `docker compose pull`, then runs `docker compose up -d`. - -### Status +### 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. -To view streaming logs, select the container you want to view, and press l. -To copy your logs, click **Copy to Clipboard**. +* **Logs**: To view streaming logs, select the container you want to view, and press l. +To copy the logs, click **Copy to Clipboard**. -To **upgrade** your containers, click **Upgrade**. -**Upgrade** runs `docker compose pull` and then `docker compose up -d --force-recreate`. -For more information, see [Upgrade OpenRAG containers with the TUI](#upgrade-openrag-containers-with-the-tui). +* **Upgrade**: Check for updates. For more information, see [upgrade OpenRAG](#upgrade). -To **reset** your containers, click **Reset**. -Reset gives you a completely fresh start. -Reset deletes all of your data, including OpenSearch data, uploaded documents, and authentication. -**Reset** runs two commands. -It first stops and removes all containers, volumes, and local images. -``` +* **Reset**: This is a destructive action that [resets your containers](#reset-containers). + +* **Native services**: From the **Status** menu, you can view the status, port, and process ID (PID) of the OpenRAG native services. +You can also click **Stop** or **Restart** to stop and start OpenRAG native services. + + 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. + +### Reset containers {#reset-containers} + +:::warning +This is a destructive action that destroys and recreates all of your OpenRAG containers. +::: + +To destroy and recreate your OpenRAG containers, go to the TUI [**Status** menu](#status), and then click **Reset**. + +The **Reset** function runs two commands. First, it stops and removes all containers, volumes, and local images: + +```bash docker compose down --volumes --remove-orphans --rmi local ``` -When the first command is complete, OpenRAG removes any additional Docker objects with `prune`. +Then, it removes any additional Docker objects with `docker system prune -f`. -``` -docker system prune -f -``` +If you reset your containers as part of reinstalling OpenRAG, continue the [reinstallation process](#reinstall) after resetting the containers. -### Native services status +### Start all services -A _native service_ in OpenRAG refers to a service run locally on your machine, and not within a container. -The `docling serve` process is a native service in OpenRAG, because it's a document processing service that is run on your local machine, and controlled separately from the containers. +On the TUI main page, click **Start All Services** to start the OpenRAG containers and launch OpenRAG itself. -To start or stop `docling serve` or any other native services, in the TUI Status menu, click **Stop** or **Restart**. +When you start all services, the following processes happen: -To view the status, port, or PID of a native service, in the TUI main menu, click [Status](#status). +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`. ## Upgrade OpenRAG {#upgrade} -To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers using the OpenRAG TUI. +To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers. -Upgrading the OpenRAG Python package updates the TUI and Python code, but container versions are controlled separately by environment variables in your `.env` file. +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. -### Upgrade OpenRAG python package +1. Stop your OpenRAG containers: In the OpenRAG TUI, go to the **Status** menu, and then click **Stop Services**. -Use the following steps to upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/). -After upgrading the Python package, you should also [upgrade your OpenRAG containers](#upgrade-openrag-containers-with-the-tui). +2. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/). - - + + - If you installed OpenRAG using the [automatic installer](#install) or [uvx](#install), follow these steps to upgrade: + 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 - ``` + + ```bash + cd openrag-workspace + ``` 2. Upgrade the OpenRAG package: - ```bash - uvx --from openrag openrag - ``` - - To upgrade to a specific version: - ```bash - uvx --from openrag==0.1.33 openrag - ``` - 3. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui). + ```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 - ``` + + ```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 - ``` + + ```bash + uv add --upgrade openrag + ``` + + To upgrade to a specific version: + + ```bash + uv add --upgrade openrag==0.1.33 + ``` 3. Start the OpenRAG TUI: - ```bash - uv run openrag - ``` - 4. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui). + ```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 - ``` + + ```bash + uv pip install --upgrade openrag + ``` + + To upgrade to a specific version: + + ```bash + uv pip install --upgrade openrag==0.1.33 + ``` 3. Start the OpenRAG TUI: - ```bash - uv run openrag - ``` - 4. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui). + ```bash + uv run openrag + ``` - - + + -### Upgrade OpenRAG containers with the TUI {#upgrade-openrag-containers-with-the-tui} +3. Start the upgraded OpenRAG containers: In the OpenRAG TUI, click **Start All Services**, and then wait while the containers start. -After upgrading the OpenRAG Python package, upgrade your containers to ensure they match the `latest` version. -**Upgrade** runs `docker compose pull`, which pulls container images based on versions specified in your `.env` file. -`OPENRAG_VERSION` is set to `latest` by default, so it pulls the `latest` available container images. + 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`. -1. In the OpenRAG TUI, click **Status**, and then click **Upgrade**. -2. When the upgrade completes, close the **Status** window and continue using OpenRAG. + 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`. -If you encounter a `langflow container already exists` error during upgrade, see [Langflow container already exists during upgrade](/support/troubleshoot#langflow-container-already-exists-during-upgrade) in the troubleshooting guide. + 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. -To pin container versions to a specific release other than `latest`, set the `OPENRAG_VERSION` in your `.env` file: -```bash -OPENRAG_VERSION=0.1.33 -``` + 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). -For more information, see [System settings environment variables](/reference/configuration#system-settings). - -## Diagnostics - -The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. +3. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG. ## Reinstall OpenRAG {#reinstall} To reinstall OpenRAG with a completely fresh setup: -1. Reset your containers using the **Reset** button in the [TUI status](#status) menu. - This removes all containers, volumes, and data. +1. In the TUI **Status** menu, [reset your containers](#reset-containers) to destroy the existing OpenRAG containers and their data. 2. Optional: Delete your project's `.env` file. - The Reset operation doesn't remove your project's `.env` file, so your passwords, API keys, and OAuth settings can be preserved. - If you delete the `.env` file, run the [Set up OpenRAG with the TUI](#setup) process again to create a new configuration. -3. In the TUI Setup menu, follow these steps from [Basic Setup](#setup): - 1. Click **Start All Services** to pull container images and start them. - 2. Under **Native Services**, click **Start** to start the Docling service. - 3. Click **Open App** to open the OpenRAG application. - 4. Continue with [application onboarding](#application-onboarding). \ No newline at end of file + The Reset operation doesn't remove your project's `.env` file, so your passwords, API keys, and OAuth settings can be preserved. + If you delete the `.env` file, you must run the [Set up OpenRAG with the TUI](#setup) process again to create a new configuration file. + +3. Optional: Delete your OpenSearch knowledge base by deleting the contents of the `./opensearch-data` folder in your OpenRAG installation directory. + +3. In the TUI **Setup** menu, repeat the [Basic Setup](#setup) process: + + 1. Click **Start All Services** to pull container images and start them. + 2. Under **Native Services**, click **Start** to start the Docling service. + 3. Click **Open App** to open the OpenRAG application. + 4. Continue with [application onboarding](#application-onboarding). + +If reinstalling OpenRAG and deleting the `.env` file doesn't reset setup or onboarding, see [Reinstalling OpenRAG doesn't reset onboarding](/support/troubleshoot#reinstalling-openrag-doesnt-reset-onboarding). diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx index 5a0e09c8..f8b227bd 100644 --- a/docs/docs/get-started/quickstart.mdx +++ b/docs/docs/get-started/quickstart.mdx @@ -159,7 +159,7 @@ 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 with your preferred configuration because some settings are immutable after initial setup. +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). * **Learn more about OpenRAG**: Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality. diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx index c573958e..97d71a2c 100644 --- a/docs/docs/reference/configuration.mdx +++ b/docs/docs/reference/configuration.mdx @@ -149,11 +149,11 @@ Configure general system components, session management, and logging. |----------|---------|-------------| | `LANGFLOW_KEY_RETRIES` | `15` | Number of retries for Langflow key generation. | | `LANGFLOW_KEY_RETRY_DELAY` | `2.0` | Delay between retries in seconds. | -| `LANGFLOW_VERSION` | `latest` | Langflow Docker image version. | +| `LANGFLOW_VERSION` | `OPENRAG_VERSION` | Langflow Docker image version. By default, OpenRAG uses the `OPENRAG_VERSION` for the Langflow Docker image version. | | `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` | OpenRAG Docker image version. | +| `OPENRAG_VERSION` | `latest` | The version of the OpenRAG Docker images to run. For more information, see [Upgrade OpenRAG](/install#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 4f04a281..4a97be09 100644 --- a/docs/docs/support/troubleshoot.mdx +++ b/docs/docs/support/troubleshoot.mdx @@ -124,8 +124,8 @@ If reinstalling the Langflow container doesn't resolve the issue, you must reset Then, you can retry the upgrade. :::warning -This is a destructive operation that completely resets your OpenRAG containers and removes all OpenRAG data, including OpenSearch data, uploaded documents, and authentication details. -Your `.env` file is preserved, so your configuration settings remain intact, but all other data is lost. +This is a destructive operation that destroys your OpenRAG containers and their contents. +However, your `.env` file (configuration settings) and `./opensearch-data` (OpenSearch knowledge base) are preserved. ::: To reset your installation, stop your containers, and then completely remove them. @@ -212,6 +212,15 @@ After removing the containers, retry the upgrade in the OpenRAG TUI by clicking +## Reinstalling OpenRAG doesn't reset onboarding {#reinstalling-openrag-doesnt-reset-onboarding} + +If you [reinstall OpenRAG](/install#reinstall), you can restore your installation to it's original, default state by resetting the containers _and_ deleting the `.env` file. + +When you start OpenRAG after doing this, you should be prompted to go through the initial setup and onboarding process again. + +Due to a known issue, the onboarding process might not reset when you reinstall OpenRAG. +If this occurs, [install OpenRAG in a new Python project directory](/install#install) (with `uv init` and `uv add openrag`). + ## Document ingestion or similarity search issues See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion). \ No newline at end of file