diff --git a/docs/docs/core-components/chat.mdx b/docs/docs/core-components/chat.mdx
index 728f3fb6..996dcc8d 100644
--- a/docs/docs/core-components/chat.mdx
+++ b/docs/docs/core-components/chat.mdx
@@ -11,15 +11,23 @@ import PartialTempKnowledge from '@site/docs/_partial-temp-knowledge.mdx';
After you [upload documents to your knowledge base](/ingestion), you can use the OpenRAG **Chat** feature to interact with your knowledge through natural language queries.
+The OpenRAG **Chat** uses an LLM-powered agent to understand your queries, retrieve relevant information from your knowledge base, and generate context-aware responses.
+The agent can also fetch information from URLs and new documents that you provide during the chat session.
+To limit the knowledge available to the agent, use [filters](/knowledge-filters).
+
+The agent can call specialized Model Context Protocol (MCP) tools to extend its capabilities.
+To add or change the available tools, you must edit the [**OpenRAG OpenSearch Agent** flow](#flow).
+
:::tip
Try chatting, uploading documents, and modifying chat settings in the [quickstart](/quickstart).
:::
## OpenRAG OpenSearch Agent flow {#flow}
-When you use the OpenRAG **Chat**, the **OpenRAG OpenSearch Agent** [flow](/agents) runs in the background to retrieve relevant information from your knowledge base and generate a response.
+When you use the OpenRAG **Chat**, the **OpenRAG OpenSearch Agent** flow runs in the background to retrieve relevant information from your knowledge base and generate a response.
If you [inspect the flow in Langflow](/agents#inspect-and-modify-flows), you'll see that it is comprised of eight components that work together to ingest chat messages, retrieve relevant information from your knowledge base, and then generate responses.
+When you inspect this flow, you can edit the components to customize the agent's behavior.
@@ -49,7 +57,7 @@ One or more specialized tools can be attached to the **Tools** port to extend th
Different models can change the style and content of the agent's responses, and some models might be better suited for certain tasks than others. If the agent doesn't seem to be handling requests well, try changing the model to see how the responses change. For example, fast models might be good for simple queries, but they might not have the depth of reasoning for complex, multi-faceted queries.
-* [**MCP Tools** component](https://docs.langflow.org/mcp-client): Connected to the **Agent** component's **Tools** port, this component can be used to [access any Model Context Protocol (MCP) server](https://docs.langflow.org/mcp-server) and the MCP tools provided by that server. In this case, your OpenRAG Langflow instance's [**Starter Project**](https://docs.langflow.org/concepts-flows#projects) is the MCP server, and the [**OpenSearch URL Ingestion** flow](/ingestion#url-flow) is the MCP tool.
+* [**MCP Tools** component](https://docs.langflow.org/mcp-client): Connected to the **Agent** component's **Tools** port, this component can be used to [access any MCP server](https://docs.langflow.org/mcp-server) and the MCP tools provided by that server. In this case, your OpenRAG Langflow instance's [**Starter Project**](https://docs.langflow.org/concepts-flows#projects) is the MCP server, and the [**OpenSearch URL Ingestion** flow](/ingestion#url-flow) is the MCP tool.
This flow fetches content from URLs, and then stores the content in your OpenRAG OpenSearch knowledge base. By serving this flow as an MCP tool, the agent can selectively call this tool if a URL is detected in the chat input.
* [**OpenSearch** component](https://docs.langflow.org/bundles-elastic#opensearch): Connected to the **Agent** component's **Tools** port, this component lets the agent search your [OpenRAG OpenSearch knowledge base](/knowledge). The agent might not use this database for every request; the agent uses this connection only if it decides that documents in your knowledge base are relevant to your query.
diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx
index a745be0c..3e991176 100644
--- a/docs/docs/core-components/ingestion.mdx
+++ b/docs/docs/core-components/ingestion.mdx
@@ -267,7 +267,7 @@ If an ingestion task fails, do the following:
* Split excessively large files into smaller files before uploading.
* Remove unusual embedded content, such as videos or animations, before uploading. Although Docling can replace some non-text content with placeholders during ingestion, some embedded content might cause errors.
-If the OpenRAG **Chat** doesn't seem to use your documents correctly, [browse your knowledge base](#browse-knowledge) to confirm that the documents are uploaded in full, and the chunks are correct.
+If the OpenRAG **Chat** doesn't seem to use your documents correctly, [browse your knowledge base](/knowledge#browse-knowledge) to confirm that the documents are uploaded in full, and the chunks are correct.
If the documents are present and well-formed, check your [knowledge filters](/knowledge-filters).
If a global filter is applied, make sure the expected documents are included in the global filter.
diff --git a/docs/docs/core-components/knowledge-filters.mdx b/docs/docs/core-components/knowledge-filters.mdx
index 8376a55b..7821f814 100644
--- a/docs/docs/core-components/knowledge-filters.mdx
+++ b/docs/docs/core-components/knowledge-filters.mdx
@@ -14,6 +14,16 @@ Each knowledge filter captures a specific subset of documents based on given a s
Knowledge filters can be used with different OpenRAG functionality.
For example, knowledge filters can help agents access large knowledge bases efficiently by narrowing the scope of documents that you want the agent to use.
+## Built-in filters
+
+When you install OpenRAG, it automatically creates an **OpenRAG docs** filter that includes OpenRAG's default documents.
+These documents provide information about OpenRAG itself and help you learn how to use OpenRAG.
+
+When you use the OpenRAG **Chat**, [apply the **OpenRAG docs** filter](#apply-a-filter) if you want to ask questions about OpenRAG's features and functionality.
+This limits the agent's context to the default OpenRAG documentation rather than all documents in your knowledge base.
+
+After uploading your own documents, it is recommended that you create your own filters to organize your documents effectively and separate them from the default OpenRAG documents.
+
## Create a filter
To create a knowledge filter, do the following:
diff --git a/docs/docs/core-components/knowledge.mdx b/docs/docs/core-components/knowledge.mdx
index d299aab1..3edf5a55 100644
--- a/docs/docs/core-components/knowledge.mdx
+++ b/docs/docs/core-components/knowledge.mdx
@@ -26,7 +26,7 @@ The **Knowledge** page lists the documents OpenRAG has ingested into your OpenSe
To explore the raw contents of your knowledge base, click **Knowledge** to get a list of all ingested documents.
Click a document to view the chunks produced from splitting the document during ingestion.
-OpenRAG includes some initial documents about OpenRAG. You can use these documents to ask OpenRAG about itself, and to test the [**Chat**](/chat) feature before uploading your own documents.
+By default, OpenRAG includes some initial documents about OpenRAG. You can use these documents to ask OpenRAG about itself, and to test the [**Chat**](/chat) feature before uploading your own documents.
If you [delete these documents](#delete-knowledge), you won't be able to ask OpenRAG about itself and it's own functionality.
It is recommended that you keep these documents, and use [filters](/knowledge-filters) to separate them from your other knowledge.
diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx
index c78bc64d..64555bbb 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 da513712..789f12c8 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.
@@ -430,26 +447,23 @@ This is a two part process because upgrading the OpenRAG Python package updates
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).
-3. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
+4. 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:
+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).
-
-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).
+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 4a97be09..546bddf2 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -85,141 +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
- ```
-
-
-
-
-## 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`).
+4. Retry the upgrade.
## Document ingestion or similarity search issues