Merge pull request #1126 from idanzairi302/codex/unraid-beginner-safe-docs

docs: add beginner-safe Unraid deployment guide

Author: Classic298

docs/tutorials/integrations/unraid.md

@@ -0,0 +1,143 @@
+---
+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.
+
+## 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://<ollama-lan-ip>:11434`
+
+### Ollama in Another Container
+
+- Put both containers on the same custom Docker network.
+- Set:
+  - `OLLAMA_BASE_URL=http://<ollama-container-name>:11434`
+
+## 3. First Launch Validation
+
+1. Start the container.
+2. Open `http://<unraid-ip>:3000`.
+3. Complete initial admin setup.
+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`.
+
+## 5. Upgrade Steps (Safe Workflow)
+
+1. Back up `/mnt/user/appdata/open-webui`.
+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).
+
+## 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://<unraid-lan-ip>: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.