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] 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