From ac97ef72c65fddd2be6cb46ec1a06541fd3fdf49 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Mon, 24 Nov 2025 13:54:17 -0800 Subject: [PATCH 1/3] add wsl instructions --- docs/docs/_partial-wsl-install.mdx | 19 +++++++++++++ docs/docs/get-started/install.mdx | 42 +++++++++++++++++++++------- docs/docs/get-started/quickstart.mdx | 19 ++++++++++++- 3 files changed, 69 insertions(+), 11 deletions(-) create mode 100644 docs/docs/_partial-wsl-install.mdx diff --git a/docs/docs/_partial-wsl-install.mdx b/docs/docs/_partial-wsl-install.mdx new file mode 100644 index 00000000..bff89586 --- /dev/null +++ b/docs/docs/_partial-wsl-install.mdx @@ -0,0 +1,19 @@ +1. [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install) with the Ubuntu distribution using WSL 2: + + ```powershell + wsl --install -d Ubuntu + ``` + + For new installations, the `wsl --install` command uses WSL 2 and Ubuntu by default. + + For existing WSL installations, you can [change the distribution](https://learn.microsoft.com/en-us/windows/wsl/install#change-the-default-linux-distribution-installed) and [check the WSL version](https://learn.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2). + +2. [Start your WSL Ubuntu distribution](https://learn.microsoft.com/en-us/windows/wsl/install#ways-to-run-multiple-linux-distributions-with-wsl) if it doesn't start automatically. + +3. [Set up a username and password for your WSL distribution](https://learn.microsoft.com/en-us/windows/wsl/setup/environment#set-up-your-linux-username-and-password). + +4. [Install Docker Desktop for Windows with WSL 2](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers). When you reach the Docker Desktop **WSL integration** settings, make sure your Ubuntu distribution is enabled, and then click **Apply & Restart** to enable Docker support in WSL. + +5. Install and run OpenRAG from within your WSL Ubuntu distribution using any of the installation methods described on this page. + +If you encounter issues with port forwarding or the Windows Firewall, you might to adjust the [Hyper-V firewall settings](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see [Troubleshooting WLS common issues](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues). \ No newline at end of file diff --git a/docs/docs/get-started/install.mdx b/docs/docs/get-started/install.mdx index 06f73e3e..ab142b81 100644 --- a/docs/docs/get-started/install.mdx +++ b/docs/docs/get-started/install.mdx @@ -5,7 +5,8 @@ slug: /install import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; +import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; +import PartialWsl from '@site/docs/_partial-wsl-install.mdx'; [Install OpenRAG](#install) and then run the [OpenRAG Terminal User Interface(TUI)](#setup) to start your OpenRAG deployment with a guided setup process. @@ -21,19 +22,40 @@ If you prefer running Podman or Docker containers and manually editing `.env` fi ## Prerequisites -- 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. -- Optional: Create an [OpenAI API key](https://platform.openai.com/api-keys). During [Application Onboarding](#application-onboarding), you can provide this key or choose a different model provider. +- All OpenRAG installations require [Python](https://www.python.org/downloads/release/python-3100/) version 3.10 to 3.13. + +- If you aren't using the automatic installer script, install the following: + + - [uv](https://docs.astral.sh/uv/getting-started/installation/). + - [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/). + - [`podman-compose`](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or [Docker Compose](https://docs.docker.com/compose/install/). To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands. + +- Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL). + +
+ Install WSL for OpenRAG + + + +
+ +- Prepare model providers and credentials. + + During [Application Onboarding](#application-onboarding), you must select language model and embedding model providers. + If your chosen provider offers both types, you can use the same provider for both selections. + If your provider offers only one type, such as Anthropic, you must select two providers. + + Gather the credentials and connection details for your chosen model providers before starting onboarding: + + - OpenAI: Create an [OpenAI API key](https://platform.openai.com/api-keys). + - Anthropic language models: Create an [Anthropic API key](https://www.anthropic.com/docs/api/reference). + - IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment. + - Ollama: Use the [Ollama documentation](https://docs.ollama.com/) to set up your Ollama instance locally, in the cloud, or on a remote server, and then get your Ollama server's base URL. + - 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 {#install} -:::note Windows users -To use OpenRAG on Windows, use [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install). -::: - Choose an installation method based on your needs: * For new users, the automatic installer script detects and installs prerequisites and then runs OpenRAG. diff --git a/docs/docs/get-started/quickstart.mdx b/docs/docs/get-started/quickstart.mdx index bb605b05..80eb0902 100644 --- a/docs/docs/get-started/quickstart.mdx +++ b/docs/docs/get-started/quickstart.mdx @@ -6,12 +6,29 @@ slug: /quickstart import Icon from "@site/src/components/icon/icon"; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import PartialWsl from '@site/docs/_partial-wsl-install.mdx'; Use this quickstart to install OpenRAG, and then try some of OpenRAG's core features. ## Prerequisites -This quickstart requires an [OpenAI API key](https://platform.openai.com/api-keys) and [Python](https://www.python.org/downloads/release/python-3100/) version 3.10 to 3.13. +This quickstart requires the following: + +- An [OpenAI API key](https://platform.openai.com/api-keys). +This quickstart uses OpenAI for simplicity. +For other providers, see the complete [installation guide](/install). + +- [Python](https://www.python.org/downloads/release/python-3100/) version 3.10 to 3.13. + +- Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL). + +
+ Install WSL for OpenRAG + + + +
+ ## Install OpenRAG From ecb486b9a4835493baf612b6fb36b7e982435471 Mon Sep 17 00:00:00 2001 From: April M <36110273+aimurphy@users.noreply.github.com> Date: Mon, 24 Nov 2025 14:27:13 -0800 Subject: [PATCH 2/3] update docker page prereqs --- docs/docs/_partial-wsl-install.mdx | 2 +- docs/docs/get-started/docker.mdx | 39 ++++++++++++++++++++++++------ 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/docs/docs/_partial-wsl-install.mdx b/docs/docs/_partial-wsl-install.mdx index bff89586..ff674297 100644 --- a/docs/docs/_partial-wsl-install.mdx +++ b/docs/docs/_partial-wsl-install.mdx @@ -14,6 +14,6 @@ 4. [Install Docker Desktop for Windows with WSL 2](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers). When you reach the Docker Desktop **WSL integration** settings, make sure your Ubuntu distribution is enabled, and then click **Apply & Restart** to enable Docker support in WSL. -5. Install and run OpenRAG from within your WSL Ubuntu distribution using any of the installation methods described on this page. +5. Install and run OpenRAG from within your WSL Ubuntu distribution. If you encounter issues with port forwarding or the Windows Firewall, you might to adjust the [Hyper-V firewall settings](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see [Troubleshooting WLS common issues](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues). \ No newline at end of file diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx index d8494134..b9bb312a 100644 --- a/docs/docs/get-started/docker.mdx +++ b/docs/docs/get-started/docker.mdx @@ -6,8 +6,9 @@ slug: /docker import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; +import PartialWsl from '@site/docs/_partial-wsl-install.mdx'; -OpenRAG has two Docker Compose files. Both files deploy the same applications and containers locally, but they are for 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. This Docker Compose file requires an NVIDIA GPU with [CUDA](https://docs.nvidia.com/cuda/) support. @@ -15,12 +16,36 @@ OpenRAG has two Docker Compose files. Both files deploy the same applications an ## Prerequisites -- 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. -- Optional: Create an [OpenAI API key](https://platform.openai.com/api-keys). You can provide this key during [Application Onboarding](#application-onboarding) or choose a different model provider. -- 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 following: + + - [Python](https://www.python.org/downloads/release/python-3100/) version 3.10 to 3.13. + - [uv](https://docs.astral.sh/uv/getting-started/installation/). + - [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/). + - [`podman-compose`](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or [Docker Compose](https://docs.docker.com/compose/install/). To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands. + +- Microsoft Windows only: To run OpenRAG on Windows, you must use the Windows Subsystem for Linux (WSL). + +
+ Install WSL for OpenRAG + + + +
+ +- Prepare model providers and credentials. + + During [Application Onboarding](#application-onboarding), you must select language model and embedding model providers. + If your chosen provider offers both types, you can use the same provider for both selections. + If your provider offers only one type, such as Anthropic, you must select two providers. + + Gather the credentials and connection details for your chosen model providers before starting onboarding: + + - OpenAI: Create an [OpenAI API key](https://platform.openai.com/api-keys). + - Anthropic language models: Create an [Anthropic API key](https://www.anthropic.com/docs/api/reference). + - IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment. + - Ollama: Use the [Ollama documentation](https://docs.ollama.com/) to set up your Ollama instance locally, in the cloud, or on a remote server, and then get your Ollama server's base URL. + +- Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/cuda/) support, and compatible NVIDIA drivers on the OpenRAG host machine. This is required to use the GPU-accelerated Docker Compose file. If you choose not to use GPU support, you must use the CPU-only Docker Compose file instead. ## Install OpenRAG with Docker Compose From a358166a2d372813ac50f21550c826a04e0694e3 Mon Sep 17 00:00:00 2001 From: "April I. Murphy" <36110273+aimurphy@users.noreply.github.com> Date: Mon, 24 Nov 2025 15:25:21 -0800 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Mendon Kissling <59585235+mendonk@users.noreply.github.com> --- docs/docs/_partial-wsl-install.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/_partial-wsl-install.mdx b/docs/docs/_partial-wsl-install.mdx index ff674297..7cab4029 100644 --- a/docs/docs/_partial-wsl-install.mdx +++ b/docs/docs/_partial-wsl-install.mdx @@ -15,5 +15,5 @@ 4. [Install Docker Desktop for Windows with WSL 2](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers). When you reach the Docker Desktop **WSL integration** settings, make sure your Ubuntu distribution is enabled, and then click **Apply & Restart** to enable Docker support in WSL. 5. Install and run OpenRAG from within your WSL Ubuntu distribution. - -If you encounter issues with port forwarding or the Windows Firewall, you might to adjust the [Hyper-V firewall settings](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see [Troubleshooting WLS common issues](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues). \ No newline at end of file +
+If you encounter issues with port forwarding or the Windows Firewall, you might need to adjust the [Hyper-V firewall settings](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) to allow communication between your WSL distribution and the Windows host. For more troubleshooting advice for networking issues, see [Troubleshooting WLS common issues](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#common-issues). \ No newline at end of file