diff --git a/docs/docs/_partial-onboarding.mdx b/docs/docs/_partial-onboarding.mdx index 8c3d508a..be70e8bf 100644 --- a/docs/docs/_partial-onboarding.mdx +++ b/docs/docs/_partial-onboarding.mdx @@ -19,7 +19,21 @@ You can use different providers for your language model and embedding model, suc Choose one LLM provider and complete these steps: - + + :::info + Anthropic does not provide embedding models. If you select Anthropic for your language model, you must then select a different provider for embeddings. + ::: + 1. Enable **Use environment Anthropic API key** to automatically use your key from the `.env` file. + Alternatively, paste an Anthropic API key into the field. + 2. Under **Advanced settings**, select your **Language Model**. + 3. Click **Complete**. + 4. In the second onboarding panel, select a provider for embeddings and select your **Embedding Model**. + 5. To complete the onboarding tasks, click **What is OpenRAG**, and then click **Add a Document**. + Alternatively, click + 1. Enable **Get API key from environment variable** to automatically enter your key from the TUI-generated `.env` file. Alternatively, paste an OpenAI API key into the field. 2. Under **Advanced settings**, select your **Language Model**. @@ -40,20 +54,6 @@ Choose one LLM provider and complete these steps: Alternatively, click - - :::info - Anthropic does not provide embedding models. If you select Anthropic for your language model, you must then select a different provider for embeddings. - ::: - 1. Enable **Use environment Anthropic API key** to automatically use your key from the TUI-generated `.env` file. - Alternatively, paste an Anthropic API key into the field. - 2. Under **Advanced settings**, select your **Language Model**. - 3. Click **Complete**. - 4. In the second onboarding panel, select a provider for embeddings and select your **Embedding Model**. - 5. To complete the onboarding tasks, click **What is OpenRAG**, and then click **Add a Document**. - Alternatively, click :::tip diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index ec736ec8..4ee634bc 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -146,7 +146,7 @@ Choose an installation method based on your needs: 3. Run OpenRAG: ```bash - openrag + uv run openrag ``` @@ -268,8 +268,7 @@ To copy your logs, click **Copy to Clipboard**. To **upgrade** your containers, click **Upgrade**. **Upgrade** runs `docker compose pull` and then `docker compose up -d --force-recreate`. -The first command pulls the latest images of OpenRAG. -The second command recreates the containers with your data persisted. +For more information, see [Upgrade OpenRAG containers with the TUI](#upgrade-openrag-containers-with-the-tui). To **reset** your containers, click **Reset**. Reset gives you a completely fresh start. @@ -295,6 +294,107 @@ To start or stop `docling serve` or any other native services, in the TUI Status To view the status, port, or PID of a native service, in the TUI main menu, click [Status](#status). +## Upgrade OpenRAG {#upgrade} + +To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers using the OpenRAG TUI. + +Upgrading the OpenRAG Python package updates the TUI and Python code, but container versions are controlled separately by environment variables in your `.env` file. + +### Upgrade OpenRAG python package + +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). + + + + + If you installed OpenRAG using the [automatic installer](#install) or [uvx](#install), follow these steps to upgrade: + + 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 + ``` + + 3. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui). + + + + + 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 + ``` + + 4. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui). + + + + + 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 + ``` + + 4. After upgrading the Python package, [upgrade your containers](#upgrade-openrag-containers-with-the-tui). + + + + +### Upgrade OpenRAG containers with the TUI {#upgrade-openrag-containers-with-the-tui} + +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. + +1. In the OpenRAG TUI, click **Status**, and then click **Upgrade**. +2. When the upgrade completes, close the **Status** window and continue using OpenRAG. + +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. + +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 +``` + +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. diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx index 158eafa4..2613dcaa 100644 --- a/docs/docs/support/troubleshoot.mdx +++ b/docs/docs/support/troubleshoot.mdx @@ -66,19 +66,46 @@ On macOS, this cache directory is typically a user cache directory such as `/Use If you do not need OCR, you can disable OCR-based processing in your ingestion settings to avoid requiring `easyocr`. -## Langflow container already exists +## Langflow container already exists {#langflow-container-already-exists-during-upgrade} -If you are running other versions of Langflow containers on your machine, you may encounter an issue where Docker or Podman thinks Langflow is already up. +If you encounter a `langflow container already exists` error when upgrading OpenRAG, this typically means you upgraded OpenRAG with `uv`, but didn't remove or upgrade containers from a previous installation. -Remove just the problem container, or clean up all containers and start fresh. +1. Remove only the problematic Langflow container: -To reset your local containers and pull new images, do the following: + + + ```bash + # Stop the langflow container + podman stop langflow + + # Remove the langflow container + podman rm langflow --force + ``` + + + ```bash + # Stop the langflow container + docker stop langflow + + # Remove the langflow container + docker rm langflow --force + ``` + + + +2. After removing the container, retry the upgrade in the OpenRAG TUI by clicking **Status** > **Upgrade**. + +### Reinstall all containers + +If reinstalling the Langflow container doesn't resolve the issue, or if you want a completely fresh installation, remove all OpenRAG containers and data, and then retry the upgrade. +:::warning Data loss +The complete reset removes all your data, including OpenSearch data, uploaded documents, and authentication. Your `.env` file is preserved, so your configuration settings remain intact. +::: 1. Stop your containers and completely remove them. - - + ```bash # Stop all running containers podman stop --all @@ -98,10 +125,8 @@ To reset your local containers and pull new images, do the following: # Clean up any leftover data podman system prune --all --force --volumes ``` - - ```bash # Stop all running containers docker stop $(docker ps -q) @@ -121,16 +146,7 @@ To reset your local containers and pull new images, do the following: # Clean up any leftover data docker system prune --all --force --volumes ``` - - + -2. Restart OpenRAG and upgrade to get the latest images for your containers. - ```bash - uv sync - uv run openrag - ``` - -3. In the OpenRAG TUI, click **Status**, and then click **Upgrade**. -When the **Close** button is active, the upgrade is complete. -Close the window and open the OpenRAG appplication. \ No newline at end of file +2. After removing the containers, retry the upgrade in the OpenRAG TUI by clicking **Status** > **Upgrade**. \ No newline at end of file diff --git a/documents/openrag-documentation.pdf b/documents/openrag-documentation.pdf index 306c39d7..af4d1368 100644 Binary files a/documents/openrag-documentation.pdf and b/documents/openrag-documentation.pdf differ