diff --git a/README.md b/README.md index 4cc99a71..f3b3e1d4 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ To launch OpenRAG with the TUI, do the following: The TUI opens and guides you through OpenRAG setup. -For the full TUI guide, see [TUI](https://docs.openr.ag/get-started/tui). +For the full TUI installation guide, see [TUI](https://docs.openr.ag/install). ## Docker installation diff --git a/docs/docs/_partial-onboarding.mdx b/docs/docs/_partial-onboarding.mdx index 3c5c031d..6fc5c87e 100644 --- a/docs/docs/_partial-onboarding.mdx +++ b/docs/docs/_partial-onboarding.mdx @@ -7,6 +7,8 @@ The first time you start OpenRAG, whether using the TUI or a `.env` file, you mu Values from onboarding can be changed later in the OpenRAG **Settings** page. +Choose one LLM provider and complete only those steps: + 1. Enable **Get API key from environment variable** to automatically enter your key from the TUI-generated `.env` file. diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index 56dace55..a43825bd 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -3,25 +3,24 @@ title: Install OpenRAG containers slug: /get-started/docker --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; -There are two different Docker Compose files. -They deploy the same applications and containers locally, but to different environments. +OpenRAG has two Docker Compose files. Both files deploy the same applications and containers locally, 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. +- [`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. -- [`docker-compose-cpu.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml) is a CPU-only version of OpenRAG for systems without GPU support. Use this Docker compose file for environments where GPU drivers aren't available. - -Both Docker deployments depend on `docling serve` to be running on port `5001` on the host machine. This enables [Mac MLX](https://opensource.apple.com/projects/mlx/) support for document processing. Installing OpenRAG with the TUI starts `docling serve` automatically, but for a Docker deployment you must manually start the `docling serve` process. +- [`docker-compose-cpu.yml`](https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml) is a CPU-only version of OpenRAG for systems without NVIDIA GPU support. Use this Docker Compose file for environments where GPU drivers aren't available. ## Prerequisites -- [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/) -- [uv](https://docs.astral.sh/uv/getting-started/installation/) -- [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/) installed -- [Docker Compose](https://docs.docker.com/compose/install/) installed. If you're using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands. +- Install [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/) +- Install [uv](https://docs.astral.sh/uv/getting-started/installation/) +- Install [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/) +- Install [Docker Compose](https://docs.docker.com/compose/install/). If using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands. - Create an [OpenAI API key](https://platform.openai.com/api-keys). This key is **required** to start OpenRAG, but you can choose a different model provider during [Application Onboarding](#application-onboarding). -- Optional: GPU support requires an NVIDIA GPU with CUDA support and compatible NVIDIA drivers installed on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment. +- Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment. ## Install OpenRAG with Docker Compose @@ -49,8 +48,7 @@ To install OpenRAG with Docker Compose, do the following: touch .env ``` -4. Set environment variables. The Docker Compose files will be populated with values from your `.env`. -The following values are **required** to be set: +4. The Docker Compose files are populated with the values from your .env. The following values must be set: ```bash OPENSEARCH_PASSWORD=your_secure_password @@ -63,7 +61,8 @@ The following values are **required** to be set: For more information on configuring OpenRAG with environment variables, see [Environment variables](/reference/configuration). 5. Start `docling serve` on the host machine. - Both Docker deployments depend on `docling serve` to be running on port `5001` on the host machine. This enables [Mac MLX](https://opensource.apple.com/projects/mlx/) support for document processing. + OpenRAG Docker installations require that `docling serve` is running on port 5001 on the host machine. + This enables [Mac MLX](https://opensource.apple.com/projects/mlx/) support for document processing. ```bash uv run python scripts/docling_ctl.py start --port 5001 @@ -74,7 +73,7 @@ The following values are **required** to be set: uv run python scripts/docling_ctl.py status ``` - Successful result: + Make sure the response shows that `docling serve` is running, for example: ```bash Status: running Endpoint: http://127.0.0.1:5001 @@ -84,16 +83,21 @@ The following values are **required** to be set: 7. Deploy OpenRAG locally with Docker Compose based on your deployment type. - For GPU-enabled systems, run the following commands: + + ```bash docker compose build docker compose up -d - ``` - - For environments without GPU support, run: + ``` + + + ```bash docker compose -f docker-compose-cpu.yml up -d ``` + + + The OpenRAG Docker Compose file starts five containers: | Container Name | Default Address | Purpose | @@ -110,7 +114,7 @@ The following values are **required** to be set: docker compose ps ``` - You can now access the application at: + You can now access OpenRAG at the following endpoints: - **Frontend**: http://localhost:3000 - **Backend API**: http://localhost:8000 @@ -129,7 +133,7 @@ uv run python scripts/docling_ctl.py stop ## Container management commands Manage your OpenRAG containers with the following commands. -These commands are also available in the TUI's [Status menu](/get-started/tui#status). +These commands are also available in the TUI's [Status menu](/install#status). ### Upgrade containers diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index d9d947f1..355423cf 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -9,16 +9,24 @@ import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; [Install the OpenRAG Python wheel](#install-python-wheel), and then run the [OpenRAG Terminal User Interface(TUI)](#setup) to start your OpenRAG deployment with a guided setup process. -If you prefer running Docker commands and manually editing `.env` files, see [Deploy with Docker](/get-started/docker). +The OpenRAG Terminal User Interface (TUI) allows you to set up, configure, and monitor your OpenRAG deployment directly from the terminal, on any operating system. + +![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg) + +Instead of starting OpenRAG using Docker commands and manually editing values in the `.env` file, the TUI walks you through the setup. It prompts for variables where required, creates a `.env` file for you, and then starts OpenRAG. + +Once OpenRAG is running, use the TUI to monitor your application, control your containers, and retrieve logs. + +If you prefer running Docker commands and manually editing `.env` files, see [Install with Docker](/get-started/docker). ## Prerequisites -- [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/) -- [uv](https://docs.astral.sh/uv/getting-started/installation/) -- [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/) installed -- [Docker Compose](https://docs.docker.com/compose/install/) installed. If using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands. +- Install [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/) +- Install [uv](https://docs.astral.sh/uv/getting-started/installation/) +- Install [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/) +- Install [Docker Compose](https://docs.docker.com/compose/install/). If using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands. - Create an [OpenAI API key](https://platform.openai.com/api-keys). This key is **required** to start OpenRAG, but you can choose a different model provider during [Application Onboarding](#application-onboarding). -- Optional: GPU support requires an NVIDIA GPU with [CUDA](https://docs.nvidia.com/cuda/) support and compatible NVIDIA drivers installed on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment. +- Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment. ## Install the OpenRAG Python wheel {#install-python-wheel} @@ -57,7 +65,7 @@ The OpenRAG wheel installs the Terminal User Interface (TUI) for configuring and uv run openrag ``` -5. Continue with [Setup OpenRAG with the TUI](#setup). +5. Continue with [Set up OpenRAG with the TUI](#setup). ## Set up OpenRAG with the TUI {#setup} @@ -65,19 +73,19 @@ The TUI creates a `.env` file in your OpenRAG directory root and starts OpenRAG. If the TUI detects a `.env` file in the OpenRAG root directory, it sources any variables from the `.env` file. If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path. -**Basic Setup** generates all of the required values for OpenRAG except the OpenAI API key. -**Basic Setup** does not set up OAuth connections for ingestion from cloud providers. -For OAuth setup, use **Advanced Setup**. - -**Basic Setup** and **Advanced Setup** enforce the same authentication settings for the Langflow server, but manage document access differently. For more information, see [Authentication and document access](/knowledge#auth). - + **Basic Setup** generates all of the required values for OpenRAG except the OpenAI API key. + **Basic Setup** does not set up OAuth connections for ingestion from cloud providers. + For OAuth setup, use **Advanced Setup**. + For information about the difference between basic (no auth) and OAuth in OpenRAG, see [Authentication and document access](/knowledge#auth). + 1. To install OpenRAG with **Basic Setup**, click **Basic Setup** or press 1. 2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow. 3. Paste your OpenAI API key in the OpenAI API key field. 4. Click **Save Configuration**. + Your passwords are saved in the `.env` file used to start OpenRAG. 5. To start OpenRAG, click **Start Container Services**. Startup pulls container images and runs them, so it can take some time. When startup is complete, the TUI displays the following: @@ -126,4 +134,60 @@ For OAuth setup, use **Advanced Setup**. - \ No newline at end of file + + +## Manage OpenRAG containers with the TUI + +After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers. + +### Start container services + +Click **Start Container Services** to start the OpenRAG containers. +The TUI 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. +The TUI then pulls the images and deploys the containers with the following command. +```bash +docker compose up -d +``` + +If images are missing, the TUI runs `docker compose pull`, then runs `docker compose up -d`. + +### Start native services + +A "native" service in OpenRAG refers to a service run natively on your machine, and not within a container. +The `docling serve` process is a native service in OpenRAG, because it's a document processing service that is run on your local machine, and controlled separately from the containers. + +To start or stop `docling serve` or any other native services, in the TUI main menu, click **Start Native Services** or **Stop Native Services**. + +To view the status, port, or PID of a native service, in the TUI main menu, click [Status](#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. + +To view streaming logs, select the container you want to view, and press l. +To copy your logs, click **Copy to Clipboard**. + +To **upgrade** your containers, click **Upgrade**. +**Upgrade** runs `docker compose pull` and then `docker compose up -d --force-recreate`. +The first command pulls the latest images of OpenRAG. +The second command recreates the containers with your data persisted. + +To **reset** your containers, click **Reset**. +Reset gives you a completely fresh start. +Reset deletes all of your data, including OpenSearch data, uploaded documents, and authentication. +**Reset** runs two commands. +It first stops and removes all containers, volumes, and local images. +``` +docker compose down --volumes --remove-orphans --rmi local +``` + +When the first command is complete, OpenRAG removes any additional Docker objects with `prune`. + +``` +docker system prune -f +``` + +## Diagnostics + +The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security. \ No newline at end of file diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx index 942433b5..80259617 100644 --- a/docs/docs/get-started/quickstart.mdx +++ b/docs/docs/get-started/quickstart.mdx @@ -11,33 +11,30 @@ Get started with OpenRAG by loading your knowledge, swapping out your language m ## Prerequisites -- [Install and start OpenRAG](/install) +- Install and start OpenRAG with the [TUI](/install) or [Docker](/get-started/docker) -## Find your way around +## Load and chat with your own documents 1. In OpenRAG, click