From fcae9855702b20549916f6e089b3f22768eda5dc Mon Sep 17 00:00:00 2001 From: Idan Zairi Date: Wed, 4 Mar 2026 12:22:43 +0200 Subject: [PATCH 1/2] docs: add beginner-safe Unraid deployment guide --- docs/getting-started/index.md | 6 + docs/getting-started/quick-start/index.mdx | 2 + docs/getting-started/unraid.md | 135 +++++++++++++++++++++ docs/troubleshooting/connection-error.mdx | 1 + 4 files changed, 144 insertions(+) create mode 100644 docs/getting-started/unraid.md diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index aeb54f96..6bbc6500 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -16,6 +16,12 @@ Get up and running quickly with our [Quick Start Guide](/getting-started/quick-s --- +## 🧰 Unraid Guide + +Running on Unraid? Use our beginner-safe [Open WebUI on Unraid](/getting-started/unraid) guide for Docker template setup, persistent volumes, upgrades, and reverse-proxy troubleshooting. + +--- + ## 🛠️ Advanced Topics Take a deeper dive into configurations and development tips in our [Advanced Topics Guide](/getting-started/advanced-topics). diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx index a7e80807..61349d97 100644 --- a/docs/getting-started/quick-start/index.mdx +++ b/docs/getting-started/quick-start/index.mdx @@ -41,6 +41,8 @@ Choose your preferred installation method below: - **Python:** Suitable for low-resource environments or those wanting a manual setup - **Kubernetes:** Ideal for enterprise deployments that require scaling and orchestration +Using Unraid? See the dedicated [Open WebUI on Unraid (Beginner-Safe)](/getting-started/unraid) guide. + diff --git a/docs/getting-started/unraid.md b/docs/getting-started/unraid.md new file mode 100644 index 00000000..ef19f2d4 --- /dev/null +++ b/docs/getting-started/unraid.md @@ -0,0 +1,135 @@ +--- +sidebar_position: 3 +title: "Unraid (Beginner-Safe)" +--- + +# Open WebUI on Unraid (Beginner-Safe) + +This guide is for first-time Unraid users who want a stable Docker deployment with persistent data and safe upgrades. + +## What You Will Do + +- Create the Open WebUI container in Unraid. +- Configure persistent storage for `/app/backend/data`. +- Connect Open WebUI to Ollama. +- Update Open WebUI without losing data. +- Troubleshoot reverse-proxy and persistence issues. + +## Before You Start + +- Docker is enabled in Unraid. +- You have a persistent appdata path, for example: `/mnt/user/appdata/open-webui`. +- Optional: Ollama is running either on: + - the Unraid host, or + - another reachable machine. + +:::important +Persist `/app/backend/data` to a host path. If you skip this, chats/settings can disappear after container recreation. +::: + +## 1. Create the Container in Unraid + +In **Docker > Add Container**, use: + +| Field | Value | +| --- | --- | +| Name | `open-webui` | +| Repository | `ghcr.io/open-webui/open-webui:main` | +| Network Type | `bridge` | +| Restart Policy | `always` | +| Container Port | `8080` | +| Host Port | `3000` (or another free port) | + +Add a path mapping: + +| Config Type | Container Path | Host Path | +| --- | --- | --- | +| Path | `/app/backend/data` | `/mnt/user/appdata/open-webui` | + +## 2. Configure Ollama Connectivity + +Choose one setup. + +### Ollama on the Unraid Host + +- Extra parameters: + - `--add-host=host.docker.internal:host-gateway` +- Environment variable: + - `OLLAMA_BASE_URL=http://host.docker.internal:11434` + +### Ollama on Another Machine + +- Environment variable: + - `OLLAMA_BASE_URL=http://:11434` + +### Ollama in Another Container + +- Put both containers on the same custom Docker network. +- Set: + - `OLLAMA_BASE_URL=http://:11434` + +## 3. First Launch Validation + +1. Start the container. +2. Open `http://:3000`. +3. Complete initial admin setup. +4. Open **Admin Settings > Connections > Ollama** and verify the endpoint. +5. Confirm models appear in the model selector. + +## 4. Persistent Volume Notes + +- Open WebUI state is stored in `/app/backend/data`. +- Keep host mapping consistent across updates/recreates. +- Use a directory mapping, not a file mapping. +- If persistence fails, check folder permissions for `/mnt/user/appdata/open-webui`. + +## 5. Upgrade Steps (Safe Workflow) + +1. Back up `/mnt/user/appdata/open-webui`. +2. Update/pull your Open WebUI image tag. +3. Recreate using the same template and same `/app/backend/data` mapping. +4. Verify chats/settings are intact. +5. If needed, roll back to the previous image and restore backup. + +For broader update options, see [Updating Open WebUI](/getting-started/updating). + +## Troubleshooting + +### Cannot Reach Ollama + +Symptoms: +- `Connection error` in Open WebUI +- models do not load + +Checks: +- Confirm `OLLAMA_BASE_URL` is reachable from inside the Open WebUI container. +- If using host Ollama, confirm `--add-host=host.docker.internal:host-gateway` is present. +- If `host.docker.internal` fails, use your Unraid host LAN IP. + +### `host.docker.internal` Does Not Resolve + +- Add `--add-host=host.docker.internal:host-gateway`. +- Restart container after saving template changes. +- Fallback: `OLLAMA_BASE_URL=http://:11434`. + +### Reverse Proxy Subpath Problems (`/openwebui`) + +Symptoms: +- login/static assets return `404` +- WebSocket disconnects or stuck loading states + +Checks: +- Ensure proxy forwards WebSocket upgrade headers. +- Ensure subpath routing is consistent (strip or rewrite prefix before forwarding). +- Set `WEBUI_URL` without trailing slash, for example: + - `WEBUI_URL=https://example.com/openwebui` +- If subpath remains unstable, prefer a subdomain: + - `WEBUI_URL=https://ai.example.com` + +For broader reverse-proxy debugging, see [Connection Errors](/troubleshooting/connection-error). + +### Data Missing After Update/Redo + +- Verify mapping is exactly `/app/backend/data` to your persistent host folder. +- Confirm no typo created a second empty folder. +- Confirm Unraid permissions allow read/write. diff --git a/docs/troubleshooting/connection-error.mdx b/docs/troubleshooting/connection-error.mdx index 1ac2e62d..0e274835 100644 --- a/docs/troubleshooting/connection-error.mdx +++ b/docs/troubleshooting/connection-error.mdx @@ -70,6 +70,7 @@ The `CORS_ALLOW_ORIGIN` setting is crucial for WebSocket functionality. If you s ### Reverse Proxy / SSL/TLS Configuration For reverse proxy and TLS setups, check our [tutorials here](/reference/https). +If you are running Unraid, use the [Open WebUI on Unraid (Beginner-Safe)](/getting-started/unraid) deployment and troubleshooting guide. ### WebSocket Troubleshooting From fafb49f9d8ce3c2627ee84a2148d50eb49ef57c5 Mon Sep 17 00:00:00 2001 From: Idan Zairi Date: Wed, 4 Mar 2026 12:30:16 +0200 Subject: [PATCH 2/2] docs: move Unraid guide to tutorials/integrations --- docs/getting-started/index.md | 6 ----- docs/getting-started/quick-start/index.mdx | 2 -- docs/troubleshooting/connection-error.mdx | 1 - .../integrations}/unraid.md | 22 +++++++++++++------ 4 files changed, 15 insertions(+), 16 deletions(-) rename docs/{getting-started => tutorials/integrations}/unraid.md (81%) diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 6bbc6500..aeb54f96 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -16,12 +16,6 @@ Get up and running quickly with our [Quick Start Guide](/getting-started/quick-s --- -## 🧰 Unraid Guide - -Running on Unraid? Use our beginner-safe [Open WebUI on Unraid](/getting-started/unraid) guide for Docker template setup, persistent volumes, upgrades, and reverse-proxy troubleshooting. - ---- - ## 🛠️ Advanced Topics Take a deeper dive into configurations and development tips in our [Advanced Topics Guide](/getting-started/advanced-topics). diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx index 61349d97..a7e80807 100644 --- a/docs/getting-started/quick-start/index.mdx +++ b/docs/getting-started/quick-start/index.mdx @@ -41,8 +41,6 @@ Choose your preferred installation method below: - **Python:** Suitable for low-resource environments or those wanting a manual setup - **Kubernetes:** Ideal for enterprise deployments that require scaling and orchestration -Using Unraid? See the dedicated [Open WebUI on Unraid (Beginner-Safe)](/getting-started/unraid) guide. - diff --git a/docs/troubleshooting/connection-error.mdx b/docs/troubleshooting/connection-error.mdx index 0e274835..1ac2e62d 100644 --- a/docs/troubleshooting/connection-error.mdx +++ b/docs/troubleshooting/connection-error.mdx @@ -70,7 +70,6 @@ The `CORS_ALLOW_ORIGIN` setting is crucial for WebSocket functionality. If you s ### Reverse Proxy / SSL/TLS Configuration For reverse proxy and TLS setups, check our [tutorials here](/reference/https). -If you are running Unraid, use the [Open WebUI on Unraid (Beginner-Safe)](/getting-started/unraid) deployment and troubleshooting guide. ### WebSocket Troubleshooting diff --git a/docs/getting-started/unraid.md b/docs/tutorials/integrations/unraid.md similarity index 81% rename from docs/getting-started/unraid.md rename to docs/tutorials/integrations/unraid.md index ef19f2d4..bedd9c53 100644 --- a/docs/getting-started/unraid.md +++ b/docs/tutorials/integrations/unraid.md @@ -1,8 +1,14 @@ --- -sidebar_position: 3 -title: "Unraid (Beginner-Safe)" +sidebar_position: 34 +title: "Unraid Deployment (Beginner-Safe)" --- +:::warning + +This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the [contributing tutorial](/tutorials/tips/contributing-tutorial). + +::: + # Open WebUI on Unraid (Beginner-Safe) This guide is for first-time Unraid users who want a stable Docker deployment with persistent data and safe upgrades. @@ -73,12 +79,13 @@ Choose one setup. 1. Start the container. 2. Open `http://:3000`. 3. Complete initial admin setup. -4. Open **Admin Settings > Connections > Ollama** and verify the endpoint. +4. Open **Settings > Admin Settings > Connections** and verify the Ollama endpoint. 5. Confirm models appear in the model selector. ## 4. Persistent Volume Notes - Open WebUI state is stored in `/app/backend/data`. +- Set a fixed `WEBUI_SECRET_KEY` in your Unraid template and keep it the same across recreates to avoid unnecessary session invalidation. - Keep host mapping consistent across updates/recreates. - Use a directory mapping, not a file mapping. - If persistence fails, check folder permissions for `/mnt/user/appdata/open-webui`. @@ -86,10 +93,11 @@ Choose one setup. ## 5. Upgrade Steps (Safe Workflow) 1. Back up `/mnt/user/appdata/open-webui`. -2. Update/pull your Open WebUI image tag. -3. Recreate using the same template and same `/app/backend/data` mapping. -4. Verify chats/settings are intact. -5. If needed, roll back to the previous image and restore backup. +2. Ensure your template keeps the same `WEBUI_SECRET_KEY`. +3. Update/pull your Open WebUI image tag. +4. Recreate using the same template and the same `/app/backend/data` mapping. +5. Verify chats/settings are intact. +6. If needed, roll back to the previous image and restore backup. For broader update options, see [Updating Open WebUI](/getting-started/updating).