gmakstutis/openrag
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

Merge pull request #565 from langflow-ai/issue-552-known-01-dec-25

Browse source 
Docs: Modifications to the descriptions of upgrade and reinstall behaviors
This commit is contained in:
April I. Murphy 2025-12-02 07:58:24 -08:00 • committed by GitHub
commit ef2014f82e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 131 additions and 113 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

225
docs/docs/get-started/install.mdx
View file

@ -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. 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 **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.
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
```
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. 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. 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 <kbd>l</kbd>. * **Logs**: To view streaming logs, select the container you want to view, and press <kbd>l</kbd>.
To copy your logs, click **Copy to Clipboard**. To copy the logs, click **Copy to Clipboard**.
To **upgrade** your containers, click **Upgrade**. * **Upgrade**: Check for updates. For more information, see [upgrade OpenRAG](#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).
To **reset** your containers, click **Reset**. * **Reset**: This is a destructive action that [resets your containers](#reset-containers).
Reset gives you a completely fresh start.
Reset deletes all of your data, including OpenSearch data, uploaded documents, and authentication. * **Native services**: From the **Status** menu, you can view the status, port, and process ID (PID) of the OpenRAG native services.
**Reset** runs two commands. You can also click **Stop** or **Restart** to stop and start OpenRAG native services.
It first stops and removes all containers, volumes, and local images.
``` 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 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`.
``` If you reset your containers as part of reinstalling OpenRAG, continue the [reinstallation process](#reinstall) after resetting the containers.
docker system prune -f
```
### 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. On the TUI main page, click **Start All Services** to start the OpenRAG containers and launch OpenRAG itself.
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.
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} ## 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/). 2. 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).
<Tabs groupId="Installation method"> <Tabs groupId="Installation method">
<TabItem value="installer" label="Automatic installer / uvx" default> <TabItem value="installer" label="Automatic installer or uvx" default>
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: 1. Navigate to your OpenRAG workspace directory:
```bash
cd openrag-workspace ```bash
``` cd openrag-workspace
```
2. Upgrade the OpenRAG package: 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
```
</TabItem> To upgrade to a specific version:
<TabItem value="uv-add" label="Python project with uv add">
```bash
uvx --from openrag==0.1.33 openrag
```
</TabItem>
<TabItem value="uv-add" label="Python project (uv add)">
Use these steps to upgrade the Python package if you installed OpenRAG in a Python project with `uv add`:
1. Navigate to your project directory: 1. Navigate to your project directory:
```bash
cd YOUR_PROJECT_NAME ```bash
``` cd YOUR_PROJECT_NAME
```
2. Update OpenRAG to the latest version: 2. Update OpenRAG to the latest version:
```bash
uv add --upgrade openrag ```bash
``` uv add --upgrade openrag
```
To upgrade to a specific version:
```bash To upgrade to a specific version:
uv add --upgrade openrag==0.1.33
``` ```bash
uv add --upgrade openrag==0.1.33
```
3. Start the OpenRAG TUI: 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
```
</TabItem> </TabItem>
<TabItem value="uv-pip" label="Existing virtual environment with uv pip install"> <TabItem value="uv-pip" label="Virtual environment (uv pip install)">
Use these steps to upgrade the Python package if you installed OpenRAG in a venv with `uv pip install`:
1. Activate your virtual environment. 1. Activate your virtual environment.
2. Upgrade OpenRAG: 2. Upgrade OpenRAG:
```bash
uv pip install --upgrade openrag ```bash
``` uv pip install --upgrade openrag
```
To upgrade to a specific version:
```bash To upgrade to a specific version:
uv pip install --upgrade openrag==0.1.33
``` ```bash
uv pip install --upgrade openrag==0.1.33
```
3. Start the OpenRAG TUI: 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
```
</TabItem> </TabItem>
</Tabs> </Tabs>
### 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. 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`.
**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**. 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.
2. When the upgrade completes, close the **Status** window and continue using OpenRAG. 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: 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).
```bash
OPENRAG_VERSION=0.1.33
```
For more information, see [System settings environment variables](/reference/configuration#system-settings). 3. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
## Diagnostics
The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.
## Reinstall OpenRAG {#reinstall} ## Reinstall OpenRAG {#reinstall}
To reinstall OpenRAG with a completely fresh setup: To reinstall OpenRAG with a completely fresh setup:
1. Reset your containers using the **Reset** button in the [TUI status](#status) menu. 1. In the TUI **Status** menu, [reset your containers](#reset-containers) to destroy the existing OpenRAG containers and their data.
This removes all containers, volumes, and data.
2. Optional: Delete your project's `.env` file. 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): The Reset operation doesn't remove your project's `.env` file, so your passwords, API keys, and OAuth settings can be preserved.
1. Click **Start All Services** to pull container images and start them. 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.
2. Under **Native Services**, click **Start** to start the Docling service.
3. Click **Open App** to open the OpenRAG application. 3. Optional: Delete your OpenSearch knowledge base by deleting the contents of the `./opensearch-data` folder in your OpenRAG installation directory.
4. Continue with [application onboarding](#application-onboarding).
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).

2
docs/docs/get-started/quickstart.mdx
View file

@ -159,7 +159,7 @@ You can send and receive requests with the Langflow API using Python, TypeScript
## Next steps ## Next steps
* **Reinstall OpenRAG with your preferred settings**: This quickstart used a minimal setup to demonstrate OpenRAG's core functionality. * **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). 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. * **Learn more about OpenRAG**: Explore OpenRAG and the OpenRAG documentation to learn more about its features and functionality.

4
docs/docs/reference/configuration.mdx
View file

@ -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_RETRIES` | `15` | Number of retries for Langflow key generation. |
| `LANGFLOW_KEY_RETRY_DELAY` | `2.0` | Delay between retries in seconds. | | `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_FORMAT` | Disabled | Set to `json` to enabled JSON-formatted log output. |
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR). | | `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR). |
| `MAX_WORKERS` | `1` | Maximum number of workers for document processing. | | `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. | | `SERVICE_NAME` | `openrag` | Service name for logging. |
| `SESSION_SECRET` | Automatically generated | Session management. | | `SESSION_SECRET` | Automatically generated | Session management. |

13
docs/docs/support/troubleshoot.mdx
View file

@ -124,8 +124,8 @@ If reinstalling the Langflow container doesn't resolve the issue, you must reset
Then, you can retry the upgrade. Then, you can retry the upgrade.
:::warning :::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. This is a destructive operation that destroys your OpenRAG containers and their contents.
Your `.env` file is preserved, so your configuration settings remain intact, but all other data is lost. 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. 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
</TabItem> </TabItem>
</Tabs> </Tabs>
## 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 ## Document ingestion or similarity search issues
See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion). See [Troubleshoot ingestion](/ingestion#troubleshoot-ingestion).