Skip to main content
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.

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:

FieldValue
Nameopen-webui
Repositoryghcr.io/open-webui/open-webui:main
Network Typebridge
Restart Policyalways
Container Port8080
Host Port3000 (or another free port)

Add a path mapping:

Config TypeContainer PathHost 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.

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.