Open WebUI: ChatGPT-Style Interface for Local LLMs

Running local LLMs is powerful, but let’s be honest - most people don’t want to interact with AI through a command line. Open WebUI solves this by providing a beautiful, feature-rich web interface that rivals ChatGPT, Claude, and other commercial AI services. The difference? Everything runs on your hardware, your data never leaves your network, and there are zero subscription fees.

This comprehensive guide will take you from a fresh installation to a fully-configured, multi-user AI platform with advanced features like RAG (Retrieval-Augmented Generation), custom models, and workflow automation.

What You’ll Learn:

• Install and configure Open WebUI with Ollama integration
• Set up multi-user environments with authentication
• Implement RAG for document-grounded responses
• Create custom models and prompts for specific tasks
• Optimize performance and troubleshoot common issues
• Build automation workflows with the Open WebUI API

Time Investment: 30 minutes for basic setup | 2-3 hours for advanced features

Hardware Requirements: 8GB RAM minimum (16GB recommended) | GPU optional but recommended for better performance

---

Table of Contents

1. Understanding Open WebUI
2. Prerequisites
3. Installation Methods
4. First-Time Configuration
5. Multi-User Setup
6. Model Management
7. RAG Implementation
8. Custom Prompts & Workflows
9. API Integration
10. Advanced Features
11. Troubleshooting
12. Next Steps

---

Understanding Open WebUI

What is Open WebUI?

Open WebUI (formerly Ollama WebUI) is an extensible, feature-rich, self-hosted web interface designed specifically for local LLM interaction. Think of it as your private ChatGPT that runs entirely on your infrastructure.

Core Features:

• ChatGPT-Like Interface: Familiar conversation UI with markdown rendering, code highlighting, and streaming responses
• Multi-Model Support: Switch between models mid-conversation or run multiple models simultaneously
• RAG Capabilities: Upload documents and get AI responses grounded in your data
• User Management: Multi-user authentication with role-based access control
• Conversation Management: Organize, search, export, and share conversations
• Model Customization: Create custom models with specific behaviors and prompts
• API Access: Full REST API for programmatic integration
• Extensibility: Plugin system for adding custom functionality

Why Choose Open WebUI?

For Individuals:

• Privacy First: Your conversations and documents never leave your server
• Cost Savings: No per-token charges or monthly subscriptions
• Full Control: Customize every aspect of the interface and behavior
• Offline Capable: Works without internet once deployed

For Families:

• Multi-User Accounts: Each family member gets their own private space
• Safe for Kids: No external data sharing or inappropriate content risks
• Shared Knowledge: Create family knowledge bases with uploaded documents
• Learning Tool: Educational AI assistant without privacy concerns

For Teams & Homelabs:

• Centralized AI: Single deployment serves entire team
• Role-Based Access: Control who can access which models and features
• Knowledge Management: Company documents become AI-searchable
• Integration Ready: API for automation and tool integration

Open WebUI vs Commercial Alternatives

When Open WebUI Makes Sense:

• You already run Ollama or plan to
• You need multi-user AI access
• Privacy and data control are priorities
• You want unlimited document RAG
• You need API integration capabilities

When Commercial Services Work Better:

• You need the absolute latest models immediately
• You don’t want to manage infrastructure
• Occasional use (few queries per week)
• You need maximum convenience over privacy

---

Prerequisites

Required Components

1. Ollama Installation

Open WebUI requires Ollama as its LLM backend. If you haven’t installed Ollama yet:

# Linux/macOS
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
systemctl start ollama
systemctl enable ollama

Verify Ollama is running:

curl http://localhost:11434/api/tags
# Should return JSON with models (or empty list)

See our Ollama guide for detailed installation and configuration.

2. Docker (Recommended Installation Method)

# Install Docker if not already present
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Verify installation
docker --version
docker compose version

3. Hardware Requirements

Minimum Configuration:

• RAM: 8GB total (4GB for Ollama, 2GB for Open WebUI, 2GB for OS)
• CPU: Quad-core processor
• Storage: 20GB free space (more for document storage)
• Network: Local network access

Recommended Configuration:

• RAM: 16GB+ (allows larger models and better performance)
• GPU: NVIDIA RTX 4060+ (8GB VRAM) or Apple M1/M2/M3
• Storage: 50GB+ SSD/NVMe
• Network: Gigabit Ethernet or WiFi 6

Network Planning

Port Requirements:

• 3000: Open WebUI web interface (default)
• 11434: Ollama API backend
• 443/80: If using reverse proxy (recommended for production)

Firewall Configuration (if needed):

# Ubuntu/Debian
sudo ufw allow 3000/tcp
sudo ufw allow 11434/tcp

# RHEL/CentOS
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=11434/tcp
sudo firewall-cmd --reload

---

Installation Methods

Method 1: Docker Compose (Recommended)

This method deploys both Ollama and Open WebUI together, ensuring perfect compatibility.

Step 1: Create Project Directory

mkdir -p /opt/docker/open-webui
cd /opt/docker/open-webui

Step 2: Create Docker Compose File

Create docker-compose.yml:

version: '3.8'

services:
  # Ollama LLM backend
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      - OLLAMA_NUM_PARALLEL=4
      - OLLAMA_MAX_LOADED_MODELS=3
      - OLLAMA_KEEP_ALIVE=24h
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - ollama-network

  # Open WebUI interface
  open-webui:
    image: ghcr.io/open-webui/open-webui:latest
    container_name: open-webui
    restart: unless-stopped
    ports:
      - "3000:8080"
    volumes:
      - open-webui_data:/app/backend/data
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - WEBUI_AUTH=true
      - WEBUI_NAME=My AI Assistant
      - WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}
      - ENABLE_RAG_WEB_SEARCH=true
      - ENABLE_IMAGE_GENERATION=false
      - DEFAULT_USER_ROLE=user
    depends_on:
      - ollama
    networks:
      - ollama-network

volumes:
  ollama_data:
    driver: local
  open-webui_data:
    driver: local

networks:
  ollama-network:
    driver: bridge

Step 3: Create Environment File

Create .env file for secrets:

# Generate a secure secret key
openssl rand -hex 32 > .secret_key

# Create .env file
cat > .env << EOF
WEBUI_SECRET_KEY=$(cat .secret_key)
EOF

# Secure the files
chmod 600 .env .secret_key

Step 4: Deploy the Stack

# Start services
docker compose up -d

# Check logs
docker compose logs -f

# Wait for services to be ready (30-60 seconds)

Step 5: Verify Deployment

# Check service status
docker compose ps

# Test Ollama connectivity
curl http://localhost:11434/api/tags

# Access Open WebUI
# Open browser to http://your-server-ip:3000

Method 2: Standalone Docker (Open WebUI Only)

If you already have Ollama running elsewhere:

docker run -d   --name open-webui   --restart unless-stopped   -p 3000:8080   -v open-webui:/app/backend/data   -e OLLAMA_BASE_URL=http://host.docker.internal:11434   -e WEBUI_AUTH=true   ghcr.io/open-webui/open-webui:latest

For Linux hosts (host.docker.internal doesn’t work):

docker run -d   --name open-webui   --restart unless-stopped   -p 3000:8080   -v open-webui:/app/backend/data   -e OLLAMA_BASE_URL=http://192.168.1.100:11434   -e WEBUI_AUTH=true   --add-host=host.docker.internal:host-gateway   ghcr.io/open-webui/open-webui:latest

Replace 192.168.1.100 with your Ollama server IP.

Method 3: Native Installation (Advanced)

For maximum performance and control:

Prerequisites:

# Install Python 3.11+
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3-pip nodejs npm

# Install Node.js 18+ if not present
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

Installation:

# Clone repository
git clone https://github.com/open-webui/open-webui.git
cd open-webui

# Create Python virtual environment
python3.11 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Install frontend dependencies
cd frontend
npm install
npm run build
cd ..

# Set environment variables
export OLLAMA_BASE_URL=http://localhost:11434
export WEBUI_AUTH=true
export WEBUI_SECRET_KEY=$(openssl rand -hex 32)

# Start the application
python backend/main.py

Access at http://localhost:8080

Create systemd service (optional):

sudo nano /etc/systemd/system/open-webui.service

[Unit]
Description=Open WebUI
After=network.target ollama.service

[Service]
Type=simple
User=your_username
WorkingDirectory=/opt/open-webui
Environment="OLLAMA_BASE_URL=http://localhost:11434"
Environment="WEBUI_AUTH=true"
Environment="WEBUI_SECRET_KEY=your_secret_key_here"
ExecStart=/opt/open-webui/venv/bin/python /opt/open-webui/backend/main.py
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable open-webui
sudo systemctl start open-webui

---

First-Time Configuration

Initial Setup Wizard

Step 1: Create Admin Account

Navigate to http://your-server-ip:3000

On first access, you’ll see the signup screen:

1. Name: Your display name (e.g., “John Smith”)
2. Email: Admin email address
3. Password: Strong password (12+ characters, mixed case, numbers, symbols)
4. Confirm Password

Click “Create Account”

Important: The first account created becomes the administrator with full system access.

Step 2: Verify Ollama Connection

After login:

1. Click Settings (gear icon in top right)
2. Go to Admin Panel → Connections
3. Verify Ollama API URL shows: http://ollama:11434 (Docker) or http://localhost:11434 (native)
4. Click Test Connection
5. Should see: “Connected successfully”

If connection fails:

# Check Ollama is running
curl http://localhost:11434/api/tags

# Check Open WebUI logs
docker logs open-webui -f

# Common fix: update OLLAMA_BASE_URL in docker-compose.yml

Step 3: Download Your First Model

1. Click the + button in the chat interface
2. Search for a model (recommended: llama3.3:8b or mistral)
3. Click the download icon
4. Wait for download to complete (progress shown in UI)

Alternatively, download via Ollama CLI:

docker exec ollama ollama pull llama3.3:8b

Step 4: Start Your First Conversation

1. Select the model from the dropdown at top of chat
2. Type a message: “Hello! Tell me about yourself”
3. Watch the AI stream its response in real-time

Congratulations! Open WebUI is now functional.

Essential Settings Configuration

Navigate to Settings → General

Interface Customization:

• Theme: Light, Dark, or Auto (system preference)
• Language: Select your preferred language
• Chat Bubble: Enable for message grouping
• Markdown Rendering: Enable code highlighting and LaTeX support

Default Behavior:

• Default Model: Model selected automatically for new chats
• System Prompt: Default instructions for all conversations
• Temperature: 0.1 (focused) to 1.0 (creative) - default 0.7
• Max Tokens: Response length limit (512-4096)

Privacy Settings:

• Chat History: Enable/disable conversation storage
• Message Feedback: Allow rating AI responses
• Anonymous Telemetry: Disable for maximum privacy

Save Changes and test with a new conversation.

---

Multi-User Setup

One of Open WebUI’s killer features is multi-user support - perfect for families, teams, or multi-tenant homelabs.

User Management

Access User Management:

1. Settings → Admin Panel → Users
2. You’ll see list of all users and their roles

Create New User:

1. Click Add User
2. Fill in details:
   • Name: Display name
   • Email: Unique email (can be fake for homelab use)
   • Password: Auto-generate or set manually
   • Role: User, Admin, or Pending
3. Click Create

User Roles Explained:

User Workflow:

New Signup (if enabled)
    ↓
Status: Pending
    ↓
Admin Reviews → Approve/Reject
    ↓
Status: User (can access chats)
    ↓
Admin Promotes → Admin (full access)

Authentication Configuration

Settings → Admin Panel → Authentication

Signup Control:

• Enable Signup: Allow new user registration
• Require Email Verification: Send confirmation email (requires SMTP)
• Default Role: Auto-assign role to new signups (User or Pending)

SMTP Email Configuration (Optional):

environment:
  - SMTP_HOST=smtp.gmail.com
  - SMTP_PORT=587
  - SMTP_USERNAME=your-[email protected]
  - SMTP_PASSWORD=your-app-password
  - SMTP_FROM=your-[email protected]
  - SMTP_TLS=true

Add to docker-compose.yml and restart:

docker compose down
docker compose up -d

Disable Public Signups (Recommended for Private Use):

1. Settings → Admin Panel → Authentication
2. Disable “Enable Signup”
3. Create user accounts manually via Admin Panel

Session Management

Settings → Admin Panel → Security

• Session Timeout: Auto-logout after inactivity (default: 7 days)
• Concurrent Sessions: Allow multiple devices simultaneously
• Force Logout All Users: Emergency logout (useful after password changes)

Usage Quotas & Limits

Settings → Admin Panel → Quotas

Control resource usage per user:

• Daily Message Limit: Max messages per user per day
• Model Access: Restrict which models users can access
• RAG Document Limit: Max documents per user for RAG
• File Upload Size: Maximum file size for document uploads

Example: Team Setup

Admin Users (2):
  - Full access to all models
  - No quotas
  - Can manage users and settings

Regular Users (10):
  - Access to llama3.3:8b, mistral only
  - 100 messages per day limit
  - 50 MB total document storage
  - Can create personal knowledge bases

Guest Users (5):
  - Access to phi-3-mini only
  - 20 messages per day limit
  - No document upload
  - Read-only mode

---

Model Management

Downloading Models via UI

Method 1: Model Selector

1. Click + button in chat
2. Browse available models
3. Click download icon next to desired model
4. Monitor progress in notification area

Method 2: Settings Menu

1. Settings → Models
2. Click Download Model
3. Enter model name (e.g., llama3.3:8b)
4. Click Download
5. Wait for completion

Popular Models for Open WebUI:

Managing Models

View Downloaded Models: Settings → Models → My Models

Delete Models:

1. Settings → Models
2. Click trash icon next to model
3. Confirm deletion
4. Frees up disk space immediately

Check Model Details:

# Via Ollama CLI
docker exec ollama ollama list

# Get detailed info
docker exec ollama ollama show llama3.3:8b

Model Switching Mid-Conversation

One of Open WebUI’s unique features:

1. During a conversation, click the model name at top
2. Select different model from dropdown
3. Continue conversation with new model
4. Previous messages retain context

Use Case Example:

You: "Write a Python function to parse JSON"
Model: llama3.3:8b (general purpose response)

[Switch to codellama:7b]

You: "Now optimize it for large files"
Model: codellama:7b (specialized code optimization)

[Switch to deepseek-r1:7b]

You: "Explain the time complexity"
Model: deepseek-r1:7b (detailed reasoning)

Custom Models with Modelfiles

Create specialized models:

Step 1: Create Modelfile

FROM llama3.3:8b

SYSTEM """You are an expert Kubernetes administrator specializing in homelab deployments.

Guidelines:
- Provide practical, tested configurations
- Assume k3s lightweight distribution
- Focus on resource-constrained environments
- Include health checks and restart policies
- Prioritize security best practices

Response Format:
1. Brief explanation
2. Complete YAML manifests
3. Verification commands
4. Troubleshooting tips"""

PARAMETER temperature 0.3
PARAMETER top_p 0.8
PARAMETER num_predict 2048

Step 2: Build Model via Ollama

# Save Modelfile
nano /tmp/k8s-expert-modelfile

# Build custom model
docker exec ollama ollama create k8s-expert -f /tmp/k8s-expert-modelfile

Step 3: Use in Open WebUI

The custom model appears in model selector automatically. Select “k8s-expert” for specialized assistance.

More Custom Model Examples:

HomeAssistant Expert:

FROM llama3.3:8b

SYSTEM """You are a Home Assistant automation expert.
Help users write YAML automations, scripts, and integrations.
Always include trigger, condition, and action sections.
Provide working examples for common devices (Zigbee, Z-Wave, WiFi)."""

PARAMETER temperature 0.2

Technical Writer:

FROM llama3.3:8b

SYSTEM """You write clear, concise technical documentation.
Follow these principles:
- Active voice
- Short paragraphs (3-4 sentences)
- Code examples with inline comments
- Step-by-step instructions
- Prerequisites listed upfront"""

PARAMETER temperature 0.4

Build with:

docker exec ollama ollama create ha-expert -f /path/to/ha-modelfile
docker exec ollama ollama create tech-writer -f /path/to/writer-modelfile

---

RAG Implementation

RAG (Retrieval-Augmented Generation) allows the AI to answer questions based on your documents rather than just its training data.

Understanding RAG

Traditional LLM Response:

You: "What is our company's vacation policy?"
LLM: "I don't have access to your specific company policies..."

RAG-Enabled Response:

You: "What is our company's vacation policy?"
[System retrieves relevant passages from uploaded employee handbook]
LLM: "According to your employee handbook (page 24), full-time
employees receive 15 days of paid vacation per year, accruing at
1.25 days per month. Vacation can be taken after 90 days of employment..."

Setting Up Document Collections

Step 1: Enable RAG

Settings → Admin Panel → RAG Settings

• Enable RAG: Toggle on
• Chunk Size: 400-600 tokens (balance between context and precision)
• Chunk Overlap: 50-100 tokens (prevents context breaks)
• Embedding Model: nomic-embed-text (recommended)

Step 2: Download Embedding Model

docker exec ollama ollama pull nomic-embed-text

This model converts documents into vector representations for similarity search.

Step 3: Create Knowledge Collection

1. Click Documents icon in sidebar
2. Click New Collection
3. Name it (e.g., “Homelab Documentation”, “Family Recipes”, “Work Policies”)
4. Click Create

Step 4: Upload Documents

Supported formats:

• PDF: Technical manuals, books, reports
• TXT: Plain text documentation
• Markdown: README files, notes
• DOCX: Word documents
• CSV: Data tables (with proper context)

Upload Process:

1. Select your collection
2. Click Upload button
3. Choose files (or drag-and-drop)
4. Wait for processing (shows progress)
5. Documents are chunked and embedded automatically

Processing happens in background:

Upload → Text Extraction → Chunking → Embedding → Vector Storage

Using RAG in Conversations

Method 1: Automatic Context

1. Start new conversation
2. Click Documents icon
3. Select collection (e.g., “Homelab Documentation”)
4. Enable “Use as context”
5. Ask questions - AI automatically searches collection

Method 2: Explicit Document Reference

You: Using the Proxmox documentation, how do I create an LXC container?

[AI searches "Proxmox documentation" collection]
[Retrieves relevant sections about LXC creation]
[Generates response grounded in your docs]

Method 3: Citation Mode

Settings → RAG → Enable “Show Citations”

AI responses include source references:

According to "Proxmox Setup Guide.pdf" (page 12), LXC containers
are created via the web UI: Datacenter → Create CT → Configure options...

Sources:
- Proxmox Setup Guide.pdf (page 12)
- LXC Best Practices.md (section 3)

Advanced RAG Configuration

Embedding Model Selection:

# Default: nomic-embed-text (fast, good quality)
docker exec ollama ollama pull nomic-embed-text

# Alternative: mxbai-embed-large (higher quality, slower)
docker exec ollama ollama pull mxbai-embed-large

# Multilingual: multilingual-e5-large
docker exec ollama ollama pull multilingual-e5-large

Configure in Settings → RAG → Embedding Model

Hybrid Search (2025 Feature):

Combines semantic search with keyword matching:

Settings → RAG → Search Strategy:

• Semantic Only: Vector similarity (best for concepts)
• Keyword Only: Exact text matching (best for specific terms)
• Hybrid: Both methods (best overall)

Reranking (Advanced):

Improves result quality by scoring retrieved chunks:

# Add to docker-compose.yml
environment:
  - ENABLE_RERANKING=true
  - RERANKING_MODEL=ms-marco-MiniLM-L-12-v2

RAG Use Cases

1. Personal Knowledge Base

Upload:

• Personal notes and journals
• Project documentation
• Learning resources and bookmarks
• Code snippets and solutions

Ask:

• “What was my solution to that Docker networking issue last month?”
• “Summarize my notes on Kubernetes from the past year”

2. Family Information Hub

Upload:

• Recipes and cooking notes
• Home maintenance logs
• School calendars and info
• Family health records (private!)

Ask:

• “When did we last service the HVAC?”
• “Show me the chocolate chip cookie recipe grandma shared”

3. Work/Business Knowledge

Upload:

• Company policies and procedures
• Technical documentation
• Meeting notes and decisions
• Project specifications

Ask:

• “What was decided about the API redesign?”
• “Summarize our security policy for contractors”

4. Homelab Documentation

Upload:

• Server configurations
• Network diagrams (as text descriptions or PDFs)
• Backup procedures
• Troubleshooting logs

Ask:

• “How do I restore the PostgreSQL backup?”
• “What’s the IP address of the NAS?”

---

Custom Prompts & Workflows

System Prompts

System prompts define AI behavior across all conversations or specific to certain models.

Global System Prompt:

Settings → General → Default System Prompt

You are a helpful AI assistant for a homelab environment.

Context:
- User runs a self-hosted infrastructure
- Focus on open-source, privacy-respecting solutions
- Assume Linux/Docker environment
- Provide production-ready, tested configurations

Response Style:
- Concise but complete
- Include verification steps
- Highlight security considerations
- Provide troubleshooting tips

Model-Specific Prompts:

Create via Modelfiles (see Model Management section) or:

Settings → Models → [Select Model] → Edit

Examples:

Code Assistant:

You are an expert software engineer specializing in Python and Go.

Guidelines:
- Write production-ready, well-documented code
- Include error handling and logging
- Follow PEP 8 (Python) or Go conventions
- Provide unit test examples
- Explain complex logic with comments

Always include:
1. Function/class docstrings
2. Type hints (Python) or type declarations (Go)
3. Edge case handling
4. Example usage

Homelab Consultant:

You are a homelab infrastructure consultant with 10 years of experience.

Expertise:
- Proxmox, Docker, Kubernetes
- Network design and security
- Storage solutions (ZFS, Ceph, NFS)
- Monitoring and observability
- Cost optimization

Response Framework:
1. Assess requirements
2. Propose solution with rationale
3. Provide implementation steps
4. Highlight risks and mitigations
5. Suggest alternatives if applicable

Prompt Templates

Create reusable prompts for common tasks:

Settings → Prompt Library → Create Template

Example Templates:

Code Review:

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Code style violations
4. Best practice deviations
5. Potential bugs

Code:
[PASTE CODE HERE]

Provide specific line numbers and suggestions.

Document Summarizer:

Summarize the following document:

Requirements:
- 3-5 key points (bullet format)
- Executive summary (2-3 sentences)
- Action items (if any)
- Risk factors (if any)

Document:
[PASTE DOCUMENT HERE]

Configuration Generator:

Generate a docker-compose.yml for:

Service: [SERVICE NAME]
Requirements:
- [LIST REQUIREMENTS]

Include:
- Resource limits
- Health checks
- Restart policies
- Volume persistence
- Network configuration
- Environment variables (via .env)

Workflow Automation Examples

1. Daily Standup Generator

Template:

Generate my daily standup update based on:

Yesterday's commits: [PASTE GIT LOG]
Today's calendar: [PASTE CALENDAR]
Current blockers: [LIST BLOCKERS]

Format:
- What I did yesterday (3-5 points)
- What I'm doing today (3-5 points)
- Blockers (if any)

2. Infrastructure Change Log

Document this infrastructure change:

Change: [WHAT CHANGED]
Reason: [WHY]
Impact: [AFFECTED SYSTEMS]
Rollback: [HOW TO UNDO]

Generate:
- Change log entry (markdown)
- Update notification (Slack format)
- Documentation update (wiki format)

3. Incident Response Helper

Assist with incident response:

Symptoms: [DESCRIBE ISSUE]
Affected services: [LIST]
Impact: [USER IMPACT]
Timeline: [WHEN STARTED]

Provide:
1. Immediate mitigation steps
2. Root cause investigation checklist
3. Communication template for users
4. Post-mortem outline

---

API Integration

Open WebUI provides a REST API for programmatic access, enabling automation and integration with other tools.

API Authentication

Generate API Key:

1. Settings → Account → API Keys
2. Click Create New API Key
3. Name it (e.g., “Automation Scripts”)
4. Copy the key immediately (shown only once)
5. Store securely

Using API Key:

# Set as environment variable
export OPENWEBUI_API_KEY="your-api-key-here"

# Or pass in request header
curl -H "Authorization: Bearer your-api-key-here"   http://localhost:3000/api/...

Basic API Operations

List Available Models:

curl http://localhost:3000/api/models   -H "Authorization: Bearer ${OPENWEBUI_API_KEY}"

Send Chat Message:

curl http://localhost:3000/api/chat/completions   -H "Authorization: Bearer ${OPENWEBUI_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "model": "llama3.3:8b",
    "messages": [
      {"role": "user", "content": "Explain Docker networking"}
    ],
    "stream": false
  }'

Stream Response:

curl http://localhost:3000/api/chat/completions   -H "Authorization: Bearer ${OPENWEBUI_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "model": "llama3.3:8b",
    "messages": [
      {"role": "user", "content": "Write a bash script"}
    ],
    "stream": true
  }'

Python Integration

Installation:

pip install openai  # OpenWebUI is OpenAI-compatible

Basic Usage:

from openai import OpenAI

# Initialize client
client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="your-api-key-here"
)

# Simple chat
response = client.chat.completions.create(
    model="llama3.3:8b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Kubernetes?"}
    ]
)

print(response.choices[0].message.content)

With RAG (Document Context):

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="your-api-key-here"
)

# Query with document collection
response = client.chat.completions.create(
    model="llama3.3:8b",
    messages=[
        {
            "role": "system",
            "content": "Use the Homelab Documentation collection to answer questions."
        },
        {
            "role": "user",
            "content": "How do I configure the Proxmox firewall?"
        }
    ],
    extra_body={
        "use_knowledge_base": True,
        "knowledge_base": "Homelab Documentation"
    }
)

print(response.choices[0].message.content)

Automation Examples

1. Daily Documentation Digest

#!/usr/bin/env python3
"""Generate daily summary of uploaded documentation"""

from openai import OpenAI
from datetime import datetime
import json

client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="your-api-key"
)

def generate_digest():
    response = client.chat.completions.create(
        model="llama3.3:8b",
        messages=[
            {
                "role": "user",
                "content": """Review all documents uploaded to the
                'Homelab Documentation' collection in the last 24 hours.

                Provide:
                1. List of new documents
                2. Key topics covered
                3. Important changes or updates
                4. Recommended action items

                Format as markdown."""
            }
        ]
    )

    digest = response.choices[0].message.content

    # Save to file
    filename = f"digest_{datetime.now().strftime('%Y%m%d')}.md"
    with open(filename, 'w') as f:
        f.write(f"# Documentation Digest - {datetime.now().strftime('%Y-%m-%d')}\n\n")
        f.write(digest)

    print(f"Digest saved to {filename}")

if __name__ == "__main__":
    generate_digest()

Schedule with cron:

0 8 * * * /usr/bin/python3 /opt/scripts/daily_digest.py

2. Chatbot for Monitoring Alerts

#!/usr/bin/env python3
"""Analyze monitoring alerts and suggest fixes"""

from openai import OpenAI
import sys

client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="your-api-key"
)

def analyze_alert(alert_message):
    response = client.chat.completions.create(
        model="llama3.3:8b",
        messages=[
            {
                "role": "system",
                "content": """You are a homelab monitoring expert.
                Analyze alerts and provide:
                1. Root cause analysis
                2. Immediate mitigation steps
                3. Long-term fixes
                4. Prevention strategies"""
            },
            {
                "role": "user",
                "content": f"Alert received:\n\n{alert_message}"
            }
        ]
    )

    return response.choices[0].message.content

if __name__ == "__main__":
    alert = sys.stdin.read()
    analysis = analyze_alert(alert)
    print(analysis)

Integrate with alerting:

# In Prometheus Alertmanager webhook
curl -X POST http://monitoring-bot/analyze   -d "$(cat alert.json)" | mail -s "Alert Analysis" [email protected]

---

Advanced Features

Image Generation Integration (DALL-E Alternative)

Open WebUI can integrate with Stable Diffusion for local image generation.

Setup Stable Diffusion:

# Add to docker-compose.yml
  automatic1111:
    image: universonic/automatic1111:latest
    container_name: stable-diffusion
    restart: unless-stopped
    ports:
      - "7860:7860"
    volumes:
      - sd_models:/app/models
    environment:
      - CLI_ARGS=--api --xformers
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  sd_models:

Configure Open WebUI:

# Update Open WebUI service
  open-webui:
    environment:
      - ENABLE_IMAGE_GENERATION=true
      - IMAGE_GENERATION_ENGINE=automatic1111
      - AUTOMATIC1111_BASE_URL=http://automatic1111:7860

Restart services:

docker compose down
docker compose up -d

Usage:

In chat, type:

Generate an image: a futuristic server room with glowing blue lights

Open WebUI sends request to Stable Diffusion and displays generated image inline.

Text-to-Speech (TTS)

Enable voice responses:

Settings → Audio → Text-to-Speech

• Enable TTS: Toggle on
• Voice: Select from available voices
• Speed: 0.5x to 2.0x
• Auto-play: Automatically read responses

Click speaker icon on any message to hear it read aloud.

Self-Hosted TTS (Advanced):

# Add Piper TTS to docker-compose.yml
  piper:
    image: rhasspy/piper:latest
    container_name: piper-tts
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - piper_voices:/app/voices

Configure in Open WebUI:

environment:
  - TTS_ENGINE=piper
  - TTS_API_URL=http://piper:5000

Speech-to-Text (STT)

Enable voice input:

Settings → Audio → Speech-to-Text

• Enable STT: Toggle on
• Language: Select recognition language
• Engine: Browser (WebSpeech API) or Self-Hosted

Click microphone icon to dictate messages instead of typing.

Self-Hosted STT with Whisper:

See our Whisper guide for detailed setup.

  whisper:
    image: onerahmet/openai-whisper-asr-webservice:latest
    container_name: whisper-stt
    restart: unless-stopped
    ports:
      - "9000:9000"
    environment:
      - ASR_MODEL=base
      - ASR_ENGINE=faster_whisper
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Configure Open WebUI:

environment:
  - STT_ENGINE=whisper
  - WHISPER_API_URL=http://whisper:9000

Web Search Integration

Enable AI to search the internet for current information:

Settings → Admin Panel → Web Search

• Enable Web Search: Toggle on
• Search Engine: DuckDuckGo, Google, or SearXNG (self-hosted)
• Max Results: Number of results to retrieve (3-10)

Self-Hosted SearXNG (Recommended):

  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - searxng_data:/etc/searxng
    environment:
      - BASE_URL=http://localhost:8080

Configure Open WebUI:

environment:
  - ENABLE_RAG_WEB_SEARCH=true
  - RAG_WEB_SEARCH_ENGINE=searxng
  - SEARXNG_QUERY_URL=http://searxng:8080/search

Usage:

Enable “Web Search” toggle in chat, then ask:

What are the latest updates to Kubernetes 1.29?

AI searches the web, retrieves current information, and provides cited response.

Plugin System

Extend Open WebUI functionality with plugins:

Settings → Admin Panel → Plugins

Available Plugins:

• GitHub Integration: Search code repositories
• Jira Integration: Ticket management
• Google Drive: Access cloud documents
• Notion: Sync workspace pages
• Custom Functions: Execute Python code

Example: Custom Function Plugin

# Create plugin: /app/plugins/homelab_status.py

def get_homelab_status():
    """Check status of homelab services"""
    import subprocess

    services = {
        "Proxmox": "https://proxmox.local:8006",
        "TrueNAS": "https://truenas.local",
        "Portainer": "https://portainer.local:9443"
    }

    status = {}
    for name, url in services.items():
        try:
            result = subprocess.run(
                ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", url],
                capture_output=True,
                timeout=5
            )
            status[name] = "UP" if result.returncode == 0 else "DOWN"
        except:
            status[name] = "ERROR"

    return status

# Register function
PLUGIN_FUNCTIONS = {
    "homelab_status": {
        "function": get_homelab_status,
        "description": "Check status of homelab services",
        "parameters": {}
    }
}

Use in chat:

Check homelab status

AI calls the function and reports results.

---

Troubleshooting

Common Issues & Solutions

Issue 1: Can’t Connect to Ollama

Symptoms:

• “Failed to connect to Ollama API”
• Models won’t download
• Chat requests timeout

Diagnosis:

# Check Ollama is running
docker ps | grep ollama

# Test Ollama API directly
curl http://localhost:11434/api/tags

# Check logs
docker logs ollama -f

Solutions:

1. Verify OLLAMA_BASE_URL:

Docker Compose:

environment:
  - OLLAMA_BASE_URL=http://ollama:11434  # Service name

Standalone Docker:

-e OLLAMA_BASE_URL=http://host.docker.internal:11434  # For Docker Desktop
# or
-e OLLAMA_BASE_URL=http://192.168.1.100:11434  # For Linux hosts

2. Check Network Connectivity:

# From Open WebUI container
docker exec open-webui ping ollama
docker exec open-webui curl http://ollama:11434/api/tags

3. Firewall Issues:

# Allow Ollama port
sudo ufw allow 11434/tcp

Issue 2: RAG Not Working

Symptoms:

• Documents upload but AI doesn’t use them
• “No relevant documents found”
• Incorrect responses despite uploaded docs

Solutions:

1. Verify Embedding Model:

# Download embedding model
docker exec ollama ollama pull nomic-embed-text

# Check it exists
docker exec ollama ollama list | grep nomic-embed-text

2. Re-index Documents:

Settings → Documents → [Select Collection] → Re-index

3. Check Chunk Settings:

Settings → RAG:

• Chunk Size: 400-600 tokens
• Chunk Overlap: 50-100 tokens
• Similarity Threshold: 0.5-0.7 (lower = more results)

4. Enable Debug Mode:

environment:
  - DEBUG=true

Check logs for RAG processing:

docker logs open-webui -f | grep -i "rag|embedding|retrieval"

Issue 3: Slow Performance

Symptoms:

• Responses take 30+ seconds to start
• UI lags or freezes
• High CPU/memory usage

Diagnosis:

# Check resource usage
docker stats

# Check Open WebUI logs
docker logs open-webui -f

# Check Ollama performance
docker exec ollama ollama ps

Solutions:

1. Use Smaller/Faster Model:

Switch from llama3.3:70b to llama3.3:8b or mistral

2. Adjust Resource Limits:

services:
  open-webui:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 4G

3. Enable GPU Acceleration:

Verify GPU is accessible:

docker exec ollama nvidia-smi

If not working, ensure deploy.resources.reservations.devices is configured.

4. Reduce Concurrent Requests:

environment:
  - OLLAMA_NUM_PARALLEL=2  # Reduce from 4

Issue 4: Authentication Issues

Symptoms:

• Can’t log in
• “Invalid credentials”
• Session expires immediately

Solutions:

1. Reset Admin Password:

# Access database directly
docker exec -it open-webui sh

# Reset password (inside container)
python -c "
from backend.apps.users.models import Users
from backend.apps.users.utils import hash_password
user = Users.get_user_by_email('[email protected]')
user.password = hash_password('new_password_here')
user.save()
"

2. Fix Secret Key:

Ensure WEBUI_SECRET_KEY is set and persistent:

environment:
  - WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}

Generate stable key:

openssl rand -hex 32 > .secret_key
echo "WEBUI_SECRET_KEY=$(cat .secret_key)" >> .env

3. Clear Sessions:

Settings → Admin Panel → Security → Force Logout All Users

Issue 5: Docker Permission Errors

Symptoms:

• “Permission denied” writing to volumes
• Uploaded files disappear
• Can’t save settings

Solutions:

1. Fix Volume Permissions:

# Find volume location
docker volume inspect open-webui_data

# Fix permissions (replace UID/GID as needed)
sudo chown -R 1000:1000 /var/lib/docker/volumes/open-webui_data/_data

2. Run with User Directive:

services:
  open-webui:
    user: "1000:1000"  # Match your host user

Performance Benchmarking

Test Open WebUI performance:

# Simple response time test
time curl -X POST http://localhost:3000/api/chat/completions   -H "Authorization: Bearer ${OPENWEBUI_API_KEY}"   -H "Content-Type: application/json"   -d '{
    "model": "llama3.3:8b",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

Expected Performance:

Times assume GPU acceleration (RTX 4070 or equivalent).

Getting Help

Useful debugging commands:

# Full environment info
docker exec open-webui env

# Check database
docker exec open-webui ls -la /app/backend/data

# Test API connectivity
curl http://localhost:3000/api/health

# View all logs
docker compose logs -f

# Restart clean
docker compose down -v  # WARNING: Deletes data
docker compose up -d

Community Resources:

• GitHub Issues: https://github.com/open-webui/open-webui/issues
• Discord: https://discord.gg/open-webui
• Reddit: r/LocalLLaMA

When asking for help, provide:

1. Open WebUI version: docker inspect open-webui | grep Image
2. Ollama version: docker exec ollama ollama --version
3. Relevant logs: docker logs open-webui --tail 50
4. Configuration: docker compose config (remove secrets!)

---

Next Steps

Congratulations! You now have a fully-functional, ChatGPT-like interface for local LLMs.

Immediate Next Actions

1. Set Up Backup Strategy

# Backup volumes
docker run --rm   -v open-webui_data:/data:ro   -v $(pwd):/backup   alpine tar czf /backup/open-webui_backup_$(date +%Y%m%d).tar.gz -C /data .

# Automated backup script
cat > /opt/scripts/backup-open-webui.sh << 'EOF'
#!/bin/bash
BACKUP_DIR=/opt/backups/open-webui
mkdir -p $BACKUP_DIR
docker run --rm   -v open-webui_data:/data:ro   -v $BACKUP_DIR:/backup   alpine tar czf /backup/open-webui_$(date +%Y%m%d_%H%M%S).tar.gz -C /data .

# Keep only last 7 days
find $BACKUP_DIR -name "open-webui_*.tar.gz" -mtime +7 -delete
EOF

chmod +x /opt/scripts/backup-open-webui.sh

# Schedule daily backups
(crontab -l; echo "0 2 * * * /opt/scripts/backup-open-webui.sh") | crontab -

2. Configure Reverse Proxy (Secure Access)

See our Nginx Proxy Manager guide for HTTPS setup.

Quick example with built-in reverse proxy:

  nginx:
    image: nginx:alpine
    container_name: open-webui-proxy
    restart: unless-stopped
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - open-webui

3. Explore Advanced Features

• Enable web search for current information
• Set up image generation with Stable Diffusion
• Create custom models for specific tasks
• Build automation workflows with the API

Integration Ideas

Home Assistant: Use Open WebUI to control smart home with natural language.

Obsidian/Notion: AI assistant with access to your personal knowledge base.

CI/CD Pipeline: Automated code review and documentation generation.

Monitoring Stack: AI-powered alert analysis and incident response.

Related Guides

• Ollama: Self-Hosted Local LLMs - Backend setup and optimization
• AnythingLLM: RAG-Enabled Knowledge Base - Alternative with different focus
• LocalAI: OpenAI API-Compatible Inference - Backend alternative to Ollama
• Continue.dev + Ollama: AI Code Assistant - IDE integration

Learning Path

Week 1-2: Master the Basics

• Download 3-5 different models
• Experiment with system prompts
• Create your first custom model
• Upload personal documentation for RAG

Week 3-4: Advanced Usage

• Set up multi-user accounts for family/team
• Implement web search integration
• Build custom prompt templates
• Explore API integration

Month 2+: Automation & Integration

• Create workflow automation scripts
• Integrate with existing tools
• Build custom plugins
• Contribute to the community

---

Conclusion

Open WebUI transforms local LLMs from a command-line curiosity into a production-ready AI platform. By combining Ollama’s powerful inference engine with a beautiful, feature-rich web interface, you get:

Privacy: Your data never leaves your infrastructure Flexibility: Multiple models, custom prompts, RAG capabilities Cost Savings: No subscription fees, unlimited usage Control: Full customization and integration capabilities Accessibility: User-friendly interface for non-technical users

The future of AI is local, private, and under your control. Open WebUI makes that future accessible today.

Start experimenting, build your knowledge bases, and discover how AI can enhance your homelab and daily workflows. The possibilities are limited only by your imagination.

---

Guide Version: 1.0 Last Updated: December 2024 Author: homelabbing.io Difficulty: Intermediate Time to Complete: 30-45 minutes

Happy homelabbing!