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

known issue with reinstall

Browse source
This commit is contained in:
April M 2025-12-01 14:48:04 -08:00
parent 681a139a93
commit 3cfebf2cbb
3 changed files with 122 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -272,171 +272,172 @@ 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**: Use this option when you [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 deletes all of your OpenRAG container data, including OpenSearch data, uploaded documents, and customized flows.
:::
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. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
Use the following steps to upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/). <Tabs groupId="Installation method">
After upgrading the Python package, you should also [upgrade your OpenRAG containers](#upgrade-openrag-containers-with-the-tui). <TabItem value="installer" label="Automatic installer or uvx" default>
<Tabs groupId="Installation method"> Use these steps to upgrade the Python package if you installed OpenRAG using the automatic installer or `uvx`:
<TabItem value="installer" label="Automatic installer / uvx" default>
If you installed OpenRAG using the [automatic installer](#install) or [uvx](#install), follow these steps to upgrade:
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} 2. Upgrade the OpenRAG containers: In the OpenRAG TUI, click **Status**, click **Upgrade**, and then wait while the containers are upgraded.
After upgrading the OpenRAG Python package, upgrade your containers to ensure they match the `latest` version. **Upgrade** runs `docker compose pull` to get the container images based on the version specified in your `.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**. `OPENRAG_VERSION` 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, edit the `OPENRAG_VERSION` [environment variable](/reference/configuration#system-settings) in your OpenRAG `.env` file. For example, `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. 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).
To pin container versions to a specific release other than `latest`, set the `OPENRAG_VERSION` in your `.env` file: 3. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
```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.
## 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 does not 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 does not 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. In the TUI **Setup** menu, repeat the [Basic Setup](#setup) process:
4. Continue with [Application Onboarding](#application-onboarding).
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

@ -267,7 +267,7 @@ You could also pass the output from one flow as input to another flow.
## 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.

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

@ -210,4 +210,13 @@ 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`).