open-webui

Open WebUI: Best Frontend for Local LLMs on Your Homelab

Frank Stupak

— 6 min read
Open WebUI: Best Frontend for Local LLMs on Your Homelab

Why You Need Open WebUI for Your Homelab LLM Setup

If you're running Ollama on your homelab and accessing models through curl commands or basic web interfaces, you're leaving serious usability on the table. Open WebUI gives you a production-grade ChatGPT-like frontend with model management, conversation persistence, RAG uploads, and multi-user support—all running locally on your hardware.

This post covers deploying Open WebUI 0.1.127 on Docker with Ollama integration, handling the common permission gotchas, and configuring it for a small team or family setup. I'm assuming you already have Docker and Ollama running; if not, that's a 10-minute prerequisite.

Prerequisites and System Requirements

Software versions tested:

  • Docker 26.1.3, Docker Compose 2.27.0
  • Ollama 0.1.32 (or any recent version with REST API)
  • Open WebUI 0.1.127
  • Ubuntu 24.04 LTS (should work on any Docker-capable Linux)

System requirements:

  • 2GB RAM minimum (4GB+ if you're running models + Open WebUI simultaneously)
  • Ollama running and accessible on your network (local or remote)
  • Port 8080 (or any unused port) available on your host
  • Docker daemon running with your user in the docker group

On my T5810 with 24GB RAM running Ubuntu 24.04, I run Ollama in the background on the same machine, but Open WebUI also works against a remote Ollama instance on a different host. The key is network reachability—Open WebUI needs to reach Ollama's API endpoint.

Setting Up Open WebUI with Docker Compose

The cleanest approach is Docker Compose. This handles networking, volume persistence, and environment variables without wrestling with long docker run commands.

Create a directory for your stack:

mkdir -p ~/homelab/open-webui
cd ~/homelab/open-webui

Now create your docker-compose.yml. The critical part is the OLLAMA_BASE_URL—this must be reachable from inside the container:

version: '3.8'

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:0.1.127
    container_name: open-webui
    ports:
      - "8080:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
      - WEBUI_SECRET_KEY=your-secret-key-min-8-chars-change-this
      - ENABLE_SIGNUP=false
    volumes:
      - open-webui-data:/app/backend/data
    restart: unless-stopped
    networks:
      - webui-net

networks:
  webui-net:
    driver: bridge

volumes:
  open-webui-data:

Critical gotcha #1: OLLAMA_BASE_URL on macOS vs Linux. On macOS Docker Desktop, host.docker.internal resolves correctly. On Linux, it doesn't exist—you need either http://localhost:11434 (if Ollama runs on the host network) or http://<your-host-ip>:11434 if Ollama runs on a different machine. I use host.docker.internal on this Linux setup because I run Ollama with --network host.

If you run Ollama in a separate Docker container, use the container's service name instead:

- OLLAMA_BASE_URL=http://ollama:11434

Change the WEBUI_SECRET_KEY to something random—this signs session tokens. Generate one:

openssl rand -hex 16

Bring up the stack:

docker compose up -d

Check logs immediately:

docker compose logs -f open-webui

Look for "Uvicorn running on 0.0.0.0:8080". If you see connection errors to the Ollama URL, fix that environment variable before proceeding.

Configuring Multi-User Access and Authentication

By default, Open WebUI allows anyone with network access to use it. For a homelab, you probably want at least basic signup control.

Open http://localhost:8080 in your browser. The first user you create becomes the admin. Create your account:

  1. Sign up with email and password
  2. You'll be logged in immediately as admin
  3. Go to Admin Settings (gear icon, top-right)
  4. Under General, toggle Allow user sign-ups to OFF

Now only you can create new users. To add family members or team members, stay in Admin Settings and use the Users section to manually create accounts.

For OAuth2 integration (optional): Open WebUI supports Google OAuth and other OIDC providers, but that requires external internet access. For a private homelab, stick with local users. The setup is cleaner and you avoid leaking your activity to third parties.

Each user gets their own conversation history, saved models, and preferences. Conversation data lives in the open-webui-data volume, so it persists across container restarts.

Managing Models and Testing the Setup

After logging in, Open WebUI auto-detects models available in your Ollama instance. Click the + Select a model dropdown at the top of the chat window. You should see every model you've pulled in Ollama.

If the dropdown is empty, Ollama isn't reachable. Double-check your OLLAMA_BASE_URL. Test connectivity from inside the container:

docker compose exec open-webui curl -s http://host.docker.internal:11434/api/tags | jq .

This returns a JSON list of available models. If it fails, your URL is wrong or Ollama isn't listening on that address.

Once models appear, click one and send a test message. Response time depends on your model and hardware. On my T5810 with a 7B model, first token takes ~2 seconds.

Gotcha #2: Model switching context.** Each conversation remembers which model it started with. If you switch models mid-conversation, Open WebUI sends the entire history to the new model—fine for similar-sized models, wasteful if jumping between 70B and 7B. Start a new conversation when changing model classes.

Enabling RAG and Document Upload

Open WebUI's RAG (Retrieval-Augmented Generation) feature lets you upload PDFs, text files, or Markdown and have the LLM reference them during responses. This requires a vector database.

By default, Open WebUI uses an embedded SQLite-based vector store. No extra setup needed. To upload documents:

  1. Click the + icon in the chat input area (or the paperclip if visible)
  2. Select files: PDF, DOCX, TXT, MD, JSON
  3. Open WebUI chunks and embeds them
  4. In your prompt, mention the document: "Based on the uploaded file, what..."

The embedding process is synchronous—you'll see a progress indicator. Embedding speed depends on your model and document size. A 10-page PDF takes 10-30 seconds on my setup.

For production RAG at scale, swap in Weaviate or Milvus, but for homelab use, the embedded store is solid. Add these environment variables if you want persistent RAG storage:

environment:
  - OLLAMA_BASE_URL=http://host.docker.internal:11434
  - ENABLE_RAG=true
  - RAG_EMBEDDING_MODEL=nomic-embed-text

The embedding model runs inside Ollama—make sure it's pulled:

ollama pull nomic-embed-text

Persistence, Backups, and Disaster Recovery

Your conversation history, user data, and documents live in the open-webui-data Docker volume. To back it up:

docker run --rm -v open-webui-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/open-webui-backup-$(date +%s).tar.gz -C /data .

This creates a timestamped tarball in your current directory. Schedule this via cron for weekly backups:

0 3 * * 0 cd ~/homelab/open-webui && docker run --rm -v open-webui-data:/data -v $(pwd):/backup alpine tar czf /backup/open-webui-backup-\$(date +\%s).tar.gz -C /data .

To restore:

docker run --rm -v open-webui-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/open-webui-backup-1234567890.tar.gz -C /data

Then restart the container. Your conversations, users, and documents return intact.

Common Issues and Troubleshooting

Ollama connection failures

Symptom: "Failed to fetch models" error in the UI.

Fix: Verify Ollama is running and listening:

netstat -tlnp | grep 11434
# or on newer systems:
ss -tlnp | grep 11434

If Ollama isn't there, start it: ollama serve (background it with & or systemd).

Then test the URL from the container again. If it's still failing, check your firewall. On Ubuntu:

sudo ufw allow 11434/tcp

Port 8080 already in use

Change the exposed port in docker-compose.yml: - "8081:8080" instead of 8080:8080. Access it at localhost:8081.

Permission denied on volume mount

Symptom: Container starts but immediately exits.

The Open WebUI container runs as non-root. Ensure your Docker group permissions are correct:

docker ps  # Should work without sudo

If it fails, add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Slow embedding or model responses

If everything feels sluggish, check resource contention:

docker stats

If Ollama is pegged at 100% CPU, it's processing a model inference and will be slow until done. If Open WebUI is slow with reasonable Ollama usage, you might have memory pressure. Reduce concurrent users or scale up your hardware.

You now have a fully functional Open WebUI homelab setup with Ollama integration, multi-user support, RAG capabilities, and persistent storage. Here's what to explore next:

  • Network access: Expose Open WebUI to your LAN (or VPN) by binding to 0.0.0.0 instead of localhost. Use a reverse proxy (Caddy, Traefik) for TLS and auth if it's internet-facing.
  • Model management: Create separate conversations for different tasks—one for coding, one for brainstorming, one for documentation. The model dropdown persists your choice per conversation.
  • Integrations: Open WebUI supports webhooks and extensions. Check the GitHub repository for community extensions that add functionality.
  • Performance tuning: If you have spare hardware, run Ollama on a different machine and point Open WebUI to its remote IP. This decouples UI latency from model inference time.

For detailed configuration options, check the Open WebUI GitHub repository. For Ollama model selection and optimization, refer to the Ollama model library.

Read more