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

revised setup, explain uv cache, rename svc mgmt

Browse source
This commit is contained in:
April M 2025-12-04 17:17:00 -08:00
parent e2c4d0a9e5
commit d578e7832e
18 changed files with 347 additions and 268 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/docs/core-components/ingestion.mdx
View file

@ -64,11 +64,11 @@ To enable multiple connectors, you must register an app and generate credentials
<Tabs>
<TabItem value="TUI" label="TUI Advanced Setup" default>
If you use the TUI to manage your OpenRAG containers, provide OAuth credentials in the **Advanced Setup**.
If you use the TUI to manage your OpenRAG services, provide OAuth credentials in the **Advanced Setup**.
You can do this during [installation](/install#setup), or you can add the credentials afterwards:
1. If OpenRAG is running, stop it: Go to [**Status**](/install#tui-container-management), and then click **Stop Services**.
1. If OpenRAG is running, stop it: Go to [**Status**](/manage-services#tui-container-management), and then click **Stop Services**.
2. Click **Advanced Setup**, and then add the OAuth credentials for the cloud storage providers that you want to use:
@ -83,12 +83,12 @@ These are the URLs your OAuth provider will redirect back to after users authent
OpenRAG regenerates the [`.env`](/reference/configuration) file with the given credentials.
5. Click **Start Container Services**.
5. Click **Start All Services**.
</TabItem>
<TabItem value="env" label="Docker Compose .env file">
If you [install OpenRAG with self-managed containers](/docker), set OAuth credentials in the `.env` file for Docker Compose.
If you [installed OpenRAG with self-managed services](/docker), set OAuth credentials in the `.env` file for Docker Compose.
You can do this during [initial set up](/docker#install-openrag-with-docker-compose), or you can add the credentials afterwards:

25
docs/docs/core-components/knowledge.mdx
View file

@ -32,20 +32,21 @@ It is recommended that you keep these documents, and use [filters](/knowledge-fi
## OpenSearch authentication and document access {#auth}
When you [install OpenRAG](/install), you can choose between two setup modes: **Basic Setup** and **Advanced Setup**.
The mode you choose determines how OpenRAG authenticates with OpenSearch and controls access to documents:
When you [install OpenRAG](/install-options), you provide the initial configuration values for your OpenRAG services.
This includes authentication credentials for OpenSearch and OAuth connectors.
This configuration determines how OpenRAG authenticates with OpenSearch and controls access to documents in your knowledge base:
* **Basic Setup (no-auth mode)**: If you choose **Basic Setup**, then OpenRAG is installed in no-auth mode.
This mode uses one, anonymous JWT token for OpenSearch authentication.
There is no differentiation between users.
All users that access your OpenRAG instance can access all documents uploaded to your OpenSearch knowledge base.
* **No-auth mode (basic setup)**: If you choose **Basic Setup** in the [TUI](/tui), or your `.env` file doesn't include OAuth credentials, then OpenRAG runs in no-auth mode.
* **Advanced Setup (OAuth mode)**: If you choose **Advanced Setup**, then OpenRAG is installed in OAuth mode.
This mode uses a unique JWT token for each OpenRAG user, and each document is tagged with user ownership. Documents are filtered by user owner.
This means users see only the documents that they uploaded or have access to.
This mode uses one anonymous JWT token for OpenSearch authentication.
There is no differentiation between users; all users that access your OpenRAG instance can access all documents uploaded to your knowledge base.
You can enable OAuth mode after installation.
For more information, see [Ingest files with OAuth connectors](/ingestion#oauth-ingestion).
* **OAuth mode (advanced setup)**: If you choose **Advanced Setup** in the [TUI](/tui), or your `.env` file includes OAuth credentials, then OpenRAG runs in OAuth mode.
This mode uses a unique JWT token for each OpenRAG user, and each document is tagged with user ownership.
Documents are filtered by user owner; users see only the documents that they uploaded or have access to through their cloud storage accounts.
You can enable OAuth mode after installation, as explained in [Ingest files with OAuth connectors](/ingestion#oauth-ingestion).
## OpenSearch indexes
@ -119,7 +120,7 @@ To modify the Docling ingestion and embedding parameters, click <Icon name="Sett
:::tip
OpenRAG warns you if `docling serve` isn't running.
You can [start and stop OpenRAG services](/install#tui-container-management) from the TUI main menu with **Start Native Services** or **Stop Native Services**.
You can [start and stop OpenRAG services](/manage-services#tui-container-management) from the TUI main menu with **Start Native Services** or **Stop Native Services**.
:::
* **Embedding model**: Select the model to use to generate vector embeddings for your documents.

9
docs/docs/get-started/docker.mdx
View file

@ -1,5 +1,5 @@
---
title: Deploy OpenRAG with self-managed containers
title: Deploy OpenRAG with self-managed services
slug: /docker
---
@ -8,10 +8,11 @@ import TabItem from '@theme/TabItem';
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
import PartialWsl from '@site/docs/_partial-wsl-install.mdx';
You can use Docker or Podman to deploy self-managed OpenRAG containers.
Use this option if you don't want to use the TUI for container management, or you need to run OpenRAG in an environment where using the TUI is unfeasible.
To manage your own OpenRAG services, deploy OpenRAG with Docker or Podman.
OpenRAG has two Docker Compose files. Both files deploy the same applications and containers locally, but they are for different environments:
Use this installation method if you don't want to [use the Terminal User Interface (TUI)](/tui), or you need to run OpenRAG in an environment where using the TUI is unfeasible.
OpenRAG has two Docker Compose files. Both files deploy the same services, but they are for different environments:
- [`docker-compose.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose.yml) is an OpenRAG deployment with GPU support for accelerated AI processing. This Docker Compose file requires an NVIDIA GPU with [CUDA](https://docs.nvidia.com/cuda/) support.

15
docs/docs/get-started/install-options.mdx
View file

@ -4,27 +4,28 @@ slug: /install-options
---
The [OpenRAG architecture](/#openrag-architecture) is lightweight and container-based with a central OpenRAG backend that orchestrates the various services and external connectors.
Depending on your use case, OpenRAG can assist with container management, or you can manage the containers yourself.
Depending on your use case, OpenRAG can assist with service management, or you can manage the services yourself.
Choose the installation method that best fits your needs:
* **Use the [Terminal User Interface (TUI)](/tui) to manage containers**: For guided configuration and simplified container management, install OpenRAG with TUI-managed containers.
* **Use the [Terminal User Interface (TUI)](/tui) to manage services**: For guided configuration and simplified service management, install OpenRAG with TUI-managed services.
* [**Automatic installer script**](/install): Run one script to install the required dependencies and install OpenRAG with `uvx`.
* [**Automatic installer script**](/install): Run one script to install the required dependencies and OpenRAG.
* [**`uv`**](/install-uv): Install OpenRAG as a dependency of a new or existing Python project.
* [**`uvx`**](/install-uvx): Invoke OpenRAG without permanently installing it in a Python project.
* [**`uvx`**](/install-uvx): Install OpenRAG without creating a project or modifying your project's dependencies.
* [**Install OpenRAG on Microsoft Windows**](/install-windows): On Windows machines, you must install OpenRAG within the Windows Subsystem for Linux (WSL).
OpenRAG doesn't support nested virtualization; don't run OpenRAG on a WSL distribution that is inside a Windows VM.
* [**Manage your own containers**](/docker): You can use Docker or Podman to deploy self-managed OpenRAG containers.
* [**Manage your own services**](/docker): You can use Docker or Podman to deploy self-managed OpenRAG services.
The first time you start OpenRAG, you must complete application onboarding.
This is required for all installation methods because it prepares the minimum required configuration for OpenRAG to run.
For TUI-managed services, you must also complete initial setup before you start the OpenRAG services.
For more information, see the instructions for your chosen installation method.
Your OpenRAG configuration is stored in a `.env` file in the OpenRAG installation directory.
When using TUI-managed containers, the TUI prompts you for any missing values during setup and onboarding, and any values detected in a preexisting `.env` file are automatically populated.
When using self-managed containers, you must predefine these values in a `.env` file, as you would for any container deployment.
When using TUI-managed services, the TUI prompts you for any missing values during setup and onboarding, and any values detected in a preexisting `.env` file are automatically populated.
When using self-managed services, you must predefine these values in a `.env` file, as you would for any Docker or Podman deployment.
For more information, see the instructions for your chosen installation method and [Environment variables](/reference/configuration).

4
docs/docs/get-started/install-uv.mdx
View file

@ -3,7 +3,7 @@ title: Install OpenRAG in a Python project with uv
slug: /install-uv
---
For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
For guided configuration and simplified service management, install OpenRAG with services managed by the [Terminal User Interface (TUI)](/tui).
You can use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) to install OpenRAG as a managed or unmanaged dependency in a new or existing Python project.
@ -79,6 +79,6 @@ When the Terminal User Interface (TUI) starts, you must complete the initial set
## Next steps
* [Manage OpenRAG containers](/manage-containers)
* [Manage OpenRAG services](/manage-services)
* [Chat](/chat)
* [Upload documents](/ingestion)

34
docs/docs/get-started/install-uvx.mdx
View file

@ -3,43 +3,47 @@ title: Invoke OpenRAG with uvx
slug: /install-uvx
---
For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
For guided configuration and simplified service management, install OpenRAG with services managed by the [Terminal User Interface (TUI)](/tui).
You can use [`uvx`](https://docs.astral.sh/uvx/getting-started/installation/) to invoke OpenRAG without permanently installing it in a Python project.
`uvx` installs OpenRAG in an ephemeral, isolated virtual environment.
This method is best when you want to test OpenRAG outside of a Python project or you don't need to preserve the OpenRAG installation.
Depending on your project structure, `uvx` might not be suitable for production deployments.
You can use [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools) to invoke OpenRAG outside of a Python project or without modifying your project's dependencies.
:::tip
The [automatic installer script](/install) also uses `uvx` to install OpenRAG.
:::
Depending on your project structure, `uvx` might not be suitable for production deployments.
For other installation methods, see [Choose an installation method](/install-options).
## Install and run OpenRAG with uvx
Use `uvx` to quickly run OpenRAG without creating a project or modifying any files.
1. Create a directory to store your OpenRAG configuration files and data, and then change to that directory:
1. Create a directory to store the OpenRAG configuration files:
```bash
mkdir openrag-workspace
cd openrag-workspace
```
2. Run OpenRAG:
:::tip
If you want to use a pre-populated [`.env`](/reference/configuration) file for OpenRAG, copy it to this directory before invoking OpenRAG.
:::
2. Invoke OpenRAG:
```bash
uvx openrag
```
To run a specific version:
You can invoke a specific version using any of the [`uvx` version specifiers](https://docs.astral.sh/uv/guides/tools/#requesting-specific-versions), such as `--from`:
```bash
uvx --from openrag==0.1.30 openrag
```
<!-- move down to the setup section?? -->
When you install OpenRAG with `uvx`, OpenRAG creates its `.env` and `docker-compose.yml` files in the current working directory.
If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
Invoking OpenRAG with `uvx openrag` creates a cached, ephemeral environment for the TUI in your local `uv` cache.
By invoking OpenRAG in a specific directory, your OpenRAG configuration files and data are stored separately from the `uv` cache.
Clearing the `uv` cache doesn't remove your entire OpenRAG installation.
After clearing the cache, you can re-invoke OpenRAG (`uvx openrag`) to restart the TUI with your preserved configuration and data.
If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
## Set up OpenRAG with the TUI
@ -47,9 +51,11 @@ When the Terminal User Interface (TUI) starts, you must complete the initial set
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)
The OpenRAG setup process creates the `.env` and `docker-compose.yml` files in the directory where you invoked OpenRAG.
If it detects a `.env` file in the OpenRAG installation directory, it sources any variables from that file.
## Next steps
* [Manage OpenRAG containers](/manage-containers)
* [Manage OpenRAG services](/manage-services)
* [Chat](/chat)
* [Upload documents](/ingestion)

6
docs/docs/get-started/install-windows.mdx
View file

@ -7,8 +7,8 @@ import PartialWsl from '@site/docs/_partial-wsl-install.mdx';
If you're using Windows, you must install OpenRAG within the Windows Subsystem for Linux (WSL).
For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
For self-managed containers, deploy OpenRAG with Docker or Podman inside your WSL distribution.
For guided configuration and simplified service management, install OpenRAG with services managed by the [Terminal User Interface (TUI)](/tui).
For self-managed services, deploy OpenRAG with Docker or Podman inside your WSL distribution.
## Nested virtualization isn't supported
@ -22,6 +22,6 @@ For self-managed containers, deploy OpenRAG with Docker or Podman inside your WS
## Next steps
* [Manage OpenRAG containers](/manage-containers)
* [Manage OpenRAG services](/manage-services)
* [Chat](/chat)
* [Upload documents](/ingestion)

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

@ -11,11 +11,11 @@ import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
For a fully guided installation and preview of OpenRAG's core features, try the [quickstart](/quickstart).
:::
For guided configuration and simplified container management, install OpenRAG with containers managed by the [Terminal User Interface (TUI)](/tui).
For guided configuration and simplified service management, install OpenRAG with services managed by the [Terminal User Interface (TUI)](/tui).
The installer script detects and installs any missing dependencies, and then installs OpenRAG with [`uvx`](https://docs.astral.sh/uvx/getting-started/installation/).
The installer script detects and installs any missing dependencies, and then installs OpenRAG with [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools) in the directory where you run the script.
Because `uvx` installs OpenRAG in an ephemeral, isolated virtual environment, this installation method isn't suitable for all use cases.
This installation method is best for running OpenRAG outside of a Python project.
For other installation methods, see [Choose an installation method](/install-options).
## Prerequisites
@ -48,70 +48,118 @@ See [Install OpenRAG on Windows](/install-windows).
## Install OpenRAG {#install}
The script detects and installs uv, Docker/Podman, and Docker Compose prerequisites, then runs OpenRAG with `uvx`.
The script detects and installs uv, Docker/Podman, and Docker Compose prerequisites, then it installs and runs OpenRAG with `uvx`.
1. Create a directory to store your OpenRAG configuration file, and then change to that directory:
1. Create a directory to store the OpenRAG configuration files:
```bash
mkdir openrag-workspace
cd openrag-workspace
```
2. Run the installer:
2. Get and run the installer script:
```bash
curl -fsSL https://docs.openr.ag/files/run_openrag_with_prereqs.sh | bash
```
<!-- move down to the setup section?? -->
The installer script installs OpenRAG with `uvx`.
When installed in this way, OpenRAG creates its `.env` and `docker-compose.yml` files in the current working directory.
<!-- use partial? -->
If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
## Set up OpenRAG with the TUI {#setup}
<!-- use partial? -->
When the Terminal User Interface (TUI) starts, you must complete the initial setup to configure OpenRAG.
:::tip
You can also manually [download the OpenRAG install script](https://docs.openr.ag/files/run_openrag_with_prereqs.sh), move it to your OpenRAG directory, and then run it:
```bash
bash run_openrag_with_prereqs.sh
```
:::
3. Wait while the installer script prepares your environment and installs OpenRAG.
You might be prompted to install certain dependencies if they aren't already present in your environment.
The entire process can take a few minutes.
Once the environment is ready, the OpenRAG Terminal User Interface (TUI) starts.
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)
The OpenRAG setup process creates a `.env` file at the root of your OpenRAG directory, and then starts OpenRAG.
If it detects a `.env` file in the OpenRAG root directory, it sources any variables from the `.env` file.
The installer script uses `uvx`, which creates a cached, ephemeral environment in your local `uv` cache.
Running the script in a specific directory, your OpenRAG configuration files and data are stored separately from the `uv` cache.
Clearing the cache doesn't delete your entire OpenRAG installation, only the TUI environment.
After clearing the cache, run `uvx openrag` to [access the TUI](/tui) and continue with your preserved configuration and data.
The TUI offers two setup methods to populate the required values. **Basic Setup** can generate all minimum required values for OpenRAG. However, **Basic Setup** doesn't enable [OAuth connectors for cloud storage](/knowledge#auth). If you want to use OAuth connectors to upload documents from cloud storage, select **Advanced Setup**.
If OpenRAG detects OAuth credentials, it recommends **Advanced Setup**.
If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).
## Set up OpenRAG with the TUI {#setup}
When you install OpenRAG with the installer script, you manage the OpenRAG services with the Terminal User Interface (TUI).
The TUI guides you through the initial configuration process before you start the OpenRAG services.
Your [OpenRAG configuration](/reference/configuration) is stored in a `.env` file that is created automatically in the OpenRAG installation directory.
If OpenRAG detects an existing `.env` file, the TUI automatically populates those values during setup and onboarding.
Container definitions are stored in a `docker-compose.yml` file in the OpenRAG installation directory.
Because the installer script uses `uvx`, the OpenRAG `.env` and `docker-compose.yml` files are stored in the directory where you ran the installer script.
You can use either **Basic Setup** or **Advanced Setup** to configure OpenRAG.
This choice determines [how OpenRAG authenticates with OpenSearch and controls access to documents](/knowledge#auth).
:::info
You must use **Advanced Setup** if you want to [use OAuth connectors to upload documents from cloud storage](/ingestion#oauth-ingestion).
:::
If OpenRAG detects OAuth credentials during setup, it recommends **Advanced Setup** in the TUI.
<Tabs groupId="Setup method">
<TabItem value="Basic setup" label="Basic setup" default>
1. To install OpenRAG with **Basic Setup**, click **Basic Setup** or press <kbd>1</kbd>.
2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow.
1. In the TUI, click **Basic Setup** or press <kbd>1</kbd>.
The OpenSearch password is required. The Langflow admin password is optional.
If no Langflow admin password is generated, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required.
2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically.
The OpenSearch password is required.
The Langflow password is optional.
If the Langflow password is empty, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) without password authentication.
3. Optional: Enter your OpenAI API key, or leave this field empty if you want to configure model provider credentials later during application onboarding.
3. Optional: Paste your OpenAI API key in the OpenAI API key field. You can also provide this during onboarding or choose a different model provider.
4. Click **Save Configuration**.
Your passwords are saved in the `.env` file used to start OpenRAG.
5. To start OpenRAG, click **Start All Services**.
Startup pulls container images and runs them, so it can take some time.
When startup is complete, the TUI displays the following:
```bash
Your passwords and API key, if provided, are stored in the `.env` file in your OpenRAG installation directory.
If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file.
5. Click **Start All Services** to start the OpenRAG services that run in containers.
This process can take some time while OpenRAG pulls and runs the container images.
If all services start successfully, the TUI prints a confirmation message:
```text
Services started successfully
Command completed successfully
```
6. To start the Docling service, under **Native Services**, click **Start**.
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`.
6. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
7. Launch the OpenRAG application:
* From the TUI main menu, click **Open App**.
* In your browser, navigate to `localhost:3000`.
8. Continue with [application onboarding](#application-onboarding).
</TabItem>
<TabItem value="Advanced setup" label="Advanced setup">
1. To install OpenRAG with **Advanced Setup**, click **Advanced Setup** or press <kbd>2</kbd>.
2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow.
1. In the TUI, click **Advanced Setup** or press <kbd>2</kbd>.
The OpenSearch password is required. The Langflow admin password is optional.
If no Langflow admin password is generated, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required.
2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services, or click **Generate Passwords** to generate passwords automatically.
3. Paste your OpenAI API key in the OpenAI API key field.
4. If you want to upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in a `.env` file in the OpenRAG installation directory.
The OpenSearch password is required.
The Langflow password is optional.
If the Langflow password is empty, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) without password authentication.
3. Optional: Enter your OpenAI API key, or leave this field empty if you want to configure model provider credentials later during application onboarding.
4. To upload documents from external storage, such as Google Drive, add the required OAuth credentials for the connectors that you want to use. These settings can be populated automatically if OpenRAG detects these credentials in a `.env` file in the OpenRAG installation directory.
* **Amazon**: Provide your AWS Access Key ID and AWS Secret Access Key with access to your S3 instance. For more information, see the AWS documentation on [Configuring access to AWS applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html).
* **Google**: Provide your Google OAuth Client ID and Google OAuth Client Secret. You can generate these in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). For more information, see the [Google OAuth client documentation](https://developers.google.com/identity/protocols/oauth2).
@ -122,113 +170,54 @@ If OpenRAG detects OAuth credentials, it recommends **Advanced Setup**.
5. The OpenRAG TUI presents redirect URIs for your OAuth app.
These are the URLs your OAuth provider will redirect back to after user sign-in.
Register these redirect values with your OAuth provider as they are presented in the TUI.
6. Click **Save Configuration**.
7. To start OpenRAG, click **Start All Services**.
Startup pulls container images and runs them, so it can take some time.
When startup is complete, the TUI displays the following:
```bash
Your passwords, API key (if provided), and OAuth credentials (if provided) are stored in the `.env` file in your OpenRAG installation directory.
If you modified any credentials that were pulled from an existing `.env` file, those values are updated in the `.env` file.
7. Click **Start All Services** to start the OpenRAG services that run in containers.
This process can take some time while OpenRAG pulls and runs the container images.
If all services start successfully, the TUI prints a confirmation message:
```text
Services started successfully
Command completed successfully
```
8. To start the Docling service, under **Native Services**, click **Start**.
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`.
8. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
9. Launch the OpenRAG application:
* From the TUI main menu, click **Open App**.
* In your browser, navigate to `localhost:3000`.
10. If you enabled OAuth connectors, you must sign in to your OAuth provider before being redirected to your OpenRAG instance.
11. Two additional variables are available for **Advanced Setup** at this point.
Only change these variables if you have a non-default network configuration for your deployment, such as using a reverse proxy or custom domain.
11. If required, you can edit the following additional environment variables.
Only change these variables if your OpenRAG deployment has a non-default network configuration, such as a reverse proxy or custom domain.
* `LANGFLOW_PUBLIC_URL`: Sets the base address to access the Langflow web interface. This is where users interact with flows in a browser.
* `WEBHOOK_BASE_URL`: Sets the base address of the OpenRAG OAuth connector endpoint.
Supported webhook endpoints:
* `WEBHOOK_BASE_URL`: Sets the base address for the following OpenRAG OAuth connector endpoints:
- Amazon S3: Not applicable.
- Google Drive: `/connectors/google_drive/webhook`
- OneDrive: `/connectors/onedrive/webhook`
- SharePoint: `/connectors/sharepoint/webhook`
- Google Drive: `WEBHOOK_BASE_URL/connectors/google_drive/webhook`
- OneDrive: `WEBHOOK_BASE_URL/connectors/onedrive/webhook`
- SharePoint: `WEBHOOK_BASE_URL/connectors/sharepoint/webhook`
12. Continue with [application onboarding](#application-onboarding).
</TabItem>
</Tabs>
The first time you start the OpenRAG application, you must complete application onboarding to select language and embedding models that are essential for OpenRAG features like the [**Chat**](/chat).
<PartialOnboarding />
## Manage OpenRAG containers with the TUI {#tui-container-management}
After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers.
### Diagnostics
The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.
### Status {#status}
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.
* **Logs**: To view streaming logs, select the container you want to view, and press <kbd>l</kbd>.
To copy the logs, click **Copy to Clipboard**.
* **Upgrade**: Check for updates. For more information, see [upgrade OpenRAG](/upgrade).
* **Factory Reset**: This is a destructive action that [resets your containers](#reset-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 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.
:::
1. To destroy and recreate your OpenRAG containers, go to the TUI [**Status** menu](#status), and then click **Factory Reset**.
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
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.
### 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.
#### 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:
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`.
#### 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.
## Next steps
* [Manage OpenRAG containers](/manage-containers)
* [Manage OpenRAG services](/manage-services)
* [Chat](/chat)
* [Upload documents](/ingestion)

32
docs/docs/get-started/manage-containers.mdx
View file

@ -1,32 +0,0 @@
---
title: Manage OpenRAG containers
slug: /manage-containers
---
Container management is an essential part of maintaining your OpenRAG deployment.
## Manage containers with the TUI
If you [installed OpenRAG](/install-options) with the automated installer script, `uv`, or `uvx`, you can use the [Terminal User Interface (TUI)](/tui) to manage your containers:
* Start and stop OpenRAG containers.
* Start and stop OpenRAG's native services (Docling).
* View the status of your OpenRAG services.
* Access container logs for troubleshooting.
* Upgrade your OpenRAG containers to the latest version.
* Reset your OpenRAG containers to an initial state (destructive).
## Manage containers with Docker or Podman
If you [deployed OpenRAG with self-managed containers](/docker), run Docker or Podman commands to manage your OpenRAG containers.
* Start containers
* Stop containers
* View container status
* Access container logs for troubleshooting
* Upgrade your OpenRAG containers to the latest version
* Reset your OpenRAG containers to an initial state (destructive)
## See also
* [Uninstall OpenRAG](/uninstall)

103
docs/docs/get-started/manage-services.mdx Normal file
View file

@ -0,0 +1,103 @@
---
title: Manage OpenRAG containers and services
slug: /manage-services
---
Service management is an essential part of maintaining your OpenRAG deployment.
Most OpenRAG services run in containers.
_Native services_, like Docling, run directly on the local machine where you installed OpenRAG.
## Manage containers and services with the TUI {#tui-container-management}
If you [installed OpenRAG](/install-options) with the automated installer script, `uv`, or `uvx`, you can use the [Terminal User Interface (TUI)](/tui) to manage your services:
* Start and stop OpenRAG container-based services.
* Start and stop OpenRAG's native services (Docling).
* View the status of your OpenRAG services.
* Access container logs for troubleshooting.
* Upgrade your OpenRAG containers to the latest version.
* Reset your OpenRAG containers to an initial state (destructive).
### Diagnostics
The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.
### Status {#status}
The TUI's **Status** menu provides information about your OpenRAG services, including health, ports, logs, and controls:
* **Logs**: To view streaming logs, select the container you want to view, and press <kbd>l</kbd>.
To copy the logs, click **Copy to Clipboard**.
* **Upgrade**: Check for updates to OpenRAG. For more information, see [upgrade OpenRAG](/upgrade).
* **Factory Reset**: This is a destructive action that [resets your containers](#reset-containers).
* **Native services**: [View and manage OpenRAG's native services](#start-all-services) that run directly on the 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 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.
:::
1. To destroy and recreate your OpenRAG containers, go to the TUI [**Status** menu](#status), and then click **Factory Reset**.
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
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.
### Start all services {#start-all-services}
Through the TUI, you can stop and start OpenRAG services.
#### Start containers
On the TUI main page or the **Setup** menu, click **Start All Services** to start the OpenRAG containers.
When you start all services, the following processes happen:
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`.
#### 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.
## Manage containers with Docker or Podman
If you [deployed OpenRAG with self-managed containers](/docker), run Docker or Podman commands to manage your OpenRAG containers.
* Start containers
* Stop containers
* View container status
* Access container logs for troubleshooting
* Upgrade your OpenRAG containers to the latest version
* Reset your OpenRAG containers to an initial state (destructive)
## See also
* [Uninstall OpenRAG](/uninstall)

35
docs/docs/get-started/quickstart.mdx
View file

@ -33,10 +33,9 @@ For other providers, see the complete [installation guide](/install).
## Install OpenRAG
For this quickstart, install OpenRAG with the automatic installer script and basic setup.
The script installs OpenRAG dependencies, including Docker or Podman, and then it installs and runs OpenRAG with [`uvx`](https://docs.astral.sh/uv/guides/tools/#running-tools).
This script installs OpenRAG dependencies, including Docker or Podman, installs OpenRAG with [`uvx`](https://docs.astral.sh/uvx/getting-started/installation/), and creates a `.env` file and `docker-compose` files in the current working directory.
1. Create a directory to store the OpenRAG configuration files, and then change to that directory:
1. Create a directory for your OpenRAG installation, and then change to that directory:
```bash
mkdir openrag-workspace
@ -53,39 +52,41 @@ This script installs OpenRAG dependencies, including Docker or Podman, installs
You might be prompted to install certain dependencies if they aren't already present in your environment.
The entire process can take a few minutes.
Once the environment is ready, the OpenRAG Terminal User Interface (TUI) starts.
Once the environment is ready, the OpenRAG [Terminal User Interface (TUI)](/tui) starts.
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)
3. Click **Basic Setup**.
3. In the TUI, click **Basic Setup**.
4. Create passwords for your OpenRAG installation's OpenSearch and Langflow services. You can click **Generate Passwords** to automatically generate passwords.
4. Click **Generate Passwords** to create administrator passwords for your OpenRAG OpenSearch and Langflow services.
The OpenSearch password is required. The Langflow admin password is optional.
If you don't generate a Langflow admin password, Langflow runs in [autologin mode](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login) with no password required.
5. Leave the **OpenAI API key** field empty.
Your passwords are saved in the `.env` file that is used to start OpenRAG.
You can find this file in your OpenRAG installation directory.
5. Click **Save Configuration**, and then click **Start All Services**.
6. Click **Save Configuration**, and then click **Start All Services**.
Wait a few minutes while the startup process pulls and runs the necessary container images.
Proceed when you see the following messages in the TUI:
This process can take some time while OpenRAG pulls and runs the container images.
If all services start successfully, the TUI prints a confirmation message:
```bash
```text
Services started successfully
Command completed successfully
```
6. To open the OpenRAG application, go to the TUI main menu, and then click **Open App**.
Alternatively, in your browser, navigate to `localhost:3000`.
Your [OpenRAG configuration](/reference/configuration) is stored in a `.env` file that is created automatically in the directory where you ran the installer script.
Container definitions are stored in a `docker-compose.yml` file in the same directory.
7. Select the **OpenAI** model provider, enter your OpenAI API key, and then click **Complete**.
7. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
For this quickstart, you can use the default options for the model settings.
8. From the TUI main menu, click **Open App** to launch the OpenRAG application and start the application onboarding process.
8. Click through the overview slides for a brief introduction to OpenRAG and basic setup, or click <Icon name="ArrowRight" aria-hidden="true"/> **Skip overview**.
9. 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.
10. Click through the overview slides for a brief introduction to OpenRAG, or click <Icon name="ArrowRight" aria-hidden="true"/> **Skip overview**.
You can complete this quickstart without going through the overview.
The overview demonstrates some basic functionality that is covered in the next section and in other parts of the OpenRAG documentation.
## Load and chat with documents {#chat-with-documents}

2
docs/docs/get-started/reinstall.mdx
View file

@ -7,7 +7,7 @@ You can reset your OpenRAG deployment to its initial state by recreating the con
## Reinstall TUI-managed containers
1. In the TUI, [reset your containers](/manage-containers) to destroy the following:
1. In the TUI, [reset your containers](/manage-services) to destroy the following:
* All existing OpenRAG containers, volumes, and local images
* Any additional Docker objects

8
docs/docs/get-started/tui.mdx
View file

@ -7,10 +7,10 @@ The OpenRAG Terminal User Interface (TUI) provides a simplified and guided exper
![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)
The TUI is used when you install OpenRAG with the [automatic installer script](/install), [`uv`](/install-uv), or [`uvx`](/install-uvx).
It guides you through the initial setup, creates your `.env` file automatically, and provides convenient access to [container management](/manage-containers) controls.
If you install OpenRAG with the [automatic installer script](/install), [`uv`](/install-uv), or [`uvx`](/install-uvx), you use the TUI to manage your OpenRAG deployment.
The TUI guides you through the initial setup, automatically manages your OpenRAG `.env` and `docker-compose.yml` files, and provides convenient access to [service management](/manage-services) controls.
In contrast, when you [deploy OpenRAG with self-managed containers](/docker), you must manually configure OpenRAG by preparing a `.env` file and using Docker or Podman commands to deploy and manage your containers.
In contrast, when you [deploy OpenRAG with self-managed services](/docker), you must manually configure OpenRAG by preparing a `.env` file and using Docker or Podman commands to deploy and manage your OpenRAG services.
## Access the TUI {#access-the-tui}
@ -28,4 +28,4 @@ To restart the TUI, see [Access the TUI](#access-the-tui).
## See also
* [Manage containers](/manage-containers)
* [Manage services](/manage-services)

6
docs/docs/get-started/uninstall.mdx
View file

@ -4,11 +4,11 @@ slug: /uninstall
---
:::tip
If you want to reset your OpenRAG containers without removing OpenRAG entirely, see [Reset OpenRAG containers](/manage-containers) and [Reinstall OpenRAG](/reinstall).
If you want to reset your OpenRAG containers without removing OpenRAG entirely, see [Reset OpenRAG containers](/manage-services) and [Reinstall OpenRAG](/reinstall).
:::
If you used the [automated installer script](/install) or [`uvx`](/install-uvx) to install OpenRAG, run `uv cache clean openrag` to remove the cached OpenRAG environment.
If you used the [automated installer script](/install) or [`uvx`](/install-uvx) to install OpenRAG, clear your `uv` cache (`uv cache clean`) to remove the TUI environment, and then delete the directory containing your OpenRAG configuration files and data (where you would invoke OpenRAG).
If you used [`uv`](/install-uv) to install OpenRAG, run `uv remove openrag` in your Python project.
For self-managed containers, destroy the containers, prune any additional Docker objects, and delete any remaining OpenRAG files, as explained in [Reset OpenRAG containers](/manage-containers).
For self-managed containers, destroy the containers, prune any additional Docker objects, and delete any remaining OpenRAG files, as explained in [Reset OpenRAG containers](/manage-services).

10
docs/docs/get-started/upgrade.mdx
View file

@ -8,13 +8,15 @@ import TabItem from '@theme/TabItem';
Use these steps to upgrade your OpenRAG deployment to the latest version or a specific version.
## Upgrade TUI-managed containers
## Upgrade TUI-managed installations
To upgrade OpenRAG, you need to upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers.
Upgrading the Python package also upgrades Docling by bumping the dependency in `pyproject.toml`.
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.
1. Stop your OpenRAG containers: In the OpenRAG TUI, go to the **Status** menu, and then click **Stop Services**.
1. Stop all OpenRAG services: In the OpenRAG TUI, go to the **Status** menu, and then click **Stop Services**.
2. Upgrade the OpenRAG Python package to the latest version from [PyPI](https://pypi.org/project/openrag/).
@ -111,7 +113,9 @@ 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).
4. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
4. Under [**Native Services**](/manage-services), click **Start** to start the Docling service.
5. When the upgrade process is complete, you can close the **Status** window and continue using OpenRAG.
## Upgrade self-managed containers

45
docs/docs/reference/configuration.mdx
View file

@ -25,45 +25,36 @@ Environment variables always take precedence over other variables.
### Set environment variables {#set-environment-variables}
After you start OpenRAG, you must [stop and restart OpenRAG containers](/install#tui-container-management) to apply any changes you make to the `.env` file.
Environment variables are either mutable or immutable.
To set mutable environment variables, do the following:
If you edit mutable environment variables, you can apply the changes by stopping and restarting the OpenRAG services after editing the `.env` file:
1. Stop OpenRAG with the TUI or Docker Compose.
1. [Stop the OpenRAG services](/manage-services).
2. Set the values in the `.env` file:
2. Edit your `.env` file.
3. [Restart the OpenRAG services](/manage-services).
If you edit immutable environment variables, you must [redeploy OpenRAG](/reinstall) with your modified `.env` file.
For example, with self-managed services, do the following:
1. Stop the deployment:
```bash
LOG_LEVEL=DEBUG
LOG_FORMAT=json
SERVICE_NAME=openrag-dev
docker compose down
```
3. Start OpenRAG with the TUI or Docker Compose.
2. Edit your `.env` file.
Certain environment variables that you set during [application onboarding](/install#application-onboarding), such as provider API keys and provider endpoints, require resetting the containers after modifying the `.env` file.
To change immutable variables with TUI-managed containers, you must [reinstall OpenRAG](/reinstall) and either delete or modify the `.env` file before you repeat the setup and onboarding process in the TUI.
To change immutable variables with self-managed containers, do the following:
1. Stop OpenRAG with Docker Compose.
2. Remove the containers:
3. Redeploy OpenRAG:
```bash
docker-compose down
docker compose up -d
```
3. Update the values in your `.env` file.
4. Restart the Docling service.
4. Start OpenRAG with Docker Compose:
```bash
docker-compose up -d
```
5. Repeat [application onboarding](/install#application-onboarding). The values in your `.env` file are automatically populated.
5. Launch the OpenRAG app, and then repeat [application onboarding](/install#application-onboarding). The values in your `.env` file are automatically populated.
## Supported environment variables
@ -73,7 +64,7 @@ All OpenRAG configuration can be controlled through environment variables.
Configure which models and providers OpenRAG uses to generate text and embeddings.
These are initially set during [application onboarding](/install#application-onboarding).
Some values are immutable and can only be changed by recreating the OpenRAG containers, as explained in [Set environment variables](#set-environment-variables).
Some values are immutable and can only be changed by redeploying OpenRAG, as explained in [Set environment variables](#set-environment-variables).
| Variable | Default | Description |
|----------|---------|-------------|

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

@ -57,27 +57,41 @@ Ensure ports 3000, 7860, 8000, 9200, 5601 are available.
## OCR ingestion fails (easyocr not installed)
If Docling ingestion fails with an OCR-related error and mentions `easyocr` is missing, this is likely due to a stale `uv` cache.
Docling ingestion can fail with an OCR-related error that mentions `easyocr` is missing.
This is likely due to a stale `uv` cache when you [install OpenRAG with `uvx`](/install-uvx).
`easyocr` is already included as a dependency in OpenRAG's `pyproject.toml`. Project-managed installations using `uv sync` and `uv run` always sync dependencies directly from your `pyproject.toml`, so they should have `easyocr` installed.
When you invoke OpenRAG with `uvx openrag`, `uvx` creates a cached, ephemeral environment that doesn't modify your project.
The location and path of this cache depends on your operating system.
For example, on macOS, this is typically a user cache directory, such as `/Users/USER_NAME/.cache/uv`.
If you're running OpenRAG with `uvx openrag`, `uvx` creates a cached, ephemeral environment that doesn't modify your project. This cache can become stale.
This cache can become stale, producing errors like missing dependencies.
On macOS, this cache directory is typically a user cache directory such as `/Users/USER_NAME/.cache/uv`.
1. [Exit the TUI](/tui).
1. To clear the uv cache, run:
2. Clear the `uv` cache:
```bash
uv cache clean
```
2. Start OpenRAG:
To clear the OpenRAG cache only, run:
```bash
uv cache clean openrag
```
3. Invoke OpenRAG to restart the TUI:
```bash
uvx openrag
```
If you don't need OCR, you can disable OCR-based processing in your ingestion settings to avoid requiring `easyocr`.
4. Click **Open App**, and then retry document ingestion.
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`.
If you don't need OCR, you can disable OCR-based processing in your [ingestion settings](/knowledge#knowledge-ingestion-settings) to avoid requiring `easyocr`.
## Upgrade fails due to Langflow container already exists {#langflow-container-already-exists-during-upgrade}
@ -122,7 +136,7 @@ To resolve this issue, do the following:
2. Retry the [upgrade](/upgrade).
3. If reinstalling the Langflow container doesn't resolve the issue, then you must [reset all containers](/manage-containers) or [reinstall OpenRAG](/reinstall).
3. If reinstalling the Langflow container doesn't resolve the issue, then you must [reset all containers](/manage-services) or [reinstall OpenRAG](/reinstall).
4. Retry the [upgrade](/upgrade).

6
docs/sidebars.js
View file

@ -42,7 +42,7 @@ const sidebars = {
},
{ type: "doc",
id: "get-started/docker",
label: "Deploy self-managed containers",
label: "Deploy self-managed services",
},
"get-started/upgrade",
"get-started/reinstall",
@ -52,8 +52,8 @@ const sidebars = {
"get-started/tui",
{
type: "doc",
id: "get-started/manage-containers",
label: "Manage containers",
id: "get-started/manage-services",
label: "Manage services",
},
{
type: "doc",