From 8e4a68a32c06bd53944725e8c2d07c9b58eeab85 Mon Sep 17 00:00:00 2001 From: zznate Date: Wed, 1 Oct 2025 14:44:19 +1300 Subject: [PATCH 01/19] bug: fixes #159 by adding more memory to npm invocations --- Dockerfile.langflow | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile.langflow b/Dockerfile.langflow index 6d868f14..1ad990ec 100644 --- a/Dockerfile.langflow +++ b/Dockerfile.langflow @@ -33,8 +33,8 @@ RUN uv sync --frozen --no-install-project --no-editable --extra postgresql # Build frontend WORKDIR /app/src/frontend -RUN npm ci && \ - npm run build && \ +RUN NODE_OPTIONS=--max_old_space_size=1792 npm ci && \ + NODE_OPTIONS=--max_old_space_size=1792 npm run build && \ mkdir -p /app/src/backend/base/langflow/frontend && \ cp -r build/* /app/src/backend/base/langflow/frontend/ From f7c1b7f33f4ba71469e27ad12768ad5f8441e2f6 Mon Sep 17 00:00:00 2001 From: zznate Date: Wed, 1 Oct 2025 15:15:40 +1300 Subject: [PATCH 02/19] bug: up memory limit to 4096 for npm commands --- Dockerfile.langflow | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile.langflow b/Dockerfile.langflow index 1ad990ec..2acb4877 100644 --- a/Dockerfile.langflow +++ b/Dockerfile.langflow @@ -33,8 +33,8 @@ RUN uv sync --frozen --no-install-project --no-editable --extra postgresql # Build frontend WORKDIR /app/src/frontend -RUN NODE_OPTIONS=--max_old_space_size=1792 npm ci && \ - NODE_OPTIONS=--max_old_space_size=1792 npm run build && \ +RUN NODE_OPTIONS=--max_old_space_size=4096 npm ci && \ + NODE_OPTIONS=--max_old_space_size=4096 npm run build && \ mkdir -p /app/src/backend/base/langflow/frontend && \ cp -r build/* /app/src/backend/base/langflow/frontend/ From 9f8c4462025d16862e6bb838604af9fad778318d Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 22:24:43 -0400 Subject: [PATCH 03/19] peer-review-install-page --- docs/docs/_partial-onboarding.mdx | 49 +++++++ docs/docs/get-started/docker.mdx | 3 +- docs/docs/get-started/install.mdx | 163 +++++++++------------- docs/docs/get-started/what-is-openrag.mdx | 6 +- docs/sidebars.js | 12 +- docs/src/css/custom.css | 29 ++++ 6 files changed, 153 insertions(+), 109 deletions(-) create mode 100644 docs/docs/_partial-onboarding.mdx diff --git a/docs/docs/_partial-onboarding.mdx b/docs/docs/_partial-onboarding.mdx new file mode 100644 index 00000000..ce0d6582 --- /dev/null +++ b/docs/docs/_partial-onboarding.mdx @@ -0,0 +1,49 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +### Application onboarding + +The first time you start OpenRAG, whether using the TUI or a `.env` file, you must complete application onboarding. + +Values input during onboarding can be changed later in the OpenRAG **Settings** page, except for the language model and embedding model _provider_. +**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 completely reinstall OpenRAG. + + + + 1. Enable **Get API key from environment variable** to automatically enter your key from the TUI-generated `.env` file. + 2. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. + 3. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 4. Click **Complete**. + 5. Continue with the [Quickstart](/quickstart). + + + + 1. Complete the fields for **watsonx.ai API Endpoint**, **IBM API key**, and **IBM Project ID**. + These values are found in your IBM watsonx deployment. + 2. Under **Advanced settings**, select your **Embedding Model** and **Language Model**. + 3. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 4. Click **Complete**. + 5. Continue with the [Quickstart](/quickstart). + + + + :::tip + Ollama is not included with OpenRAG. To install Ollama, see the [Ollama documentation](https://docs.ollama.com/). + ::: + 1. 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. + 2. Select the **Embedding Model** and **Language Model** your Ollama server is running. + OpenRAG automatically lists the available models from your Ollama server. + 3. To load 2 sample PDFs, enable **Sample dataset**. + This is recommended, but not required. + 4. Click **Complete**. + 5. Continue with the [Quickstart](/quickstart). + + + diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index 84f0fca6..607846d7 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -1,5 +1,5 @@ --- -title: Docker deployment +title: Deploy with Docker slug: /get-started/docker --- @@ -40,7 +40,6 @@ To install OpenRAG with Docker Compose: 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. diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 27cafb44..f2315a0c 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -1,16 +1,15 @@ --- -title: Install OpenRAG +title: Install Python wheel slug: /install --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; -OpenRAG can be installed in multiple ways: +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. -* [**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**](get-started/docker): Clone the OpenRAG repository and deploy OpenRAG with Docker Compose, including all services and dependencies. +If you prefer running Docker commands and manually editing `.env` files, see [Deploy with Docker](/docker). ## Prerequisites @@ -18,24 +17,23 @@ OpenRAG can be installed in multiple ways: - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman.io/docs/installation) 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. -- For GPU support: (TBD) +- [OpenAI API key](https://platform.openai.com/api-keys) +- 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. -## Python wheel {#install-python-wheel} +## Install Python wheel {#install-python-wheel} -The Python wheel is currently available internally, but will be available on PyPI at launch. -The wheel installs the OpenRAG wheel, which includes the TUI for installing, running, and managing OpenRAG. -For more information on virtual environments, see [uv](https://docs.astral.sh/uv/pip/environments). - -1. Create a new project with a virtual environment using [uv](https://docs.astral.sh/uv/pip/environments). +The OpenRAG Python wheel is available on PyPI. +The wheel includes the TUI for installing, running, and managing OpenRAG. +1. Create a new project with a virtual environment using `uv`. + For more information on virtual environments, see the [uv documentation](https://docs.astral.sh/uv/pip/environments). ```bash uv init YOUR_PROJECT_NAME cd YOUR_PROJECT_NAME ``` 2. Add the OpenRAG wheel to your project and install it in the virtual environment. - Replace `PATH/TO/` and `VERSION` with your OpenRAG wheel location and version. ```bash - uv add PATH/TO/openrag-VERSION-py3-none-any.whl + uv add openrag ``` 3. Ensure all dependencies are installed and updated in your virtual environment. ```bash @@ -47,95 +45,62 @@ For more information on virtual environments, see [uv](https://docs.astral.sh/uv uv run openrag ``` - The OpenRAG TUI opens. +## Setup OpenRAG with the TUI -5. To install OpenRAG with Basic Setup, click **Basic Setup** or press 1. Basic Setup does not set up OAuth connections for ingestion from Google Drive, OneDrive, or AWS. For OAuth setup, see [Advanced Setup](#advanced-setup). - The TUI prompts you for the required startup values. - Click **Generate Passwords** to autocomplete fields that contain **Auto-generated Secure Password**, or bring your own passwords. -
- Where do I find the required startup values? - - | Variable | Where to Find | Description | - |----------|---------------|-------------| - | `OPENSEARCH_PASSWORD` | Auto-generated secure password | The password for OpenSearch database access. Must be at least 8 characters and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character. | - | `OPENAI_API_KEY` | [OpenAI Platform](https://platform.openai.com/api-keys) | API key from your OpenAI account. | - | `LANGFLOW_SUPERUSER` | User generated | Username for Langflow admin access. For more, see [Langflow docs](https://docs.langflow.org/api-keys-and-authentication#langflow-superuser). | - | `LANGFLOW_SUPERUSER_PASSWORD` | Auto-generated secure password | Password for Langflow admin access. For more, see the [Langflow docs](https://docs.langflow.org/api-keys-and-authentication#langflow-superuser). | - | `LANGFLOW_SECRET_KEY` | Auto-generated secure key | Secret key for Langflow security. For more, see the [Langflow docs](https://docs.langflow.org/api-keys-and-authentication#langflow-secret-key). | - | `LANGFLOW_AUTO_LOGIN` | Auto-generated or manual | Auto-login configuration. For more, see the [Langflow docs](https://docs.langflow.org/api-keys-and-authentication#langflow-auto-login). | - | `LANGFLOW_NEW_USER_IS_ACTIVE` | Langflow | New user activation setting. For more, see the [Langflow docs](https://docs.langflow.org/api-keys-and-authentication#langflow-new-user-is-active). | - | `LANGFLOW_ENABLE_SUPERUSER_CLI` | Langflow server | Superuser CLI access setting. For more, see the [Langflow docs](https://docs.langflow.org/api-keys-and-authentication#langflow-enable-superuser-cli). | - | `DOCUMENTS_PATH` | Set your local path | Path to your document storage directory. | - -
- - To complete credentials, click **Save Configuration**. +**Basic Setup** completes or auto-generates most of the required values to start OpenRAG. +**Basic Setup** does not set up OAuth connections for ingestion from Google Drive, OneDrive, or AWS. +For OAuth setup, use **Advanced Setup**. -6. To start OpenRAG with your credentials, click **Start Container Services**. - Startup pulls container images and starts them, so it can take some time. - The operation has completed when the **Close** button is available and the terminal displays: - ```bash - Services started successfully - Command completed successfully - ``` +If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path. +If the TUI detects a `.env` file in the OpenRAG root directory, it will source any variables from the `.env` file. + + -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. + 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**. + 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: + ```bash + Services started successfully + Command completed successfully + ``` + 6. To open the OpenRAG application, click **Open App**. + 7. 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. + 3. Paste your OpenAI API key in the OpenAI API key field. + 4. Add your client and secret values for Google, Azure, or AWS OAuth. + These values can be found in your OAuth provider. + 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 Container Services**. + Startup pulls container images and runs them, so it can take some time. + When startup is complete, the TUI displays the following: + ```bash + Services started successfully + Command completed successfully + ``` + 8. To open the OpenRAG application, click **Open App**, press 6, or navigate to `http://localhost:3000`. + You will be presented with your provider's OAuth sign-in screen, and be redirected to the redirect URI after sign-in. + Continue with Application Onboarding. - - - 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**. + Two additional variables are available for Advanced Setup: + + The `LANGFLOW_PUBLIC_URL` controls where the Langflow web interface can be accessed. This is where users interact with their flows in a browser. + + 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`. - + 9. Continue with [Application Onboarding](#application-onboarding). + -13. Continue with the [Quickstart](/quickstart). - -### Advanced Setup {#advanced-setup} - -**Advanced Setup** includes the required values from **Basic Setup**, with additional settings for OAuth credentials. -If the OpenRAG TUI detects OAuth credentials, it enforces the Advanced Setup path. -1. Add your client and secret values for Google, Azure, or AWS OAuth. -These values can be found in your OAuth provider. -2. 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. -3. To open the OpenRAG application, click **Open App** or press 6. -You will be presented with your provider's OAuth sign-in screen, and be redirected to the redirect URI after sign-in. - -Two additional variables are available for Advanced Setup: - -The `LANGFLOW_PUBLIC_URL` controls where the Langflow web interface can be accessed. This is where users interact with their flows in a browser. - -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`. \ No newline at end of file + \ No newline at end of file diff --git a/docs/docs/get-started/what-is-openrag.mdx b/docs/docs/get-started/what-is-openrag.mdx index d52fe12f..7d2340d0 100644 --- a/docs/docs/get-started/what-is-openrag.mdx +++ b/docs/docs/get-started/what-is-openrag.mdx @@ -14,6 +14,8 @@ OpenRAG connects and amplifies three popular, proven open-source projects into o * [Docling](https://docling-project.github.io/docling/) - Docling simplifies document processing, parsing diverse formats — including advanced PDF understanding — and providing seamless integrations with the gen AI ecosystem. -OpenRAG builds on Langflow's familiar interface while adding OpenSearch for vector storage and Docling for simplified document parsing, with opinionated flows that serve as ready-to-use recipes for ingestion, retrieval, and generation from popular sources like OneDrive, Google Drive, and AWS. And don't fear: every part of the stack is swappable. Write your own custom components in Python, try different language models, and customize your flows to build an agentic RAG system that solves problems. +OpenRAG builds on Langflow's familiar interface while adding OpenSearch for vector storage and Docling for simplified document parsing, with opinionated flows that serve as ready-to-use recipes for ingestion, retrieval, and generation from popular sources like OneDrive, Google Drive, and AWS. -Ready to get started? Install OpenRAG and then run the Quickstart to create a powerful RAG pipeline. \ No newline at end of file +What's more, every part of the stack is swappable. Write your own custom components in Python, try different language models, and customize your flows to build an agentic RAG system. + +Ready to get started? [Install OpenRAG](/install) and then run the [Quickstart](/quickstart) to create a powerful RAG pipeline. \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index aa37e2b5..e808dabe 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -28,18 +28,18 @@ const sidebars = { { type: "doc", id: "get-started/install", - label: "Installation" + label: "Install Python wheel" + }, + { + type: "doc", + id: "get-started/docker", + label: "Deploy with Docker" }, { type: "doc", id: "get-started/quickstart", label: "Quickstart" }, - { - type: "doc", - id: "get-started/docker", - label: "Docker Deployment" - }, { type: "doc", id: "get-started/tui", diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 2bc6a4cf..1cf8a7a1 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -28,3 +28,32 @@ --ifm-color-primary-lightest: #4fddbf; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); } + +/* Tabs Styling */ +.tabs-container { + border: 1px solid var(--ifm-color-emphasis-300); + border-radius: var(--ifm-global-radius); + padding: 1rem; + margin-bottom: 1rem; +} + +.tabs { + margin-bottom: 1rem; +} + +.tabs__item { + border: none; + border-bottom: 1px solid var(--ifm-color-emphasis-200); + margin-right: 0rem; + padding-bottom: 0.5rem; + border-radius: 0; +} + +.tabs__item:hover { + background-color: var(--ifm-hover-overlay); +} + +.tabs__item--active { + border-bottom-color: var(--ifm-tabs-color-active); +} + From 762ad224f02445ae501821858060654937de4269 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Tue, 30 Sep 2025 22:34:58 -0400 Subject: [PATCH 04/19] tui-and-quickstart-peer-review --- docs/docs/get-started/install.mdx | 2 +- docs/docs/get-started/quickstart.mdx | 78 ++++++++++++++-------------- docs/docs/get-started/tui.mdx | 6 +-- docs/sidebars.js | 2 +- 4 files changed, 41 insertions(+), 47 deletions(-) diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index f2315a0c..03706199 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -17,7 +17,7 @@ If you prefer running Docker commands and manually editing `.env` files, see [De - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [Docker](https://docs.docker.com/get-docker/) or [Podman](https://podman.io/docs/installation) 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. -- [OpenAI API key](https://platform.openai.com/api-keys) +- Create an [OpenAI API key](https://platform.openai.com/api-keys) - 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. ## Install Python wheel {#install-python-wheel} diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx index b071529b..c2f4b3a5 100644 --- a/docs/docs/get-started/quickstart.mdx +++ b/docs/docs/get-started/quickstart.mdx @@ -12,40 +12,6 @@ Get started with OpenRAG by loading your knowledge, swapping out your language m ## Prerequisites - [Install and start OpenRAG](/install) -- Create a [Langflow API key](https://docs.langflow.org/api-keys-and-authentication) -
- Create a Langflow API key - - A Langflow API key is a user-specific token you can use with Langflow. - It is **only** used for sending requests to the Langflow server. - It does **not** access to OpenRAG. - - To create a Langflow API key, do the following: - - 1. In Langflow, click your user icon, and then select **Settings**. - 2. Click **Langflow API Keys**, and then click
## Find your way around @@ -96,12 +62,44 @@ You can more quickly access the **Language Model** and **Agent Instructions** fi ## Integrate OpenRAG into your application To integrate OpenRAG into your application, use the [Langflow API](https://docs.langflow.org/api-reference-api-examples). -Make requests with Python, TypeScript, or any HTTP client to run one of OpenRAG's default flows and get a response, and then modify the flow further to improve results. +Make requests with Python, TypeScript, or any HTTP client to run one of OpenRAG's default flows and get a response, and then modify the flow further to improve results. Langflow provides code snippets to help you get started. -Langflow provides code snippets to help you get started with the Langflow API. - -1. To navigate to the OpenRAG OpenSearch Agent flow, click