Open WebUI

Overview

A browser interface for your own language models

Open WebUI gives local models a browser chat interface with conversation history, files, and knowledge collections. It suits people who want to keep household notes, drafts, and ordinary AI conversations on their own server. It replaces the hosted-chat workflow of services such as ChatGPT or Claude; it does not include those services’ proprietary models or promise their answer quality.

This recipe runs the official Open WebUI image with a separate, internal Ollama server on CPU. No cloud API key is required. A model is downloaded separately: the small qwen3:0.6b example is suitable for checking the setup, not a benchmark for demanding work. Plan for two CPU cores, 4 GB RAM (8 GB recommended), and 10 GB disk before larger models, growing data, and backups. These are planning estimates. Both images support amd64/arm64; only amd64 was exercised.

Data and security

The administrator is created from private .env values at first startup; there is no shared default password. Registration and external OpenAI-compatible providers start disabled. Ollama has no host port and cloud use is disabled. The recipe runs both servers as UID/GID 1000 with read-only root filesystems, writable data volumes, and temporary storage. Preserve OPEN_WEBUI_SECRET across updates and recovery: it protects sessions and encrypted settings.

Ordinary model chats, files, and settings are server-side data, not end-to-end encrypted by this recipe. Administrator Functions and Tools can run server-side code; grant that role only to trusted people. OIDC, MFA, and trusted-header login exist upstream but are not configured here. Do not enable trusted-header authentication behind a proxy that accepts client-supplied identity headers. Image CVEs have not been scanned and remain unknown.

A healthy web page does not prove that a model works. The amd64 smoke performs real local generation, saves a chat and file, removes both volumes, restores them, verifies the exact file and model digest, and generates another response. It does not benchmark accuracy, GPU support, large models, voice, or RAG retrieval. Model output can be wrong: review it before using it.

License and operations

The Open WebUI License contains BSD-style terms plus branding conditions, so the catalog records it as source available. The 50-user threshold concerns permission to change branding; ordinary use with the original branding is not capped at 50 users. This recipe keeps the application’s branding. Ollama uses MIT; the downloaded Qwen3 0.6B example uses Apache-2.0. Other models may have other restrictions.

One backup archives both persistent volumes and the active configuration while both writers are stopped. It includes SQLite, uploads, local vector/cache data, model weights, and secrets. Saved UI configuration can override initial environment defaults; inspect registration, providers, and sharing permissions after recovery. Read release notes before each update and restore the pre-update data with matching versions for rollback.

Sources: Open WebUI documentation, v0.12.4, license, Ollama, Qwen3 0.6B. The catalog SVG mark is the Open WebUI icon from LobeHub Icons; the running app’s branding is unchanged.

Step-by-step guide

Requirements and preparation

Use 64-bit Ubuntu 22.04+ or Debian 12+ with Docker Engine and Compose v2.24+. Plan for 2 CPU cores, 4 GB RAM (8 GB recommended), and 10 GB disk plus larger models, user data, and backups. This recipe is CPU-only; no GPU devices or Docker socket are mounted.

mkdir -p ~/services/open-webui
cd ~/services/open-webui
# Copy the complete recipe, scripts, and proxy/ here.
cp .env.example .env
chmod 600 .env
# Run twice: one service secret, one independent initial admin password.
openssl rand -hex 32
openssl rand -hex 32

Replace the two placeholders before starting. Every .env.example parameter:

The scripts source .env as trusted shell configuration. Keep it private. Changing bootstrap email/password variables does not rotate an existing account. Some UI settings persist in SQLite and can override initial environment defaults.

Start and sign in

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 600
curl --fail http://127.0.0.1:3080/health/db

The permissions helper exits after assigning both volumes to UID/GID 1000; both servers then run without root. Open OPEN_WEBUI_URL and sign in with the configured administrator email/password. If remote, first use ssh -L 3080:127.0.0.1:3080 user@server and the matching local URL. Verify the admin account and closed registration before exposing a proxy. Choose a language and theme in personal settings. There is no shared default password.

Download and test a model

A running Ollama server initially has no chat model. Download one deliberately; this needs internet and disk space:

docker compose exec ollama ollama pull qwen3:0.6b
docker compose exec ollama ollama list

Refresh the model list in Open WebUI, select qwen3:0.6b, and send a short message. The example is about a 522 MB download, with additional runtime RAM; it is small and can give poor answers. Use its Apache-2.0 terms and review another model’s license before downloading it. The tag may change upstream; the backup preserves the downloaded weights. Larger contexts and models need more RAM and disk. Keep Ollama internal. OFFLINE_MODE=true avoids Open WebUI model/update downloads; the image includes its default embedding cache, and explicit Ollama model pulls remain possible. External providers, GPU, plugins, voice, and web search are not configured.

VPS

Set the external HTTPS OPEN_WEBUI_URL, configure the proxy, and allow only SSH/HTTP/HTTPS through the firewall. Keep port 3080 on loopback and leave Ollama without a host port. Use a strong administrator password and encrypted off-server backups. A low-cost CPU VPS may answer slowly; size it for the chosen model rather than the web page.

Trusted local network

Use the SSH tunnel for personal access, or an HTTPS proxy for the LAN. If you deliberately bind to a private IP, restrict it with a firewall and keep authentication enabled. Match OPEN_WEBUI_URL to the browser origin; a different origin can break websocket/CORS checks. Do not expose Ollama as an unauthenticated LAN API.

Domain and HTTPS

Use a sample from proxy/: Caddy obtains certificates; Nginx needs certificate paths; Traefik needs websecure and a letsencrypt resolver. Samples run on the host and forward to 127.0.0.1:3080. A containerized proxy needs a shared network and the internal app port 8080.

Set OPEN_WEBUI_URL=https://chat.example.com and the proxy’s real IP/CIDR in OPEN_WEBUI_TRUSTED_PROXIES, then recreate with docker compose up -d --wait --wait-timeout 600. The proxy must support websocket upgrades and long inference responses. The Nginx sample permits 100 MB requests. Forwarded-header trust is separate from trusted-identity login, which this recipe leaves disabled. Review persisted UI settings after changes.

Backup

./backup.sh

The script stops both writers and archives both complete volumes, .env, and Compose into backups/open-webui-<timestamp>.tar with mode 600. Each server’s previous running/stopped state is preserved. Weight archives can be large and backup time can interrupt active chats. Encrypt and copy the archive off-server: it holds private chats, files, models, initial credentials, and service secrets. Copying a live SQLite file or only exporting a chat is not a full backup.

Restore

Restore replaces both volumes. Use trusted archives, matching application/Ollama versions, and the original OPEN_WEBUI_SECRET. Compare archived configuration.env with active .env before restoring; it is not activated automatically.

# On a fresh host initialize the matching recipe first.
docker compose up -d --wait --wait-timeout 600
./restore.sh ./backups/open-webui-TIMESTAMP.tar
curl --fail http://127.0.0.1:3080/health/db

The payload is validated before replacement and a safety backup is created. A file-replacement failure leaves both servers stopped. After recovery, sign in, reopen a saved chat, download a file, and generate a new answer with a restored model. Recheck registration, providers, and sharing settings. The amd64 smoke removes both original volumes and verifies these operations, including the model digest and exact file bytes.

Update

Read upstream release notes and model compatibility notes. Back up, keep an off-server copy, and change the reviewed exact tag in .env:

docker compose pull
docker compose up -d --wait --wait-timeout 600
docker compose logs --tail=100 open-webui ollama

App migrations run at startup. Ollama has an independent version: review its release notes before changing it. Do not change the service secret casually. Do not use latest, assume 0.x API compatibility, or remove branding outside the license’s exceptions.

Rollback

Never start an older app on a database migrated by a newer release. Stop both servers, set their old exact tags and original secret in .env, and recreate without starting:

docker compose stop open-webui ollama
# Edit both reviewed versions and preserve OPEN_WEBUI_SECRET.
docker compose pull open-webui ollama
docker compose create open-webui ollama
./restore.sh ./backups/open-webui-BEFORE-UPDATE.tar

The safety backup reads stopped volumes without launching the old app against new data. Restore the complete matching archive and verify a chat, file, and local inference. Keep the failed installation’s backup until recovery is confirmed.

Stop and remove

docker compose down keeps both volumes. After verifying an off-server backup, docker compose down --volumes permanently deletes accounts, chats, files, model weights, and Ollama state. Removing the recipe directory also removes local backups and .env.

Sources: documentation, environment configuration, v0.12.4, Ollama, Qwen model, license.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

Startup, permissions, or healthcheck failure

Run docker compose ps, docker compose logs --tail=100 open-webui ollama, and docker compose config --quiet. Check free disk/RAM, pinned tags, and that the permissions helper completed. The app healthcheck uses /health/db; Ollama uses ollama list. Both data volumes must be writable by UID/GID 1000. Do not remove authentication or run privileged to bypass a permissions problem.

No models or no answer

A healthy Ollama is not a downloaded model. Run docker compose exec ollama ollama list, pull the reviewed example, and refresh Open WebUI’s model list. Check the local provider URL http://ollama:11434; this is an internal address, not a browser URL. OLLAMA_NO_CLOUD=true deliberately disables cloud use. Large models, long contexts, and several simultaneous requests can exhaust RAM. Inspect docker stats and the logs; use a smaller model/context or a larger server.

Wrong password or registration policy

The bootstrap password/email applies only to an empty user database. Change an existing password in the UI, not by editing the initial environment. Registration starts disabled, but saved UI settings can override defaults. Review the administrator security/provider settings after updates and recovery. The recipe does not supply shared login credentials.

CORS, websocket, or proxy errors

Match OPEN_WEBUI_URL to the exact browser origin. Check websocket upgrades and proxy timeouts. OPEN_WEBUI_TRUSTED_PROXIES must name the actual forwarding proxy; do not use *. A containerized proxy cannot reach the host’s loopback by using its own 127.0.0.1. Never expose the Ollama API to fix a browser proxy issue.

Missing files, chats, or models after recovery

Restore the complete backup archive containing both data payloads with the original service secret and matching app/Ollama versions. A chat export omits uploads, model weights, and settings. Re-login, open a saved chat, download a file, and test generation. Compare the archived environment by hand. Preserve the current volumes and the safety backup while investigating.

Sources: environment configuration, documentation, Ollama.