diff --git a/docs/docs/core-components/ingestion.mdx b/docs/docs/core-components/ingestion.mdx
index 3e991176..33fb1420 100644
--- a/docs/docs/core-components/ingestion.mdx
+++ b/docs/docs/core-components/ingestion.mdx
@@ -64,11 +64,11 @@ To enable multiple connectors, you must register an app and generate credentials
-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**.
-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:
diff --git a/docs/docs/core-components/knowledge.mdx b/docs/docs/core-components/knowledge.mdx
index 3edf5a55..86604cbb 100644
--- a/docs/docs/core-components/knowledge.mdx
+++ b/docs/docs/core-components/knowledge.mdx
@@ -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
- 1. To install OpenRAG with **Basic Setup**, click **Basic Setup** or press 1.
- 2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow.
+ 1. In the TUI, click **Basic Setup** or press 1.
- 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).
+
- 1. To install OpenRAG with **Advanced Setup**, click **Advanced Setup** or press 2.
- 2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow.
+ 1. In the TUI, click **Advanced Setup** or press 2.
- 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).
+
+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).
+
-## 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 l.
-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)
\ No newline at end of file
diff --git a/docs/docs/get-started/manage-containers.mdx b/docs/docs/get-started/manage-containers.mdx
deleted file mode 100644
index 584701fa..00000000
--- a/docs/docs/get-started/manage-containers.mdx
+++ /dev/null
@@ -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)
\ No newline at end of file
diff --git a/docs/docs/get-started/manage-services.mdx b/docs/docs/get-started/manage-services.mdx
new file mode 100644
index 00000000..082ee59a
--- /dev/null
+++ b/docs/docs/get-started/manage-services.mdx
@@ -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 l.
+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)
\ No newline at end of file
diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx
index 2359d6ae..5789e3ed 100644
--- a/docs/docs/get-started/quickstart.mdx
+++ b/docs/docs/get-started/quickstart.mdx
@@ -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.
-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 **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 **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}
diff --git a/docs/docs/get-started/reinstall.mdx b/docs/docs/get-started/reinstall.mdx
index be20b6db..c74a8da9 100644
--- a/docs/docs/get-started/reinstall.mdx
+++ b/docs/docs/get-started/reinstall.mdx
@@ -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
diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx
index 24bc4bc0..98fe5e9d 100644
--- a/docs/docs/get-started/tui.mdx
+++ b/docs/docs/get-started/tui.mdx
@@ -7,10 +7,10 @@ The OpenRAG Terminal User Interface (TUI) provides a simplified and guided exper
-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)
\ No newline at end of file
+* [Manage services](/manage-services)
\ No newline at end of file
diff --git a/docs/docs/get-started/uninstall.mdx b/docs/docs/get-started/uninstall.mdx
index e438fdd4..f9a3cadb 100644
--- a/docs/docs/get-started/uninstall.mdx
+++ b/docs/docs/get-started/uninstall.mdx
@@ -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).
\ No newline at end of file
+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).
\ No newline at end of file
diff --git a/docs/docs/get-started/upgrade.mdx b/docs/docs/get-started/upgrade.mdx
index b81063da..e2842c33 100644
--- a/docs/docs/get-started/upgrade.mdx
+++ b/docs/docs/get-started/upgrade.mdx
@@ -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
diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx
index 412108cb..8df6f1ae 100644
--- a/docs/docs/reference/configuration.mdx
+++ b/docs/docs/reference/configuration.mdx
@@ -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 |
|----------|---------|-------------|
diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx
index 70a80d35..4a0ad0d0 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -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).
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 736a658e..f4f7ebfd 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -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",