mirror of
https://github.com/open-webui/docs.git
synced 2026-03-27 13:28:37 +07:00
144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
---
|
|
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.
|