Deploy Open WebUI with Docker and Persistent Storage

Scope and verification status

This guide covers a Linux Docker Engine deployment with a separately installed Ollama backend. It provides deployment references and functional self-checks, not a claim that this site has tested a complete installation. Official documentation was checked on 10 October 2026; commands were statically reviewed. Image startup, inference, TLS and recovery have not been tested here.

Open WebUI is the interface; Ollama runs the models. Record docker version, ollama --version and the selected Open WebUI release before troubleshooting. The example uses Docker bridge networking, not host networking. Docker Desktop, rootless Docker and custom networks can behave differently. Use a supported Docker release that understands host-gateway. Docker's localhost publishing warning for releases older than 28.0.0 means loopback binding is not an absolute isolation guarantee on those versions; see the port publishing documentation.

Resources, data and access boundaries

There is no verified universal CPU/RAM/disk minimum in this article. Size the interface for concurrent users, uploads and enabled features; separately size Ollama for model size, quantization and context. Allow space for images, application data and models. A small web server does not automatically have enough memory for inference.

Keep /app/backend/data persistent and WEBUI_SECRET_KEY stable. Back up data before upgrades, keep the secret separately protected and test restoration on a copy. Do not delete the volume to fix a connection error. Disable nonessential sign-ups after administrator setup; do not expose an uninitialized instance publicly. Expose an authenticated HTTPS interface, not the raw Ollama API.

Step 1: Establish the Ollama prerequisite

Have Ollama installed and running using its official installation and service instructions. This article does not install Ollama or select a model for your hardware. On the Ollama host, inspect the version and existing models:

ollama --version
ollama list
curl --fail --silent --show-error --max-time 10 http://127.0.0.1:11434/api/tags

A working local endpoint returns JSON with a models array. An empty array is different from a connection failure: obtain a suitable model through the official workflow only after checking its resource and download requirements. Use an already installed model for the checks below. If your service uses a different address, check that approved address instead. Do not start a second ollama serve over an existing service.

Step 2: Choose a safe network path

Inside a bridge container, 127.0.0.1 refers to that container, not the Linux host. --add-host=host.docker.internal:host-gateway adds a hostname mapping to a host-side address; it does not change what interfaces Ollama listens on. Ollama defaults to host loopback on port 11434. Consequently the example in Step 4 is conditional: it needs an Ollama endpoint that is actually reachable from that bridge network.

Before using the example, review listening addresses and network access controls with the host administrator. A host-side private interface reachable by the intended container, with access restricted to necessary sources, is different from a public endpoint. If no such path exists, stop here and consult the official connection guide and Ollama networking FAQ. Do not blindly set a wildcard listener or open port 11434 to the Internet. A private address alone is not access control.

Alternative topologies require their own configuration: a backend container can use a shared private Docker network and service name; a remote backend needs a protected private path; Linux host networking changes port publication and isolation, so it is not a drop-in replacement for this bridge command. No universal firewall or listening-address change is prescribed here. The following checks identify whether your chosen path works; they do not establish its security by themselves.

Step 3: Prepare persistent storage and a secret

Use an account authorized to manage Docker. Docker administrative access is privileged; do not grant it indiscriminately. Check the daemon as well as the client:

docker version
docker volume create open-webui
openssl rand -hex 32

Expected: docker version includes a responding server; volume creation returns open-webui; the secret generator returns 64 hexadecimal characters. Save that value once in a private open-webui.env file using your editor, as WEBUI_SECRET_KEY=<your generated value>. Replace the placeholder, restrict file access to the deployment owner, and exclude the file from version control, screenshots and shared logs. Docker administrators can inspect container environment values; an env file does not hide secrets from them. Keep the same value across recreation and upgrades.

Step 4: Start the interface container

The official main tag is a moving evaluation image. For production, replace it with a release reviewed for your architecture, retain its version/digest, and read release notes before upgrading. We have not tested a particular release here. The official quick start explains supported image choices.

Run this reference only after Step 2's network prerequisite and the private env file are ready. Check that the name and port do not belong to another deployment; do not remove an existing container or data volume blindly.

docker run -d \
  -p 127.0.0.1:3001:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --env-file ./open-webui.env \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

Expected: a container ID is returned; this is not proof the application or model backend is ready. The UI is published to the host's loopback port 3001. On a remote server, your laptop's localhost is not the server: use an approved secure tunnel or the HTTPS setup below, not an unprotected public port mapping.

Step 5: Verify each layer

First inspect the container and the local HTTP response:

docker ps -a --filter name=open-webui
docker logs --tail=100 open-webui
curl --fail --silent --show-error --max-time 20 -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/

Expected: the container remains running, logs do not show a fatal startup loop, and the local page returns an expected successful HTTP response. Open the page through your approved access path. A page response proves neither backend connectivity nor inference. Logs can contain sensitive information; redact them before sharing.

If the chosen image includes Python, the following diagnostic checks the Ollama endpoint from inside the container without downloading a model:

docker exec -i open-webui python - <<'PY'
import json, urllib.request
with urllib.request.urlopen('http://host.docker.internal:11434/api/tags', timeout=10) as response:
    data = json.load(response)
if not isinstance(data.get('models'), list):
    raise SystemExit('Unexpected model-list response')
print([model.get('name') for model in data['models']])
PY

A list of existing model names shows that this container can reach that endpoint. [] means no models were returned. Connection refusal/timeout or name resolution errors point to service, routing, listening or access-control issues. If the image has no python, this diagnostic is unavailable; do not install tools into a production container merely to run it. Check the connection in the UI and consult version-specific documentation instead. Change the diagnostic URL only to match your approved topology.

Then create the administrator through the protected interface, review sign-up/access settings, and inspect the Ollama connection in the administration settings. UI labels may change by release. Confirm that its URL matches the approved backend and that the model selector lists the existing model; saved application settings may differ from an environment variable. Select it, send a short test message, and check that an actual assistant reply completes. No visible models: check the connection and model list first. A selected model but no reply: inspect backend logs, memory/accelerator resources, and proxy streaming/WebSocket behavior. Do not fix either case by deleting application data.

Optional backend response check

On the Ollama host, replace EXISTING_MODEL_NAME with an exact name returned by the model list before running this request. It performs inference and consumes resources; skip it if no suitable model is already available. With stream:false, inspect message.content and done:true; an HTTP response alone is insufficient. A reasoning model may also take time or return separate thinking data.

curl --fail --silent --show-error --max-time 120 \
  http://127.0.0.1:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"model":"EXISTING_MODEL_NAME","messages":[{"role":"user","content":"Reply with a short greeting."}],"stream":false}'

A timeout is not automatically an installation failure. This host-side test does not replace a completed conversation through WebUI. API references: model list and chat.

Step 6: Caddy HTTPS configuration reference

This is Caddyfile syntax, not a shell command and not a claim of tested HTTPS. It assumes Caddy runs on the same host and can reach port 3001, that you control the replacement domain, DNS points to this host, and the required certificate-validation path and ports are available. A Caddy container has its own loopback and needs a separately designed upstream path. Back up and review your existing configuration before adding a site; do not overwrite other sites.

openwebui.example.com {
    reverse_proxy 127.0.0.1:3001
}

Replace the example domain in a reviewed configuration file. Unlike the previous all-comment example, these lines declare a site. On your own test/deployment host, validate the complete intended file before an authorized reload:

caddy validate --config ./Caddyfile --adapter caddyfile

Validation is not proof of DNS, certificate issuance, authentication or model streaming. Follow the Caddy command documentation and automatic HTTPS prerequisites. After an approved reload, check the correct HTTPS domain, certificate, login policy and a completed chat. Keep the backend API private.

Failure boundaries and recovery

• Container exits: check its logs, daemon access, image/architecture, env file and name/port collisions.
• Host model list works but the container cannot reach it: check the actual network mode, gateway mapping, Ollama listener and source restrictions.
• Model selector is empty: distinguish a failed connection from an empty backend model list; inspect the saved connection URL.
• Model is present but replies fail: check model resources and logs, then the UI/proxy path. A successful homepage is not the finish line.
• After an upgrade: retain the same data volume and secret. Restore only a verified backup through a reviewed recovery plan, preferably tested on a copy; do not run destructive cleanup as troubleshooting.

The complete user-side success condition is: persistent interface running, protected browser access, a reachable intended backend, a visible model and a completed reply. This article supplies checks for those conditions; it does not assert that this site has executed them all.