Open WebUI has a quick start with docker guide. Yeah, that’s a bit too quick - not very sustainable if you want to get more out of this.

I’ll try to make this really detailed so anyone can follow along.

Prerequisites

  • macOS 14.5 or later. May work with earlier versions 🤷‍♂️
  • Terminal access

System Preparation

Install Docker Desktop

Install Docker Desktop from the official website if not already installed. Open Terminal and ensure Docker is running, with this command:

docker --version

Install Ollama

Install Ollama on macOS if not already installed.

Download at least one local model with the ollama run <modelname> command in terminal. You need at least one model installed to get anything out of open-webui.

For llama3.1 8B

ollama run llama3.1:latest

or a smaller model like Gemma 2B

ollama run gemma2:2b

or use anything other model from here.

Install Open WebUI

Create the openwebui directory

In terminal, run these commands. Update both commands to reflect the path you want the open-webui folder in.

mkdir -p ~/Software/open-webui &&
cd ~/Software/open-webui

This creates a directory, and goes to the newly created directory.

Configure your Open WebUI installation

Create a compose.yaml configuration file that defines and configures your open-webui installation. This is the step missing from most quick install guides. This will build your configuration in more scalable and secure way, and help you persist the configuration across installs.

touch compose.yaml

Open the file in any text editor and add the following content:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main  # Use the official open-webui image
    container_name: open-webui  # Set a custom name for the container
    ports:
      - "3000:8080"  # Map host port 3000 to container port 8080
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434  # Point to local Ollama instance
    volumes:
      - open-webui:/app/backend/data  # Mount a volume for persistent data storage
    restart: always  # Automatically restart the container if it stops

volumes:
  open-webui:  # Define a named volume for data persistence

💾 Save the file and close the editor.

✨ Done!

Start Open WebUI using Docker Compose

Run this command. It will take a bit of time the first time to download the open-webui image.

docker compose up -d

Explanation:

  1. docker compose up starts the services defined in your compose.yaml file
  2. The -d flag runs the containers in detached mode (in the background) so you can close your terminal session.

Read more at docker if interested.

This command will:

  1. Pull the necessary Docker images if they’re not already present
  2. Create and start the containers as defined in your compose.yaml
  3. Set up the network and volumes
  4. Run the containers in the background, allowing you to close your terminal

🚀 Access Open WebUI

Access Open WebUI at http://localhost:3000

You’ll need to create a username and password. Use any random email address, name and password. It’s all stored locally on your device.

Stopping Open WebUI

If you ever want to stop Open WebUI there are two ways to do it:

  1. the easy way: Open Docker from your macOS Dock. Click Container on the left, and “stop” the open-webui container.
  2. the quick way: Run this in terminal
cd ~/Software/open-webui && docker compose down

(Re)Starting Open WebUI

If you ever want to (re)start Open WebUI there are two ways to do it:

  1. the easy way: Open Docker from your macOS Dock. Click Container on the left, and “play” the open-webui container.
  2. the quick way: Run this in terminal
cd ~/Software/open-webui && docker compose up -d