Skip to content

Open WebUI

Overview

Open WebUI is a feature-rich, self-hosted web interface for AI chat models that provides a user-friendly alternative to command-line interfaces. It supports both local LLMs through Ollama integration and external AI providers like OpenAI and Anthropic. The interface offers a ChatGPT-like experience with additional features for model management, conversation history, and user administration.

Key Features

  • Multi-Model Support: Connect to local Ollama models and external AI providers simultaneously
  • User Management: Built-in authentication and user administration
  • Conversation Management: Save, search, and organize chat histories
  • Model Switching: Seamlessly switch between different models mid-conversation
  • Document Upload: Support for various file formats for context-aware conversations
  • Customizable Interface: Dark/light themes and adjustable settings
  • API Access: RESTful API for programmatic interaction

Architecture

Open WebUI follows a modular architecture with several key components:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Web Browser   │────▶│    Traefik      │────▶│   Open WebUI    │
│                 │     │ (Reverse Proxy) │     │   Container     │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                          │
                        ┌─────────────────────────────────┴───────────┐
                        │                                             │
                  ┌─────▼─────────┐                      ┌───────────▼──────────┐
                  │    Ollama     │                      │  External AI APIs   │
                  │ (Local Host)  │                      │ (OpenAI, Anthropic) │
                  └───────────────┘                      └────────────────────┘

Components

  1. Frontend: React-based SPA with responsive design
  2. Backend: Python FastAPI server handling authentication, model routing, and data persistence
  3. Database: SQLite for user data, conversations, and settings
  4. Storage: Local filesystem for uploaded documents and vector embeddings
  5. Model Providers: Ollama for local models, API clients for external providers

Integration with Ollama

Overview

Ollama integration allows Open WebUI to interact with locally-hosted LLMs without requiring internet connectivity or API keys. In this deployment, Ollama runs as a system service on the Docker host, not as a container.

Configuration Details

The integration is configured through environment variables in /srv/dockerdata/open-webui/.env:

# Ollama Configuration
OLLAMA_BASE_URL=http://172.17.0.1:11434
ENABLE_OLLAMA=true

Important: The IP address 172.17.0.1 is the Docker bridge network gateway, allowing containers to access services running on the host.

How It Works

  1. Host Service: Ollama runs as a systemd service on the host machine
  2. Model Storage: Models are stored in /srv/dockerdata/ollama/models/
  3. API Access: Ollama exposes its API on port 11434
  4. Container Access: Open WebUI accesses Ollama through the Docker bridge network

Available Models

Current Ollama models (as shown by ollama list): - gemma3n:e4b - Google's Gemma 3 Nano model (7.5 GB) - deepseek-r1:latest - DeepSeek R1 reasoning model (5.2 GB) - llama3.1:8b-instruct-q4_0 - Meta's Llama 3.1 8B instruction model (4.7 GB)

Managing Ollama Models

# List installed models
ollama list

# Pull a new model
ollama pull llama3.2

# Remove a model
ollama rm model_name

# Run a model directly (for testing)
ollama run llama3.1:8b-instruct-q4_0

Integration with External AI Providers

Supported Providers

Open WebUI supports multiple external AI providers through their respective APIs:

  1. OpenAI - GPT models (GPT-3.5, GPT-4, etc.)
  2. Anthropic - Claude models
  3. Google - Gemini models
  4. Groq - Fast inference for open models

Configuration

API keys are configured in /srv/dockerdata/open-webui/.env:

# provider / app secrets go below (edit after generation)
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=AI...
# GROQ_API_KEY=gsk_...

After adding API keys: 

cd /srv/dockerdata/open-webui
docker compose restart open-webui

Provider-Specific Features

  • OpenAI: Function calling, vision models, embeddings
  • Anthropic: Long context windows, Claude 3 vision capabilities
  • Google: Multimodal support, Gemini Pro features
  • Groq: Ultra-fast inference, cost-effective for supported models

Configuration Details

Environment Variables

Key environment variables in /srv/dockerdata/open-webui/.env:

# Core Configuration
APP_NAME=open-webui
APP_PORT=3000  # Note: Internal port is actually 8080
APP_DOMAIN=open-webui.rbnk.uk

# Security
WEBUI_SECRET_KEY=change-this-to-a-random-secret-key  # IMPORTANT: Change this!

# Network Configuration
TRAEFIK_NETWORK=traefik_proxy
TRAEFIK_CERTRESOLVER=cf
TRAEFIK_ENTRYPOINT=websecure

# Ollama Integration
OLLAMA_BASE_URL=http://172.17.0.1:11434
ENABLE_OLLAMA=true

# Optional Features
# ENABLE_SIGNUP=false  # Disable public signups
# DEFAULT_USER_ROLE=user  # Role for new users
# WEBUI_AUTH=false  # Disable authentication (not recommended)

Docker Compose Configuration

The service is defined in /srv/dockerdata/open-webui/docker-compose.yml:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: unless-stopped
    env_file:
      - ./.env
    networks:
      - default
    volumes:
      - ./data:/app/backend/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.open-webui.rule=Host(`openwebui.rbnk.uk`)"
      - "traefik.http.routers.open-webui.entrypoints=websecure"
      - "traefik.http.routers.open-webui.tls.certresolver=cf"
      - "traefik.http.services.open-webui.loadbalancer.server.port=8080"

User Management

  1. First User: The first user to sign up becomes the admin
  2. User Roles:
  3. Admin: Full access to settings, user management, model configuration
  4. User: Can chat with models, manage own conversations

  5. Pending: Awaiting admin approval (if approval required)

  6. Managing Users (as admin):

  7. Navigate to Settings → Admin → Users
  8. Add, edit, or remove users
  9. Change user roles
  10. Reset passwords

Model Configuration

  1. Model Selection:
  2. Click the model dropdown in the chat interface
  3. Select from available Ollama or API models

  4. Set default model in user settings

  5. Model Parameters:

  6. Temperature: Controls randomness (0-2)
  7. Max Tokens: Maximum response length
  8. Top P: Nucleus sampling parameter

  9. Frequency Penalty: Reduce repetition

  10. Model Aliases: Create friendly names for models in Settings → Models

Common Issues and Solutions

Port 8080 vs 3000 Confusion

Issue: The .env file shows APP_PORT=3000 but the container actually runs on port 8080.

Explanation: - Open WebUI's container internally runs on port 8080 - The APP_PORT variable in the template is misleading - Traefik correctly routes to port 8080 as specified in the labels

Solution: The current configuration is correct. The Traefik label specifies: 

- "traefik.http.services.open-webui.loadbalancer.server.port=8080"

Ollama Connection Issues

Issue: "Ollama not found" or connection errors.

Solutions: 1. Verify Ollama is running: 

systemctl status ollama

  1. Test Ollama API: 

    curl http://localhost:11434/api/tags

  2. Check Docker bridge IP: 

    docker network inspect bridge | grep Gateway

  3. Ensure firewall allows local connections: 

    sudo ufw status

Model Download Failures

Issue: Models fail to download or appear stuck.

Solutions: 1. Check disk space: 

df -h /srv/dockerdata

  1. Monitor download progress: 

    journalctl -u ollama -f

  2. Retry with smaller model first: 

    ollama pull tinyllama

Authentication Problems

Issue: Cannot log in or password reset not working.

Solutions: 1. Access the SQLite database: 

docker exec -it open-webui sqlite3 /app/backend/data/webui.db

  1. For password reset, use the admin interface or contact admin

  2. If locked out completely, temporarily disable auth (not recommended for production): 

    # Add to .env: WEBUI_AUTH=false
# Restart container
# Create new admin account
# Re-enable auth

Usage Patterns and Best Practices

Conversation Management

  1. Organizing Chats:
  2. Use descriptive titles for conversations
  3. Archive completed conversations

  4. Use tags for categorization

  5. Context Management:

  6. Clear context when switching topics
  7. Use system prompts for consistent behavior

  8. Upload relevant documents for context

  9. Model Selection:

  10. Use smaller models for simple tasks
  11. Switch to larger models for complex reasoning
  12. Consider API models for latest capabilities

Prompt Engineering

  1. System Prompts: Configure default behavior in Settings → Interface
  2. Templates: Save frequently used prompts
  3. Variables: Use {{variable}} syntax for dynamic prompts

Multi-User Environments

  1. User Isolation: Each user has separate conversation history
  2. Shared Models: All users access the same model pool
  3. Resource Management: Monitor usage for fair access

Performance Considerations

Resource Usage

  1. Memory Requirements:
  2. Open WebUI container: ~500MB-1GB RAM
  3. Ollama models: 4-8GB RAM per loaded model

  4. Disk cache for embeddings and documents

  5. CPU Usage:

  6. Minimal for Open WebUI itself
  7. Ollama inference depends on model size
  8. Consider GPU acceleration for better performance

Optimization Tips

  1. Model Management: 

    # Unload models not in use
curl -X DELETE http://localhost:11434/api/generate

# Use quantized models for better performance
ollama pull llama3.1:8b-instruct-q4_0

  2. Database Maintenance: 

    # Vacuum SQLite database periodically
docker exec open-webui sqlite3 /app/backend/data/webui.db "VACUUM;"

  3. Cache Management: 

    # Clear old cache files
find /srv/dockerdata/open-webui/data/cache -mtime +30 -delete

Monitoring

  1. Container Stats: 

    docker stats open-webui

  2. Logs: 

    docker compose -f /srv/dockerdata/open-webui/docker-compose.yml logs -f

  3. Ollama Status: 

    curl http://localhost:11434/api/tags | jq

Security Considerations

API Key Management

  1. Storage: Never commit API keys to version control
  2. Permissions: Ensure .env file has restricted permissions: 
    chmod 640 /srv/dockerdata/open-webui/.env
  3. Rotation: Regularly rotate API keys
  4. Audit: Monitor API usage through provider dashboards

User Access Control

  1. Authentication:
  2. Always keep authentication enabled in production
  3. Use strong passwords

  4. Consider implementing 2FA (if supported in future versions)

  5. Authorization:

  6. Limit admin access
  7. Review user permissions regularly
  8. Disable signup if not needed: 
    ENABLE_SIGNUP=false

Network Security

  1. TLS/SSL: Always access through HTTPS (handled by Traefik)
  2. Internal Access: Ollama only accessible from localhost
  3. Firewall: Ensure only necessary ports are exposed

Data Protection

  1. Conversations: Stored in SQLite database
  2. Uploads: Stored in local filesystem
  3. Embeddings: Cached locally for performance

Backup and Data Persistence

What to Backup

  1. Database: /srv/dockerdata/open-webui/data/webui.db
  2. User accounts and settings
  3. Conversation history

  4. Model configurations

  5. Uploads: /srv/dockerdata/open-webui/data/uploads/

  6. User-uploaded documents

  7. Generated images

  8. Vector Database: /srv/dockerdata/open-webui/data/vector_db/

  9. Document embeddings for RAG

  10. Configuration: /srv/dockerdata/open-webui/.env

  11. API keys and settings

Backup Script

Create /srv/dockerdata/_scripts/open-webui-backup.sh:

#!/bin/bash
set -e

BACKUP_DIR="/srv/dockerdata/_backup/open-webui"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_NAME="open-webui-backup-${TIMESTAMP}"

# Create backup directory
mkdir -p "${BACKUP_DIR}"

# Stop container for consistent backup
cd /srv/dockerdata/open-webui
docker compose stop open-webui

# Create backup
tar -czf "${BACKUP_DIR}/${BACKUP_NAME}.tar.gz" \
  --exclude='data/cache' \
  data/ .env

# Restart container
docker compose start open-webui

# Keep only last 14 days of backups
find "${BACKUP_DIR}" -name "open-webui-backup-*.tar.gz" -mtime +14 -delete

echo "Backup completed: ${BACKUP_DIR}/${BACKUP_NAME}.tar.gz"

Restore Procedure

# Stop the container
cd /srv/dockerdata/open-webui
docker compose down

# Backup current data (just in case)
mv data data.old

# Extract backup
tar -xzf /srv/dockerdata/_backup/open-webui/open-webui-backup-TIMESTAMP.tar.gz

# Start container
docker compose up -d

# Verify restoration
docker compose logs

Automated Backups

Add to crontab: 

# Daily backup at 3:30 AM
30 3 * * * /srv/dockerdata/_scripts/open-webui-backup.sh >> /var/log/open-webui-backup.log 2>&1

Troubleshooting Guide

Container Won't Start

# Check logs
docker compose -f /srv/dockerdata/open-webui/docker-compose.yml logs

# Verify network exists
docker network ls | grep traefik_proxy

# Check permissions
ls -la /srv/dockerdata/open-webui/data

Slow Response Times

  1. Check Ollama model loading: 

    journalctl -u ollama -n 100

  2. Monitor resource usage: 

    htop
docker stats

  3. Consider using smaller/quantized models

Database Corruption

# Check database integrity
docker exec open-webui sqlite3 /app/backend/data/webui.db "PRAGMA integrity_check;"

# If corrupted, restore from backup or reset

Maintenance Tasks

Regular Maintenance

  1. Weekly:
  2. Review user activity
  3. Check disk usage

  4. Monitor API usage

  5. Monthly:

  6. Update Open WebUI image
  7. Vacuum database

  8. Review and update models

  9. Quarterly:

  10. Rotate API keys
  11. Audit user permissions
  12. Review backup retention

Updating Open WebUI

cd /srv/dockerdata/open-webui

# Pull latest image
docker compose pull

# Backup before update
/srv/dockerdata/_scripts/open-webui-backup.sh

# Restart with new image
docker compose up -d

# Monitor logs
docker compose logs -f

Integration with Other Services

LiteLLM Proxy

If using LiteLLM as a unified API proxy: 

# In Open WebUI settings, add custom model:
# Model: litellm/model-name
# API Base: http://litellm:4000
# API Key: your-litellm-virtual-key

Virtual Keys: Our LiteLLM deployment uses virtual keys for enhanced security and cost tracking. Each service gets its own virtual key with budget limits. For implementation details, see: LiteLLM Virtual Keys Implementation

Monitoring Integration

For Prometheus/Grafana monitoring, Open WebUI exposes metrics at /metrics endpoint (requires configuration).

Conclusion

Open WebUI provides a powerful, user-friendly interface for interacting with both local and cloud-based AI models. Its integration with Ollama enables completely offline AI capabilities, while support for external providers ensures access to the latest models. Proper configuration, security practices, and regular maintenance ensure a smooth and secure experience for all users.