Merge pull request #1129 from open-webui/main

docs/tutorials/integrations/monitoring/langfuse.md

@@ -3,6 +3,21 @@ sidebar_position: 20
 title: "Langfuse"
 ---
 
+:::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.
+
+:::
+
+:::danger
+
+This tutorial was reported as **OUTDATED** / stale.
+It might not work anymore with newer versions of Open WebUI or Langfuse.
+
+Feel free to contribute to make it up to date again, by submitting a PR: [https://github.com/open-webui/docs](https://github.com/open-webui/docs)
+
+:::
+
 ## Langfuse Integration with Open WebUI
 
 [Langfuse](https://langfuse.com/) ([GitHub](https://github.com/langfuse/langfuse)) offers open source observability and evaluations for Open WebUI. By enabling the Langfuse integration, you can trace your application data with Langfuse to develop, monitor, and improve the use of Open WebUI, including:

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.