From 2aecfc570c1c2408f329bea18cafcd9fb868c0d5 Mon Sep 17 00:00:00 2001
From: Mendon Kissling <59585235+mendonk@users.noreply.github.com>
Date: Thu, 6 Nov 2025 18:05:26 -0500
Subject: [PATCH 1/2] docs: updates from qa (#360)
* numbering
* startup-from-main-menu-and-localhost
* wsl-browser-error
* open-localhost-alternate
* tasks-menu
* Apply suggestions from code review
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
---------
Co-authored-by: April I. Murphy <36110273+aimurphy@users.noreply.github.com>
---
docs/VERSIONING_SETUP.md | 6 +++---
docs/docs/core-components/knowledge.mdx | 13 +++++++++++++
docs/docs/get-started/install.mdx | 8 +++++---
docs/docs/support/troubleshoot.mdx | 8 ++++++++
4 files changed, 29 insertions(+), 6 deletions(-)
diff --git a/docs/VERSIONING_SETUP.md b/docs/VERSIONING_SETUP.md
index 17a8c8f6..1b4f19f3 100644
--- a/docs/VERSIONING_SETUP.md
+++ b/docs/VERSIONING_SETUP.md
@@ -39,7 +39,7 @@ This command will:
- Create a versioned sidebar file at `versioned_sidebars/version-1.0.0-sidebars.json`
- Append the new version to `versions.json`
-3. After creating a version, update the Docusaurus configuration to include multiple versions.
+2. After creating a version, update the Docusaurus configuration to include multiple versions.
`lastVersion:'1.0.0'` makes the '1.0.0' release the `latest` version.
`current` is the work-in-progress docset, accessible at `/docs/next`.
To remove a version, remove it from `onlyIncludeVersions`.
@@ -62,14 +62,14 @@ docs: {
},
```
-4. Test the deployment locally.
+3. Test the deployment locally.
```bash
npm run build
npm run serve
```
-5. To add subsequent versions, repeat the process, first running the CLI command then updating `docusaurus.config.js`.
+4. To add subsequent versions, repeat the process, first running the CLI command then updating `docusaurus.config.js`.
```bash
# Create version 2.0.0 from current docs
diff --git a/docs/docs/core-components/knowledge.mdx b/docs/docs/core-components/knowledge.mdx
index 588f1f45..2e63198e 100644
--- a/docs/docs/core-components/knowledge.mdx
+++ b/docs/docs/core-components/knowledge.mdx
@@ -86,6 +86,19 @@ You can select multiple files.
The ingestion process may take some time, depending on the size of your documents.
4. When ingestion is complete, your documents are available in the Knowledge screen.
+If ingestion fails, click **Status** to view the logged error.
+
+## Monitor ingestion tasks
+
+When you upload files, process folders, or sync documents, OpenRAG processes them as background tasks.
+A badge appears on the **Tasks** icon when there are active tasks running.
+To open the Tasks menu, click **Tasks**.
+
+**Active Tasks** shows tasks that are currently processing.
+A **Pending** task is queued and waiting to start, a **Running** task is actively processing files, and a **Processing** task is performing ingestion operations. For each active task, you can find the task ID, start time, duration, the number of files processed so far, and the total files.
+
+You can cancel active tasks by clicking **Cancel**. Canceling a task stops processing immediately and marks the task as failed.
+
## Explore knowledge
The **Knowledge** page lists the documents OpenRAG has ingested into the OpenSearch vector database's `documents` index.
diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx
index c52b6ec3..ea4b4d46 100644
--- a/docs/docs/get-started/install.mdx
+++ b/docs/docs/get-started/install.mdx
@@ -19,7 +19,7 @@ Once OpenRAG is running, use the TUI to monitor your application, control your c
If you prefer running Podman or Docker containers and manually editing `.env` files, see [Install OpenRAG Containers](/get-started/docker).
-## Prerequisites
+## Prerequisites
- Install [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/)
- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
@@ -185,7 +185,8 @@ If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path.
Command completed successfully
```
6. To start the Docling service, under **Native Services**, click **Start**.
- 7. To open the OpenRAG application, click **Open App**.
+ 7. To open the OpenRAG application, navigate to the TUI main menu, and then click **Open App**.
+ Alternatively, in your browser, navigate to `localhost:3000`.
8. Continue with [Application Onboarding](#application-onboarding).
@@ -212,7 +213,8 @@ If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path.
Command completed successfully
```
8. To start the Docling service, under **Native Services**, click **Start**.
- 9. To open the OpenRAG application, click **Open App**.
+ 9. To open the OpenRAG application, navigate to the TUI main menu, and then click **Open App**.
+ Alternatively, in your browser, navigate to `localhost:3000`.
You are presented with your provider's OAuth sign-in screen.
After sign-in, you are redirected to the redirect URI.
diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx
index 67b927e0..158eafa4 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -13,6 +13,14 @@ This page provides troubleshooting advice for issues you might encounter when us
Check that `OPENSEARCH_PASSWORD` set in [Environment variables](/reference/configuration) meets requirements.
The password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong.
+## OpenRAG fails to start from the TUI with "Operation not supported" error
+
+This error occurs when starting OpenRAG with the TUI in [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install).
+
+The error occurs because OpenRAG is running within a WSL environment, so `webbrowser.open()` can't launch a browser automatically.
+
+To access the OpenRAG application, open a web browser and enter `http://localhost:3000` in the address bar.
+
## Langflow connection issues
Verify the `LANGFLOW_SUPERUSER` credentials set in [Environment variables](/reference/configuration) are correct.
From 7e343ed1f2b4d9a35340e7282f3d9283af9c70c1 Mon Sep 17 00:00:00 2001
From: Cole Goldsmith
Date: Fri, 7 Nov 2025 11:49:57 -0600
Subject: [PATCH 2/2] Fix provider health banner showing during onboarding
(#372)
* disable provider health query until edited is true, set initial provider health cache to true when onboarding mutation succeeds
* fix scroll issue with model selector in dialog
---
frontend/components/provider-health-banner.tsx | 13 ++++++++++++-
.../app/api/mutations/useUpdateSettingsMutation.ts | 3 +++
.../src/app/api/queries/useProviderHealthQuery.ts | 11 ++++-------
.../app/onboarding/components/model-selector.tsx | 10 +++++++---
.../app/onboarding/components/onboarding-card.tsx | 11 +++++++++++
5 files changed, 37 insertions(+), 11 deletions(-)
diff --git a/frontend/components/provider-health-banner.tsx b/frontend/components/provider-health-banner.tsx
index 0782e7f9..aa98b197 100644
--- a/frontend/components/provider-health-banner.tsx
+++ b/frontend/components/provider-health-banner.tsx
@@ -7,6 +7,7 @@ import { useProviderHealthQuery } from "@/src/app/api/queries/useProviderHealthQ
import { Button } from "./ui/button";
import { useRouter } from "next/navigation";
import { useGetSettingsQuery } from "@/app/api/queries/useGetSettingsQuery";
+import { ModelProvider } from "@/app/settings/helpers/model-helpers";
interface ProviderHealthBannerProps {
className?: string;
@@ -42,12 +43,22 @@ export function useProviderHealth() {
};
}
+const providerTitleMap: Record = {
+ openai: "OpenAI",
+ ollama: "Ollama",
+ watsonx: "IBM watsonx.ai",
+};
+
export function ProviderHealthBanner({ className }: ProviderHealthBannerProps) {
const { isLoading, isHealthy, isUnhealthy, health } = useProviderHealth();
const router = useRouter();
const { data: settings = {} } = useGetSettingsQuery();
+ const providerTitle =
+ providerTitleMap[settings.provider?.model_provider as ModelProvider] ||
+ "Provider";
+
// Only show banner when provider is unhealthy (not when backend is unavailable)
if (isLoading || isHealthy) {
return null;
@@ -71,7 +82,7 @@ export function ProviderHealthBanner({ className }: ProviderHealthBannerProps) {
icon={AlertTriangle}
/>
- {errorMessage}
+ {providerTitle} error - {errorMessage}