Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

controls not available in cli-only

April M95b49ba4123a
diff --git a/docs/docs/_partial-setup.mdx b/docs/docs/_partial-setup.mdx
index 337570b9e..88d05ebf1 100644
--- a/docs/docs/_partial-setup.mdx
+++ b/docs/docs/_partial-setup.mdx
@@ -2,18 +2,20 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialOAuthCredentials from '@site/docs/_partial-oauth-credentials.mdx';
-1. In your OpenRAG terminal session, select the **Configure** option.
+The first time you install OpenRAG, the terminal session issues a series of prompts to guide you through the initial configuration.
-2. Enter an administrator password for the OpenSearch service.
+If OpenRAG detects an existing OpenRAG `.env` file, you might need to select the **Reconfigure** option in the terminal to access the configuration settings.
+
+1. Enter an administrator password for the OpenSearch service.
This password is required, and a secure password is automatically generated if you don't provide one manually.
-3. Enter an administrator password for the Langflow service.
+2. Enter an administrator password for the Langflow service.
This password is recommended but optional.
If the Langflow password is empty, the Langflow server starts without authentication enabled. For more information, see [Langflow settings](/reference/configuration#langflow-settings).
-4. At the **AI providers** prompt, you can either enter your model provider credentials now, or press <kbd>Enter</kbd> to configure these options later during application onboarding.
+3. At the **AI providers** prompt, you can either enter your model provider credentials now, or press <kbd>Enter</kbd> to configure these options later during application onboarding.
There is no material difference between providing these values now or during the [application onboarding process](#application-onboarding).
If you provide a credential now, it can be populated automatically during the application onboarding process if you enable the **Use environment API key** option.
@@ -22,16 +24,16 @@ import PartialOAuthCredentials from '@site/docs/_partial-oauth-credentials.mdx';
By default, OpenRAG uses OpenAI models.
If you aren't sure which models or providers to use, you must provide an OpenAI API key to use OpenRAG's default model configuration.
-5. At the **Langfuse tracing** prompt, enter <kbd>Y</kbd> to enable the [Langflow integration with Langfuse](https://docs.langflow.org/integrations-langfuse); otherwise, enter <kbd>N</kbd>.
+4. At the **Langfuse tracing** prompt, enter <kbd>Y</kbd> to enable the [Langflow integration with Langfuse](https://docs.langflow.org/integrations-langfuse); otherwise, enter <kbd>N</kbd>.
If you enter <kbd>Y</kbd>, provide the following Langfuse credentials:
* **Langfuse Secret Key**: A secret key for your Langfuse project.
* **Langfuse Public Key**: A public key for your Langfuse project.
* **Langfuse Host**: Required for self-hosted Langfuse deployments. Leave empty for Langfuse Cloud.
-6. At the **Documents path** prompt, accept the default [local documents path](/ingestion-configure#set-the-local-documents-path), or provide a path to a directory where you want OpenRAG to look for documents to ingest into your [knowledge base](/knowledge).
+5. At the **Documents path** prompt, accept the default [local documents path](/ingestion-configure#set-the-local-documents-path), or provide a path to a directory where you want OpenRAG to look for documents to ingest into your [knowledge base](/knowledge).
-7. At the **Cloud connectors and advanced settings** prompt, enter <kbd>Y</kbd> if you want to configure any of the following additional settings; otherwise, enter <kbd>N</kbd>.
+6. At the **Cloud connectors and advanced settings** prompt, enter <kbd>Y</kbd> if you want to configure any of the following additional settings; otherwise, enter <kbd>N</kbd>.
:::info
You must configure advanced settings if you want to enable either OAuth mode or cloud storage connectors during initial set up:
@@ -63,7 +65,7 @@ If you enter <kbd>Y</kbd>, provide the following Langfuse credentials:
* **Langflow Public URL** : Sets the base address to access the Langflow web interface where users interact with the Langflow editor in a browser. You must set this value if you want to run Langflow on a non-default port (`7860`)
-8. At the `Start services now?` prompt, press <kbd>Y</kbd> to start the OpenRAG services.
+7. At the `Start services now?` prompt, press <kbd>Y</kbd> to start the OpenRAG services.
This process can take some time while OpenRAG pulls and runs the container images.
If all services start successfully, the terminal prints a confirmation message:
@@ -77,7 +79,7 @@ If you enter <kbd>Y</kbd>, provide the following Langfuse credentials:
If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file.
:::
-9. Select the **Open OpenRAG in browser** option to launch the OpenRAG application and start the [application onboarding process](#application-onboarding).
+8. If the OpenRAG app doesn't launch automatically, select the **Open OpenRAG in browser** option to launch the OpenRAG app and start the [application onboarding process](#application-onboarding).
You can also manually navigate to `localhost:3000` in a browser.
If you provided Google OAuth credentials, you must sign in with Google before you are redirected to your OpenRAG instance.
\ No newline at end of file
diff --git a/docs/docs/core-components/knowledge-connectors.mdx b/docs/docs/core-components/knowledge-connectors.mdx
index ebde00bd3..52394aaf6 100644
--- a/docs/docs/core-components/knowledge-connectors.mdx
+++ b/docs/docs/core-components/knowledge-connectors.mdx
@@ -73,8 +73,8 @@ OpenRAG saves your OAuth credentials to your [OpenRAG `.env` file](/reference/co
9. At the `Start services now?` prompt, press <kbd>Y</kbd> to start the OpenRAG services with the new configuration.
-10. When you see the `Services are running` message, select the **Open OpenRAG in browser** option to launch the OpenRAG app.
-You can also manually navigate to `localhost:3000` in a browser
+10. When you see the `Services are running` message, select the **Open OpenRAG in browser** option to launch the OpenRAG app if the app doesn't launch automatically.
+You can also manually navigate to `localhost:3000` in a browser.
If you provided Google OAuth credentials, you must sign in with Google before you are redirected to your OpenRAG instance.
diff --git a/docs/docs/get-started/manage-services.mdx b/docs/docs/get-started/manage-services.mdx
index 70a17a3f0..b9446eba1 100644
--- a/docs/docs/get-started/manage-services.mdx
+++ b/docs/docs/get-started/manage-services.mdx
@@ -24,7 +24,11 @@ For [self-managed deployments](/docker), run Docker or Podman commands to manage
<Tabs>
<TabItem value="TUI" label="Terminal-managed services" default>
-In the terminal session, select the **Show status** option to access diagnostics and controls for all OpenRAG services, including container health, ports, image versions, and streaming logs.
+In the terminal session, select the **Show status** option to access information about all OpenRAG services, including container health, ports, and image versions.
+
+For more information and options, you must [start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui`.
+Then, click **Status** to access controls to stop, start, or restart individual services.
+To view streaming logs, click the name of a service, and then press <kbd>l</kbd>.
For the Docling native service, see [Stop, start, and inspect native services](#start-native-services).
@@ -43,9 +47,10 @@ For the Docling native service, see [Stop, start, and inspect native services](#
<Tabs>
<TabItem value="TUI" label="Terminal-managed services" default>
-In the terminal session, select the **Show status** option to stop, start, and restart OpenRAG's container-based services.
+In the terminal session, use the **Start services** and **Stop services** options to start or stop all OpenRAG services.
-You can also use the terminal's **Start services** option to start all services at once.
+For fine-grained controls, you must [start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui`.
+Then, click **Status** to access controls to stop, start, or restart individual services.
:::tip
A Docker or Podman VM must be running before you start OpenRAG.
@@ -65,7 +70,7 @@ When you restart or start services in the terminal session, the following proces
</details>
Alternatively, you can manually run the Docker/Podman commands to stop and start containers.
-Typically, this is only necessary if there is an error preventing the terminal session from managing the containers.
+Typically, this is only necessary if you don't want to use `--tui` or there is an error preventing the terminal session from managing the containers.
* Stop all containers: [`docker compose down`](https://docs.docker.com/reference/cli/docker/compose/down/) or `podman compose down`
* Start all containers: [`docker compose up -d`](https://docs.docker.com/reference/cli/docker/compose/up/) or `podman compose up -d`
@@ -92,12 +97,12 @@ A _native service_ in OpenRAG is a service that runs locally on your machine, no
<Tabs>
<TabItem value="TUI" label="Terminal-managed services" default>
-In the terminal session, select the **Show status** option to stop, start, restart, and inspect OpenRAG's native services.
-
-The **Native Services** section lists the status, port, and process ID (PID) for each native service.
+In the terminal session, select the **Show status** option to view the status, port, and process ID (PID) for OpenRAG's native services.
+Native services are started and stopped when you use the **Start services** and **Stop services** options.
-To manage a native service, select the option to **Stop**, **Start** or **Restart** that service.
-You can also view logs for native services.
+For more information and options, you must [start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui`.
+Then, click **Status** to access controls to stop, start, or restart individual services.
+To view streaming logs, click the name of a service, and then press <kbd>l</kbd>.
</TabItem>
<TabItem value="env" label="Self-managed services">
@@ -154,11 +159,13 @@ To reset your OpenRAG deployment _and_ delete all OpenRAG data, see [Reinstall O
<PartialExportFlows />
-2. To destroy and recreate your OpenRAG containers, select the **Show status** option in the terminal session, and then select the **Factory Reset** option.
+2. To destroy and recreate your OpenRAG containers, [start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui`.
-3. Repeat the [setup process](/install-uvx#setup) to restart the services and launch the OpenRAG app. Your previous configuration, including credentials, are restored from the `.env` file.
+3. Click **Status** in the [TUI](/tui), and then click **Factory Reset**.
-4. If you exported customized flows, [import your flows](https://docs.langflow.org/concepts-flows-import) into Langflow after completing the onboarding process.
+4. Repeat the [setup process](/install-uvx#setup) to restart the services and launch the OpenRAG app. Your previous configuration, including credentials, are restored from the `.env` file.
+
+5. If you exported customized flows, [import your flows](https://docs.langflow.org/concepts-flows-import) into Langflow after completing the onboarding process.
</TabItem>
<TabItem value="env" label="Self-managed services">
@@ -186,7 +193,8 @@ To reset your OpenRAG deployment _and_ delete all OpenRAG data, see [Reinstall O
Use image pruning to free up disk space by removing unused OpenRAG container images.
-For terminal-managed services, use the terminal's **Prune Images** option to clean up your OpenRAG container images.
+For terminal-managed services, you must [start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui`.
+Then, use the **Prune Images** option to clean up your OpenRAG container images.
You can choose to prune unused images only or all images.
If you prune all images, the OpenRAG services are stopped, all images are pruned, and then the required images are pulled the next time you start the OpenRAG services.
diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx
index f4eb27155..b76ebd0ce 100644
--- a/docs/docs/get-started/quickstart.mdx
+++ b/docs/docs/get-started/quickstart.mdx
@@ -46,7 +46,7 @@ This quickstart installs OpenRAG with [`uvx`](https://docs.astral.sh/uv/guides/t
The entire process can take a few minutes.
If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
-3. Once the environment is ready, and the OpenRAG terminal session starts, select the **Configure** option.
+3. Once the environment is ready, the OpenRAG terminal session starts, and begins issuing prompts for OpenRAG configuration settings.
4. For the OpenSearch and Langflow **Admin password** prompts, autogenerate or manually enter passwords.
@@ -64,7 +64,7 @@ This quickstart installs OpenRAG with [`uvx`](https://docs.astral.sh/uv/guides/t
Services are running.
```
-7. Select the **Open OpenRAG in browser** option to launch the OpenRAG application and start the application onboarding process.
+7. If the OpenRAG app doesn't launch automatically, select the **Open OpenRAG in browser** option to launch the OpenRAG app and start the application onboarding process.
8. For this quickstart, select the **OpenAI** model provider, enter your OpenAI API key, and then click **Complete**. Use the default settings for all other model options.
diff --git a/docs/docs/get-started/reinstall.mdx b/docs/docs/get-started/reinstall.mdx
index 5b1c83f3d..4312c1a8a 100644
--- a/docs/docs/get-started/reinstall.mdx
+++ b/docs/docs/get-started/reinstall.mdx
@@ -21,22 +21,26 @@ Destroyed containers and deleted data are lost and cannot be recovered after run
<PartialExportFlows />
-2. In your OpenRAG terminal session, select the **Status** option, and then select the **Factory Reset** option to [reset your OpenRAG containers](/manage-services#reset-containers).
+2. [Start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui` or `uvx openrag --tui`.
+
+3. Click **Status** in the [TUI](/tui).
+
+4. Click **Factory Reset** to [reset your OpenRAG containers](/manage-services#reset-containers).
<PartialFactorResetWarning />
-3. Exit the terminal session.
+5. Press <kbd>q</kbd> to quit the TUI.
-4. Optional: Delete or edit [OpenRAG's `.env` file](/reference/configuration), which is stored at `~/.openrag/tui`.
+6. Optional: Delete or edit [OpenRAG's `.env` file](/reference/configuration), which is stored at `~/.openrag/tui`.
This file contains your OpenRAG configuration, including OpenRAG passwords, API keys, OAuth credentials, and other environment variables. If you delete this file, OpenRAG automatically generates a new one after you repeat the setup and onboarding process. If you preserve this file, OpenRAG can read values from the existing `.env` file during setup and onboarding.
-5. Optional: Remove any files from the `~/.openrag/documents` subdirectory that you don't want to reingest after redeploying the containers.
+7. Optional: Remove any files from the `~/.openrag/documents` subdirectory that you don't want to reingest after redeploying the containers.
It is recommended that you preserve OpenRAG's [default documents](https://github.com/langflow-ai/openrag/tree/main/openrag-documents).
-6. Run OpenRAG with `uv run openrag` or `uvx openrag`.
+8. Run OpenRAG with `uv run openrag` or `uvx openrag`.
-7. Repeat the [setup process](/install-uvx#setup) to configure OpenRAG and restart all services.
+9. Repeat the [setup process](/install-uvx#setup) to configure OpenRAG and restart all services.
Then, open OpenRAG in your browser and repeat the [application onboarding process](/install-uvx#application-onboarding).
## Reinstall self-managed containers with `docker compose` or `podman compose`
diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx
index aeb57f443..8de9c0720 100644
--- a/docs/docs/get-started/tui.mdx
+++ b/docs/docs/get-started/tui.mdx
@@ -20,6 +20,10 @@ If you installed OpenRAG with `uvx`, start a terminal session with `uvx openrag`
### Start a GUI terminal session
+:::important
+The GUI terminal (TUI) is required to access certain controls like **Factory Reset**, **GPU/CPU mode**, and **Upgrade**.
+:::
+
For a GUI terminal experience, start OpenRAG with the `--tui` flag.
The GUI terminal, also known as the Terminal User Interface (TUI), provides the same options as the CLI terminal session with added support for mouse navigation and button-like controls for a more visual and interactive experience.
@@ -34,17 +38,19 @@ A Docker or Podman VM must be running before you start OpenRAG.
For example, on macOS with Podman, open the Podman Desktop app before you start OpenRAG.
:::
-Use the terminal's **Start services** option to start the OpenRAG services.
-
-Use the terminal's **Show status** option to access controls and information for the OpenRAG services.
+Use the terminal's **Start services** and **Stop services** options to start and stop the OpenRAG services.
-For more information, see [Manage OpenRAG services](/manage-services).
+For more information and fine-grained controls, see [Manage OpenRAG services](/manage-services).
## Toggle GPU/CPU mode
-You can toggle between GPU and CPU mode from within the terminal session if your system has compatible GPU hardware and drivers installed.
+You can toggle between GPU and CPU mode if your system has compatible GPU hardware and drivers installed:
-In the terminal session, select the **Show status** option, and then select the **Switch to GPU Mode** or **Switch to CPU Mode** option.
+1. [Start the terminal session with `--tui`](#access-the-tui), such as `uv run openrag --tui`.
+
+2. Click **Status** in the TUI.
+
+3. Click **Switch to GPU Mode** or **Switch to CPU Mode**.
This change requires restarting all OpenRAG services because each mode has its own `docker-compose` file.
@@ -56,6 +62,8 @@ This change requires restarting all OpenRAG services because each mode has its o
To exit the OpenRAG terminal session, select the **Exit** option from the terminal menu, or quit the process (<kbd>Cmd</kbd>+<kbd>C</kbd> on macOS).
+If you are using the TUI (`--tui`), you can press <kbd>q</kbd> to quit the TUI.
+
Exiting the terminal session doesn't stop your OpenRAG services.
Your OpenRAG services continue to run until they are stopped from within the terminal session or by another process that inadvertently stops them.
diff --git a/docs/docs/get-started/upgrade.mdx b/docs/docs/get-started/upgrade.mdx
index 1c475b24c..1fd5fd05c 100644
--- a/docs/docs/get-started/upgrade.mdx
+++ b/docs/docs/get-started/upgrade.mdx
@@ -12,7 +12,7 @@ Use these steps to upgrade your OpenRAG deployment to the latest version or a sp
## Export customized flows before upgrading
If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, [export your flows](https://docs.langflow.org/concepts-flows-import) before upgrading.
-This ensure that you won't lose your flows after upgrading, and you can reference the exported flows if there are any breaking changes in the new version.
+This ensures that you won't lose your flows after upgrading, and you can reference the exported flows if there are any breaking changes in the new version.
## Upgrade terminal-managed deployments
@@ -24,14 +24,15 @@ This is a two-part process because upgrading the OpenRAG Python package updates
<PartialExportFlows />
-2. To check for updates in the terminal session, select the **Show status** option, and then select the **Upgrade** option.
+2. To check for updates, you must [start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui`.
-3. If there is an update available, select the **Stop services** option.
-You might need to exit the **Show status** submenu to access the **Stop services** option in the main menu.
+3. Click **Status** in the [TUI](/tui), and then click **Upgrade**.
-4. Exit the terminal session.
+4. If there is an update available, press <kbd>Esc</kbd> to close the **Status** page, then then click **Stop All Services**.
-5. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
+5. Press <kbd>q</kbd> to exit the TUI.
+
+6. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
The commands to upgrade the package depend on how you installed OpenRAG.
<Tabs>
@@ -114,7 +115,7 @@ The commands to upgrade the package depend on how you installed OpenRAG.
</TabItem>
</Tabs>
-6. In the OpenRAG terminal session, select the **Start services** option, and then wait while the services start.
+7. In the OpenRAG terminal session, select the **Start services** option, and then wait while the services start.
When you start services, OpenRAG dictates the container version at runtime. It automatically sets the `OPENRAG_VERSION` variable in your `.env` file to match the currently installed OpenRAG Python package version.
This ensures that your terminal and containers are always synchronized when using an OpenRAG terminal session to manage services.
@@ -122,7 +123,7 @@ The commands to upgrade the package depend on how you installed OpenRAG.
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).
-7. After the containers start, select the **Open OpenRAG in browser** option.
+8. After the containers start, select the **Open OpenRAG in browser** option if the app doesn't launch automatically.
## Upgrade self-managed deployments
diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx
index 844b8ffae..e2ba0470f 100644
--- a/docs/docs/reference/configuration.mdx
+++ b/docs/docs/reference/configuration.mdx
@@ -137,7 +137,7 @@ Configure OpenSearch database authentication.
| Variable | Default | Description |
|----------|---------|-------------|
| `OPENSEARCH_DATA_PATH` | `./opensearch-data` | The path where OpenRAG creates your OpenSearch index data. This persists through updates. |
-| `OPENSEARCH_PASSWORD` | Not set | Required. OpenSearch administrator password. Must adhere to the [OpenSearch password complexity requirements](https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password). You must set this directly in the `.env` or in the terminal's [**Configure/Reconfigure**](/install-uvx#setup) option. |
+| `OPENSEARCH_PASSWORD` | Not set | Required. OpenSearch administrator password. Must adhere to the [OpenSearch password complexity requirements](https://docs.opensearch.org/latest/security/configuration/demo-configuration/#setting-up-a-custom-admin-password). You must set this directly in the `.env` or in the terminal's [**Reconfigure**](/install-uvx#setup) option. |
| `OPENSEARCH_INDEX_NAME` | `documents` | The name of the [OpenSearch index](/knowledge#index). |
| `OPENSEARCH_HOST` | `localhost` | OpenSearch service host. |
| `OPENSEARCH_PORT` | `9200` | OpenSearch service port. |
diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx
index 9695bff80..356f1ae80 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -43,7 +43,7 @@ If you encounter container memory errors, try the following:
* Use a CPU-only deployment to reduce memory usage.
- For terminal-managed deployments, you can enable **CPU mode** through the terminal's **Show Status** option.
+ For terminal-managed deployments, you must [start the terminal session with `--tui`](/tui#access-the-tui), such as `uv run openrag --tui`. Then, click **Status** in the [TUI](/tui), and then click **Switch to CPU mode**.
For self-managed deployments, CPU-only deployments use the `docker-compose.yml` file that doesn't have GPU overrides.
@@ -211,7 +211,7 @@ This cache can become stale, producing errors like missing dependencies.
4. Select the **Start services** option to restart the OpenRAG containers.
-5. Select the **Open OpenRAG in a browser** option, and then retry document ingestion.
+5. Select the **Open OpenRAG in browser** option, and then retry document ingestion.
In contrast to `uvx`, if you install OpenRAG with `uv`, dependencies are synced directly from your `pyproject.toml` file.
This should automatically install `easyocr` because `easyocr` is included as a dependency in OpenRAG's `pyproject.toml`.