mirror of
https://github.com/open-webui/docs.git
synced 2026-03-26 13:18:42 +07:00
Merge pull request #1126 from idanzairi302/codex/unraid-beginner-safe-docs
docs: add beginner-safe Unraid deployment guide
This commit is contained in:
Classic298
143
docs/tutorials/integrations/unraid.md
Normal file
143
docs/tutorials/integrations/unraid.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user