Michael Limberger

One compose file, then the window

One Docker command and you have a ChatGPT-like interface on your Mac. Instead of a long docker run line, we use Docker Compose: a YAML file that describes how to run the container. YAML here is just labeled settings in a text file.

Show me.

mkdir ~/open-webui
cd ~/open-webui

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

Save that as docker-compose.yml in the folder, then run:

docker compose up -d

Docker pulls the image (about 2GB) and starts OpenWebUI in the background. That is the whole install for most people.

The image is the official OpenWebUI build from GitHub Container Registry. The :main tag is the latest stable line. Ports map 3000 on your Mac to 8080 inside the container, so you browse http://localhost:3000. The named volume holds conversations, settings, uploads, and accounts. Stop and restart and nothing is lost. The extra_hosts line is for Colima compatibility. Docker Desktop already provides host.docker.internal; Colima needs this so OpenWebUI can find Ollama on the Mac. restart: always brings the container back after a crash or after Docker itself starts.

Check status with docker compose ps. You want Status Up. If it is restarting or missing, run docker compose logs. Then open http://localhost:3000 in a browser. If you get a connection error, give it about 30 seconds. First startup initializes the database.

The first account is admin

+-------------------------------------------------------+
|  IMPORTANT                                            |
|                                                       |
|  The first account you create automatically becomes   |
|  the Administrator. This controls who else can use    |
|  the system and what features are available.          |
+-------------------------------------------------------+

Everything here is local. The email does not need to be a real address. It is only a login credential on your machine. After signup you land on the chat screen. It will feel familiar if you have used ChatGPT.

OpenWebUI usually finds Ollama automatically. From Docker it talks through http://host.docker.internal:11434, which is Docker's way of saying "the host machine" from inside a container. Ollama runs on the Mac, not inside Docker. This bridge is what lets them talk. If auto-detect works, models appear in the dropdown. If the dropdown is empty, configure the connection by hand.

Click the profile icon at the bottom left, open Admin Panel, then Settings, then Connections. Under Ollama, click the wrench (Manage). Enter http://host.docker.internal:11434. Hit the check mark to verify. When you get a green check, the models should appear.

Why Compose instead of a long docker run: the file is readable, repeatable, and easy to update (pull, then recreate). It also lives in a folder you can back up. Prefer Python? You can pip install open-webui then open-webui serve. That path uses port 8080 (not 3000) and talks to localhost:11434 directly. We recommend Compose for this talk. Pip works too if that is your preference.

docker compose down
docker compose up -d
docker compose logs -f
docker compose pull
docker compose up -d

Your data lives in the named volume, not inside the container image. Next: pull some models.