open-webui-docs/docs/getting-started/unraid.md

sidebar_position, title

sidebar_position	title
3	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://<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 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.

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.

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.