How to Install and Configure OpenWebUI

What is OpenWebUI?

OpenWebUI is an open-source web interface for interacting with language models (LLMs) like GPT, Claude, or local models via Ollama. It turns one or more LLMs into a full multi-user chat application, with access control, conversation history, and most importantly RAG (Retrieval-Augmented Generation) features to query your own documents.

For a business, it is a self-hosted alternative to ChatGPT: your data stays with you, you choose your models, and you keep control over costs.

For a professional setup tailored to your constraints, our AI development agency supports you from installation to optimization.

Prerequisites

Before installing OpenWebUI, plan for:

Docker and Docker Compose installed (recommended method), or Python 3.11+ for a pip-based install.
2 GB of RAM minimum for the interface alone; 8 GB or more if you run local models via Ollama.
A GPU (optional) to speed up local inference and embedding generation.
An API key (OpenAI, Anthropic...) if you use cloud models instead of local ones.

Installing OpenWebUI

Method 1: Docker (recommended)

The fastest way to launch OpenWebUI is via Docker. A single command is enough:

docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main

The interface is then available at http://localhost:3000. The open-webui volume ensures your data (accounts, conversations, documents) persists after a container restart.

Method 2: Docker Compose

For a reproducible, version-controlled setup, use a docker-compose.yml file:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - WEBUI_SECRET_KEY=change-this-key
    restart: unless-stopped
volumes:
  open-webui:

Then start it with docker compose up -d. This approach makes it easy to later add Ollama, a vector database, or a reverse proxy to the same stack.

Method 3: OpenWebUI + Ollama (local models)

To run models fully locally (privacy, no per-token cost), pair OpenWebUI with Ollama. The bundled image ships both:

docker run -d -p 3000:8080 -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:ollama

Then pull a model, for example docker exec -it open-webui ollama pull llama3.1.

Method 4: Install via pip

If you prefer to avoid Docker, OpenWebUI installs as a Python package:

pip install open-webui

open-webui serve

The interface starts at http://localhost:8080. This method is fine for local testing, but Docker remains preferable in production.

First configuration

1. Create the administrator account

On first login, the first account created automatically becomes the administrator. It controls users, permissions, and global settings.

2. Connect your models

OpenAI (GPT-4o, GPT-4.1...): enter your API key under Settings then Connections.
Anthropic Claude: add the key via an OpenAI-compatible connection or a dedicated function.
Local models: point to your Ollama server (http://localhost:11434 by default).

3. Key environment variables

OPENAI_API_KEY: your OpenAI API key.
WEBUI_SECRET_KEY: session signing secret, mandatory in production.
WEBUI_URL: public URL of your instance (webhooks, OAuth, callbacks).
DATA_DIR: data directory (default /app/backend/data).

Configuring RAG: querying your documents

The real value of OpenWebUI in a company is RAG: asking natural-language questions about your own documents. Answer quality depends entirely on the configuration. Here are the main levers.

1. Chunking (document segmentation)

Chunking sets the size and overlap of the indexed text fragments. Adjust it to the content type:

Long technical documents: 400-600 characters, overlap 50-100.
Short content (FAQ, notes): 200-300 characters, overlap 20-30.
Scientific or legal documents: 600-800 characters, overlap 100-150 to preserve context.

2. Embedding model

text-embedding-3-small (1536 dim): good performance/cost balance, ideal to start.
text-embedding-3-large (3072 dim): better accuracy on complex content, higher cost.
Local models (BGE, E5, Sentence-BERT): for sensitive data to be processed offline.

3. Hybrid search (BM25 + vectors)

Product/catalog search: BM25 weight 0.6-0.7 to favor exact matches.
Conceptual search: BM25 weight 0.3-0.4 to prioritize semantic similarity.
General balance: BM25 weight 0.5.

4. Reranker and Top K

Initial Top K: 3-5 documents.
Top K after reranking: 2-3 documents.
Relevance threshold: 0.15-0.25 to filter out noise.

5. Metadata and filters

Add fields like collection, type, year, author.
Filter queries to limit search to the right subsets.
Maintain an index/glossary for exact matches.

Going to production

Enable authentication and define roles and permissions.
Put OpenWebUI behind a reverse proxy (Nginx, Traefik) with HTTPS.
Set a strong WEBUI_SECRET_KEY and enable rate limiting.
Back up the data volume and the vector database regularly.

Updating: with Docker, pull the latest image then recreate the container:

docker pull ghcr.io/open-webui/open-webui:main

Watchtower can automate this step.

Common issues

Blank page or port in use: check that no service already listens on port 3000 and adjust the -p mapping.
Ollama models not showing: confirm the server URL and network connectivity between containers.
RAG answering off-topic: review chunking and the embedding model before blaming the LLM.
Data lost on restart: a missing Docker volume is almost always the cause.

When the default configuration is no longer enough

Installing OpenWebUI takes ten minutes. Getting a reliable, fast, and cost-efficient RAG on real volumes is another story. Default settings rarely hold up once the stakes get serious. Situations that call for real engineering:

Exhaustiveness and precision: when missing a single answer is not acceptable (support, legal, compliance), you must work on recall, reranking, and evaluation.
Performance and latency: at scale, indexing architecture and vector database choice make the difference between a 1-second and a 15-second answer.
Costs too high: embeddings, tokens, and model calls can quickly spiral; the right local/cloud mix and caching change everything.
Integration into an agentic flow: connecting RAG to tools, actions, and other agents requires custom orchestration.
Privacy and GDPR: sensitive data, sovereign hosting, anonymization, and access traceability.
Regulatory constraints: healthcare, finance, or the public sector impose requirements the standard setup does not cover.

If this sounds like your case, it is exactly what we work on. Let's talk about your RAG project or explore our AI agency.

How to Install and Configure OpenWebUI: Complete Guide 2026