From 69a85d3e4815b9b19538ab79a5205f04eb255c48 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 14:36:01 -0400 Subject: [PATCH 1/6] move-docker-to-its-own-page --- docs/docs/get-started/docker.mdx | 98 ++++++++++++++++++++++++-------- 1 file changed, 73 insertions(+), 25 deletions(-) diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index a394bc69..84f0fca6 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -1,40 +1,88 @@ --- -title: Docker Deployment +title: Docker deployment slug: /get-started/docker --- -# Docker Deployment +There are two different Docker Compose files. +They deploy the same applications and containers, but to different environments. -## Standard Deployment +- [`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. -```bash -# Build and start all services -docker compose build -docker compose up -d -``` +- [`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. -## CPU-Only Deployment +To install OpenRAG with Docker Compose: -For environments without GPU support: +1. Clone the OpenRAG repository. + ```bash + git clone https://github.com/langflow-ai/openrag.git + cd openrag + ``` -```bash -docker compose -f docker-compose-cpu.yml up -d -``` +2. Copy the example `.env` file that is included in the repository root. + The example file includes all environment variables with comments to guide you in finding and setting their values. + ```bash + cp .env.example .env + ``` -## Force Rebuild + Alternatively, create a new `.env` file in the repository root. + ``` + touch .env + ``` -If you need to reset state or rebuild everything: +3. Set environment variables. The Docker Compose files are populated with values from your `.env`, so the following values are **required** to be set: + + ```bash + OPENSEARCH_PASSWORD=your_secure_password + OPENAI_API_KEY=your_openai_api_key + + LANGFLOW_SUPERUSER=admin + LANGFLOW_SUPERUSER_PASSWORD=your_langflow_password + LANGFLOW_SECRET_KEY=your_secret_key + ``` + For more information on configuring OpenRAG with environment variables, see [Environment variables](/configure/configuration). + For additional configuration values, including `config.yaml`, see [Configuration](/configure/configuration). + +4. Deploy OpenRAG with Docker Compose based on your deployment type. + + For GPU-enabled systems, run the following command: + ```bash + docker compose up -d + ``` + + For CPU-only systems, run the following command: + ```bash + docker compose -f docker-compose-cpu.yml up -d + ``` + + The OpenRAG Docker Compose file starts five containers: + | Container Name | Default Address | Purpose | + |---|---|---| + | OpenRAG Backend | http://localhost:8000 | FastAPI server and core functionality. | + | OpenRAG Frontend | http://localhost:3000 | React web interface for users. | + | Langflow | http://localhost:7860 | AI workflow engine and flow management. | + | OpenSearch | http://localhost:9200 | Vector database for document storage. | + | OpenSearch Dashboards | http://localhost:5601 | Database administration interface. | + +5. Verify installation by confirming all services are running. + + ```bash + docker compose ps + ``` + + You can now access the application at: + + - **Frontend**: http://localhost:3000 + - **Backend API**: http://localhost:8000 + - **Langflow**: http://localhost:7860 + +Continue with the [Quickstart](/quickstart). + +## Rebuild all Docker containers + +If you need to reset state and rebuild all of your containers, run the following command. +Your OpenSearch and Langflow databases will be lost. +Documents stored in the `./documents` directory will persist, since the directory is mounted as a volume in the OpenRAG backend container. ```bash docker compose up --build --force-recreate --remove-orphans ``` - -## Service URLs - -After deployment, services are available at: - -- Frontend: http://localhost:3000 -- Backend API: http://localhost:8000 -- Langflow: http://localhost:7860 -- OpenSearch: http://localhost:9200 -- OpenSearch Dashboards: http://localhost:5601 From 030b73c6abc5b0a0ace65367ce5db001e7c53b6b Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 14:37:01 -0400 Subject: [PATCH 2/6] links --- docs/docs/get-started/install.mdx | 122 +----------------------------- 1 file changed, 4 insertions(+), 118 deletions(-) diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index dcb5c5f1..a9192cf4 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -10,7 +10,7 @@ OpenRAG can be installed in multiple ways: * [**Python wheel**](#install-python-wheel): Install the OpenRAG Python wheel and use the [OpenRAG Terminal User Interface (TUI)](/get-started/tui) to install, run, and configure your OpenRAG deployment without running Docker commands. -* [**Docker Compose**](#install-and-run-docker): Clone the OpenRAG repository and deploy OpenRAG with Docker Compose, including all services and dependencies. +* [**Docker Compose**](/docker): Clone the OpenRAG repository and deploy OpenRAG with Docker Compose, including all services and dependencies. ## Prerequisites @@ -79,46 +79,8 @@ For more information on virtual environments, see [uv](https://docs.astral.sh/uv Command completed successfully ``` -7. To open the OpenRAG application, click **Open App**, press 6, or navigate to `http://localhost:3000`. - The application opens. -8. Select your language model and embedding model provider, and complete the required fields. - **Your provider can only be selected once, and you must use the same provider for your language model and embedding model.** - The language model can be changed, but the embeddings model cannot be changed. - To change your provider selection, you must restart OpenRAG and delete the `config.yml` file. - - - - 9. If you already entered a value for `OPENAI_API_KEY` in the TUI in Step 5, enable **Get API key from environment variable**. - 10. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. - 11. To load 2 sample PDFs, enable **Sample dataset**. - This is recommended, but not required. - 12. Click **Complete**. - - - - 9. Complete the fields for **watsonx.ai API Endpoint**, **IBM API key**, and **IBM Project ID**. - These values are found in your IBM watsonx deployment. - 10. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. - 11. To load 2 sample PDFs, enable **Sample dataset**. - This is recommended, but not required. - 12. Click **Complete**. - - - - 9. Enter your Ollama server's base URL address. - The default Ollama server address is `http://localhost:11434`. - Since OpenRAG is running in a container, you may need to change `localhost` to access services outside of the container. For example, change `http://localhost:11434` to `http://host.docker.internal:11434` to connect to Ollama. - OpenRAG automatically sends a test connection to your Ollama server to confirm connectivity. - 10. Select the **Embedding Model** and **Language Model** your Ollama server is running. - OpenRAG automatically lists the available models from your Ollama server. - 11. To load 2 sample PDFs, enable **Sample dataset**. - This is recommended, but not required. - 12. Click **Complete**. - - - - -13. Continue with the [Quickstart](/quickstart). +7. To open the OpenRAG application, click **Open App** or press 6. +8. Continue with the [Quickstart](/quickstart). ### Advanced Setup {#advanced-setup} @@ -138,80 +100,4 @@ The `LANGFLOW_PUBLIC_URL` controls where the Langflow web interface can be acces The `WEBHOOK_BASE_URL` controls where the endpoint for `/connectors/CONNECTOR_TYPE/webhook` will be available. This connection enables real-time document synchronization with external services. -For example, for Google Drive file synchronization the webhook URL is `/connectors/google_drive/webhook`. - -## Docker {#install-and-run-docker} - -There are two different Docker Compose files. -They deploy the same applications and containers, but to 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-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. - -To install OpenRAG with Docker Compose: - -1. Clone the OpenRAG repository. - ```bash - git clone https://github.com/langflow-ai/openrag.git - cd openrag - ``` - -2. Copy the example `.env` file that is included in the repository root. - The example file includes all environment variables with comments to guide you in finding and setting their values. - ```bash - cp .env.example .env - ``` - - Alternatively, create a new `.env` file in the repository root. - ``` - touch .env - ``` - -3. Set environment variables. The Docker Compose files are populated with values from your `.env`, so the following values are **required** to be set: - - ```bash - OPENSEARCH_PASSWORD=your_secure_password - OPENAI_API_KEY=your_openai_api_key - - LANGFLOW_SUPERUSER=admin - LANGFLOW_SUPERUSER_PASSWORD=your_langflow_password - LANGFLOW_SECRET_KEY=your_secret_key - ``` - For more information on configuring OpenRAG with environment variables, see [Environment variables](/configure/configuration). - For additional configuration values, including `config.yaml`, see [Configuration](/configure/configuration). - -4. Deploy OpenRAG with Docker Compose based on your deployment type. - - For GPU-enabled systems, run the following command: - ```bash - docker compose up -d - ``` - - For CPU-only systems, run the following command: - ```bash - docker compose -f docker-compose-cpu.yml up -d - ``` - - The OpenRAG Docker Compose file starts five containers: - | Container Name | Default Address | Purpose | - |---|---|---| - | OpenRAG Backend | http://localhost:8000 | FastAPI server and core functionality. | - | OpenRAG Frontend | http://localhost:3000 | React web interface for users. | - | Langflow | http://localhost:7860 | AI workflow engine and flow management. | - | OpenSearch | http://localhost:9200 | Vector database for document storage. | - | OpenSearch Dashboards | http://localhost:5601 | Database administration interface. | - -5. Verify installation by confirming all services are running. - - ```bash - docker compose ps - ``` - - You can now access the application at: - - - **Frontend**: http://localhost:3000 - - **Backend API**: http://localhost:8000 - - **Langflow**: http://localhost:7860 - -Continue with the Quickstart. \ No newline at end of file +For example, for Google Drive file synchronization the webhook URL is `/connectors/google_drive/webhook`. \ No newline at end of file From d88730acb3234ad7d2fe3ca9846c00c93871fc36 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 14:37:47 -0400 Subject: [PATCH 3/6] link --- docs/docs/get-started/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index a9192cf4..e78f4df5 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -10,7 +10,7 @@ OpenRAG can be installed in multiple ways: * [**Python wheel**](#install-python-wheel): Install the OpenRAG Python wheel and use the [OpenRAG Terminal User Interface (TUI)](/get-started/tui) to install, run, and configure your OpenRAG deployment without running Docker commands. -* [**Docker Compose**](/docker): Clone the OpenRAG repository and deploy OpenRAG with Docker Compose, including all services and dependencies. +* [**Docker Compose**](get-started/docker): Clone the OpenRAG repository and deploy OpenRAG with Docker Compose, including all services and dependencies. ## Prerequisites From a88c6a9ed5dfce9468db21d1a42545d143fbd25c Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 14:44:34 -0400 Subject: [PATCH 4/6] revert-onboarding --- docs/docs/get-started/install.mdx | 42 +++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index e78f4df5..27cafb44 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -79,8 +79,46 @@ For more information on virtual environments, see [uv](https://docs.astral.sh/uv Command completed successfully ``` -7. To open the OpenRAG application, click **Open App** or press 6. -8. Continue with the [Quickstart](/quickstart). +7. To open the OpenRAG application, click **Open App**, press 6, or navigate to `http://localhost:3000`. + The application opens. +8. Select your language model and embedding model provider, and complete the required fields. + **Your provider can only be selected once, and you must use the same provider for your language model and embedding model.** + The language model can be changed, but the embeddings model cannot be changed. + To change your provider selection, you must restart OpenRAG and delete the `config.yml` file. + + + + 9. If you already entered a value for `OPENAI_API_KEY` in the TUI in Step 5, enable **Get API key from environment variable**. + 10. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. + 11. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 12. Click **Complete**. + + + + 9. Complete the fields for **watsonx.ai API Endpoint**, **IBM API key**, and **IBM Project ID**. + These values are found in your IBM watsonx deployment. + 10. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. + 11. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 12. Click **Complete**. + + + + 9. Enter your Ollama server's base URL address. + The default Ollama server address is `http://localhost:11434`. + Since OpenRAG is running in a container, you may need to change `localhost` to access services outside of the container. For example, change `http://localhost:11434` to `http://host.docker.internal:11434` to connect to Ollama. + OpenRAG automatically sends a test connection to your Ollama server to confirm connectivity. + 10. Select the **Embedding Model** and **Language Model** your Ollama server is running. + OpenRAG automatically lists the available models from your Ollama server. + 11. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 12. Click **Complete**. + + + + +13. Continue with the [Quickstart](/quickstart). ### Advanced Setup {#advanced-setup} From 70a1d0b19e3b96268d20db64ff5239680c45c40d Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 20:48:14 -0400 Subject: [PATCH 5/6] init-content --- docs/docs/get-started/tui.mdx | 52 ++++++++++++++++++++++++++++------- 1 file changed, 42 insertions(+), 10 deletions(-) diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx index 2f0a048d..44fe8a66 100644 --- a/docs/docs/get-started/tui.mdx +++ b/docs/docs/get-started/tui.mdx @@ -1,22 +1,60 @@ --- -title: Terminal Interface (TUI) +title: Terminal User Interface (TUI) commands slug: /get-started/tui --- # OpenRAG TUI Guide -The OpenRAG Terminal User Interface (TUI) provides a streamlined way to set up, configure, and monitor your OpenRAG deployment directly from the terminal. +The OpenRAG Terminal User Interface (TUI) provides a streamlined way 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) -## Launch +The TUI offers an easier way to use OpenRAG without sacrificing control. +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. + +## Start the TUI + +To start the TUI, run the following commands from the directory where you installed OpenRAG. +For more information, see [Install OpenRAG](/install). ```bash uv sync uv run openrag ``` -## Features +The TUI Welcome Screen offers basic and advanced setup options. +For more information on setup values during installation, see [Install OpenRAG](/install). + +## Container management + +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** screen + +### Diagnostics ### Welcome Screen - Quick setup options: basic (no auth) or advanced (OAuth) @@ -56,11 +94,5 @@ uv run openrag - Q: quit - Number keys (1-4): quick access to main screens -## Benefits -1. Simplified setup without manual file edits -2. Clear visual feedback and error messages -3. Integrated monitoring and control -4. Cross-platform: Linux, macOS, Windows -5. Fully terminal-based; no browser required From 4de9a1fe93af55a20b0f9a57eb81fe5160b71c26 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Mon, 29 Sep 2025 21:24:18 -0400 Subject: [PATCH 6/6] tui-more-information --- docs/docs/get-started/tui.mdx | 70 +++++++++++++++++------------------ 1 file changed, 33 insertions(+), 37 deletions(-) diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx index 44fe8a66..5ca4e934 100644 --- a/docs/docs/get-started/tui.mdx +++ b/docs/docs/get-started/tui.mdx @@ -27,6 +27,17 @@ uv run openrag The TUI Welcome Screen offers basic and advanced setup options. For more information on setup values during installation, see [Install OpenRAG](/install). +## Navigation + +The TUI accepts mouse input or keyboard commands. + +- Arrow keys: move between options +- Tab/Shift+Tab: switch fields and buttons +- Enter: select/confirm +- Escape: back +- Q: quit +- Number keys (1-4): quick access to main screens + ## Container management The TUI can deploy, manage, and upgrade your OpenRAG containers. @@ -52,47 +63,32 @@ To view the status, port, or PID of a native service, in the TUI main menu, clic ### Status -The **Status** screen +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. -### Diagnostics +To view streaming logs, select the container you want to view, and press l. +To copy your logs, click **Copy to Clipboard**. -### Welcome Screen -- Quick setup options: basic (no auth) or advanced (OAuth) -- Service monitoring: container status at a glance -- Quick actions: diagnostics, logs, configuration +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. -### Configuration Screen -- Environment variables: guided forms for required settings -- API keys: secure input with validation -- OAuth setup: Google and Microsoft -- Document paths: configure ingestion directories -- Auto-save: generates and updates `.env` +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 +``` -### Service Monitor -- Container status: real-time state of services -- Resource usage: CPU, memory, network -- Service control: start/stop/restart -- Health checks: health indicators for all components - -### Log Viewer -- Live logs: stream logs across services -- Filtering: by service (backend, frontend, Langflow, OpenSearch) -- Levels: DEBUG/INFO/WARNING/ERROR -- Export: save logs for later analysis - -### Diagnostics -- System checks: Docker/Podman availability and configuration -- Environment validation: verify required variables -- Network tests: connectivity between services -- Performance metrics: system capacity and recommendations - -## Navigation -- Arrow keys: move between options -- Tab/Shift+Tab: switch fields and buttons -- Enter: select/confirm -- Escape: back -- Q: quit -- Number keys (1-4): quick access to main screens +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