From eb2df96b49b0efac2a82271217460e15ca8538f7 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Tue, 2 Dec 2025 16:00:00 -0800 Subject: [PATCH] factory reset --- docs/docs/get-started/docker.mdx | 185 ++++++++++++++++++++++++++--- docs/docs/get-started/install.mdx | 70 ++++++----- docs/docs/support/troubleshoot.mdx | 140 +++++----------------- 3 files changed, 243 insertions(+), 152 deletions(-) diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index c78bc64d..8ed718af 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -174,7 +174,7 @@ uv run python scripts/docling_ctl.py stop 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. @@ -183,21 +183,176 @@ docker compose pull docker compose up -d --force-recreate ``` -### Rebuild containers (destructive) +### Reset containers (destructive) {#reset-containers} -Reset state by rebuilding all of your containers. -Your OpenSearch and Langflow databases will be lost. -Documents stored in the `./openrag-documents` directory will persist, since the directory is mounted as a volume in the OpenRAG backend container. +:::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. +::: -```bash -docker compose up --build --force-recreate --remove-orphans -``` + + -### Remove all containers and data (destructive) +* Rebuild containers: This command destroys and recreates the containers. Data stored exclusively on the containers is lost, such as Langflow flows. +The `.env` file, `config` directory, `./openrag-documents` directory, `./opensearch-data` directory, and the `conversations.json` file are preserved. -Completely remove your OpenRAG installation and delete all data. -This deletes all of your data, including OpenSearch data, uploaded documents, and authentication. -```bash -docker compose down --volumes --remove-orphans --rmi local -docker system prune -f -``` \ No newline at end of file + ```bash + docker compose up --build --force-recreate --remove-orphans + ``` + +* Destroy and recreate containers with the option for additional data removal: These commands destroy the containers, and then recreate them. +This allows you to delete other OpenRAG data before recreating the containers. + + 1. Destroy the containers, volumes, and local images, and then remove (prune) any additional Docker objects: + + ```bash + docker compose down --volumes --remove-orphans --rmi local + docker system prune -f + ``` + + 2. Optional: Remove data that wasn't deleted by the previous commands: + + * OpenRAG's `.env` file + * The contents of OpenRAG's `config` directory + * The contents of the `./openrag-documents` directory + * The contents of the `./opensearch-data` directory + * The `conversations.json` file + + 3. Recreate the containers: + + ```bash + docker compose up -d + ``` + + + + +* Rebuild containers: This command destroys and recreates the containers. Data stored exclusively on the containers is lost, such as Langflow flows. +The `.env` file, `config` directory, `./openrag-documents` directory, `./opensearch-data` directory, and the `conversations.json` file are preserved. + + ```bash + podman-compose up --build --force-recreate --remove-orphans + ``` + +* Destroy and recreate containers with the option for additional data removal: These commands destroy the containers, and then recreate them. +This allows you to delete other OpenRAG data before recreating the containers. + + 1. Destroy the containers, volumes, and local images, and then remove (prune) any additional Podman objects: + + ```bash + podman-compose down --volumes --remove-orphans --rmi local + podman system prune -f + ``` + + 2. Optional: Remove data that wasn't deleted by the previous commands: + + * OpenRAG's `.env` file + * The contents of OpenRAG's `config` directory + * The contents of the `./openrag-documents` directory + * The contents of the `./opensearch-data` directory + * The `conversations.json` file + + 3. Recreate the containers: + + ```bash + podman-compose up -d + ``` + + + + +1. Stop all running containers: + + ```bash + docker stop $(docker ps -q) + ``` + +2. Remove all containers, including stopped containers: + + ```bash + docker rm --force $(docker ps -aq) + ``` + +3. Remove all images: + + ```bash + docker rmi --force $(docker images -q) + ``` + +4. Remove all volumes: + + ```bash + docker volume prune --force + ``` + +5. Remove all networks except the default network: + + ```bash + docker network prune --force + ``` + +6. Clean up any leftover data: + + ```bash + docker system prune --all --force --volumes + ``` + +7. Optional: Remove data that wasn't deleted by the previous commands: + + * OpenRAG's `.env` file + * The contents of OpenRAG's `config` directory + * The contents of the `./openrag-documents` directory + * The contents of the `./opensearch-data` directory + * The `conversations.json` file + + + + +1. Stop all running containers: + + ```bash + podman stop --all + ``` + +2. Remove all containers, including stopped containers: + + ```bash + podman rm --all --force + ``` + +3. Remove all images: + + ```bash + podman rmi --all --force + ``` + +4. Remove all volumes: + + ```bash + podman volume prune --force + ``` + +5. Remove all networks except the default network: + + ```bash + podman network prune --force + ``` + +6. Clean up any leftover data: + + ```bash + podman system prune --all --force --volumes + ``` + +7. Optional: Remove data that wasn't deleted by the previous commands: + + * OpenRAG's `.env` file + * The contents of OpenRAG's `config` directory + * The contents of the `./openrag-documents` directory + * The contents of the `./opensearch-data` directory + * The `conversations.json` file + + + + +After resetting your containers, you must repeat [application onboarding](#application-onboarding). \ No newline at end of file diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 221da12f..9d0613cb 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -290,34 +290,44 @@ To copy the logs, click **Copy to Clipboard**. * **Upgrade**: Check for updates. For more information, see [upgrade OpenRAG](#upgrade). -* **Reset**: This is a destructive action that [resets your containers](#reset-containers). +* **Factory 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. +* **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 and recreates all of your OpenRAG containers. +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. ::: -To destroy and recreate your OpenRAG containers, go to the TUI [**Status** menu](#status), and then click **Reset**. +1. To destroy and recreate your OpenRAG containers, go to the TUI [**Status** menu](#status), and then click **Factory Reset**. -The **Reset** function runs two commands. First, it stops and removes all containers, volumes, and local images: + 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 -``` + ```bash + docker compose down --volumes --remove-orphans --rmi local + docker system prune -f + ``` -Then, it removes any additional Docker objects with `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. -If you reset your containers as part of reinstalling OpenRAG, continue the [reinstallation process](#reinstall) after resetting the containers. +### Start all services {#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. -On the TUI main page, click **Start All Services** to start the OpenRAG containers and launch OpenRAG itself. +#### 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: @@ -327,6 +337,13 @@ When you start all services, the following processes happen: 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. + ## Upgrade OpenRAG {#upgrade} To upgrade OpenRAG, upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers. @@ -434,20 +451,19 @@ This is a two part process because upgrading the OpenRAG Python package updates ## Reinstall OpenRAG {#reinstall} -To reinstall OpenRAG with a completely fresh setup: +Reset your OpenRAG deployment by recreating the containers and, optionally, removing related data: -1. In the TUI **Status** menu, [reset your containers](#reset-containers) to destroy the existing OpenRAG containers and their data. +1. In the TUI, [reset your containers](#reset-containers) to destroy the following: -2. Optional: Delete your project's `.env` file. + * 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 - 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. +2. Optional: Remove data that wasn't deleted by the **Factory Reset** operation. For a completely fresh installation, delete all of this data. -3. Optional: Delete your OpenSearch knowledge base by deleting the contents of the `./opensearch-data` folder in your OpenRAG installation directory. + * **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 [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). \ No newline at end of file +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 diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx index 92a79e9c..546bddf2 100644 --- a/docs/docs/support/troubleshoot.mdx +++ b/docs/docs/support/troubleshoot.mdx @@ -85,132 +85,52 @@ If you encounter a `langflow container already exists` error when upgrading Open To resolve this issue, do the following: -First, try removing only the Langflow container, and then retry the upgrade in the OpenRAG TUI by clicking **Status** and then **Upgrade**. +1. Remove only the Langflow container: - - + + -1. Stop the Langflow container: + 1. Stop the Langflow container: - ```bash - podman stop langflow - ``` + ```bash + podman stop langflow + ``` -2. Remove the Langflow container: + 2. Remove the Langflow container: - ```bash - podman rm langflow --force - ``` + ```bash + podman rm langflow --force + ``` - - + + -1. Stop the Langflow container: + 1. Stop the Langflow container: - ```bash - docker stop langflow - ``` + ```bash + docker stop langflow + ``` -2. Remove the Langflow container: + 2. Remove the Langflow container: - ```bash - docker rm langflow --force - ``` + ```bash + docker rm langflow --force + ``` - - + + -If reinstalling the Langflow container doesn't resolve the issue, you must reset to a fresh installation by removing all OpenRAG containers and data. -Then, you can retry the upgrade. +2. Retry the upgrade: -:::warning -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. -::: + * [Upgrade self-managed containers](/docker#upgrade-containers) + * [Upgrade TUI-managed containers](/install#upgrade-containers) -To reset your installation, stop your containers, and then completely remove them. -After removing the containers, retry the upgrade in the OpenRAG TUI by clicking **Status** and then **Upgrade**. +3. If reinstalling the Langflow container doesn't resolve the issue, you must reset your OpenRAG deployment: - - + * [Reset self-managed containers](/docker#reset-containers) + * [Reset TUI-managed containers](/install#reset-containers) -1. Stop all running containers: - - ```bash - podman stop --all - ``` - -2. Remove all containers, including stopped containers: - - ```bash - podman rm --all --force - ``` - -3. Remove all images: - - ```bash - podman rmi --all --force - ``` - -4. Remove all volumes: - - ```bash - podman volume prune --force - ``` - -5. Remove all networks except the default network: - - ```bash - podman network prune --force - ``` - -6. Clean up any leftover data: - - ```bash - podman system prune --all --force --volumes - ``` - - - - -1. Stop all running containers: - - ```bash - docker stop $(docker ps -q) - ``` - -2. Remove all containers, including stopped containers: - - ```bash - docker rm --force $(docker ps -aq) - ``` - -3. Remove all images: - - ```bash - docker rmi --force $(docker images -q) - ``` - -4. Remove all volumes: - - ```bash - docker volume prune --force - ``` - -5. Remove all networks except the default network: - - ```bash - docker network prune --force - ``` - -6. Clean up any leftover data: - - ```bash - docker system prune --all --force --volumes - ``` - - - +4. Retry the upgrade. ## Document ingestion or similarity search issues