OpenWebUI Setup Guide (WSL2 Docker)

OpenWebUI Setup Guide (WSL2 + Docker)

Introduction

OpenWebUI is a web interface for interacting with local LLMs such as Llama, Qwen, DeepSeek, Phi, and others.
It connects to Ollama through a simple API endpoint and provides chat, RAG, knowledge bases, file uploads, and model management.

---

Prerequisites

• Windows 11
• WSL2 with Ubuntu
• Docker installed inside WSL2
• Ollama running in Docker
• Both containers on the same Docker network
• Basic familiarity with Docker Compose

---

Step 1 – Create Docker Network

If you do not already have a shared network for your containers, create one.

docker network create mediaserver

If you already have one, skip this step.

---

Step 2 – Example OpenWebUI Docker Compose Service

Below is a generic working example of an OpenWebUI service.

services:
  openwebui:
    container_name: openwebui.<HOST_NAME>
    hostname: openwebui.<HOST_NAME>.lan
    image: ghcr.io/open-webui/open-webui:latest
    environment:
      TZ: <TZ>
      WEBUI_AUTH: "false"
      OLLAMA_API_BASE_URL: "http://ollama.<HOST_NAME>:11434"
    networks:
      - mediaserver
    ports:
      - "<OPENWEBUI_PORT>:8080"
    volumes:
      - <DOCKERDIR>/openwebui:/app/backend/data
    restart: always
    security_opt:
      - no-new-privileges:true
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "homepage.group=AI"
      - "homepage.name=OpenWebUI"
      - "homepage.icon=openwebui.png"
      - "homepage.href=https://openwebui.<DOMAIN_NAME>/"
      - "homepage.description=Local AI chat interface"

Step 3 – Start the Stack

Start OpenWebUI.

docker compose up -d

Check that the container is running.

docker ps

---

Step 4 – Access the Web Interface

Open your browser and go to:

http://<HOST_NAME>:<OPENWEBUI_PORT>

If WEBUI_AUTH is disabled, you will be logged in automatically.

---

Step 5 – Verify Connection to Ollama

OpenWebUI connects to Ollama using the API endpoint defined in the environment variable.

Example endpoint
http://ollama.<HOST_NAME>:11434

Test connectivity from inside the OpenWebUI container.

docker exec -it openwebui.<HOST_NAME> curl http://ollama.<HOST_NAME>:11434/api/tags

If you see your model list, the connection is working.

---

Step 6 – Configure OpenWebUI

Inside the OpenWebUI interface:

1. Open Settings
2. Select Models
3. Ensure Ollama is listed as a provider
4. Select your default model (example: llama3.1:8b)
5. Test a prompt to confirm GPU inference through Ollama

---

Step 7 – Knowledge Base Setup (Optional)

OpenWebUI supports RAG through its built‑in knowledge base system.

To add a knowledge source:

1. Go to Knowledge
2. Click Add Source
3. Choose URL, File, or Text
4. Allow OpenWebUI to embed the content
5. Ask questions referencing the new knowledge

This requires Ollama to support embeddings.

---

Step 8 – Backup and Restore

Backup

Backup the OpenWebUI data directory.

<DOCKERDIR>/openwebui

This contains chat history, knowledge bases, and settings.

Restore

Copy the directory into a new OpenWebUI container volume and restart the stack.

---

Troubleshooting

Cannot connect to Ollama

Verify the endpoint.

curl http://ollama.<HOST_NAME>:11434/api/tags

Ensure both containers are on the same Docker network.

OpenWebUI loads but models do not appear

Check the environment variable.

OLLAMA_API_BASE_URL="http://ollama.<HOST_NAME>:11434"

Slow or failing knowledge ingestion

Ensure Ollama has embeddings enabled and the model supports them.

Container will not start

Check logs.

docker logs openwebui.<HOST_NAME>

---

Notes

• OpenWebUI requires Ollama for model execution
• Both containers must share a Docker network
• Disable WEBUI_AUTH only on trusted networks
• Knowledge bases require embedding‑capable models
• GPU inference happens inside Ollama, not OpenWebUI

---