Installing Open WebUI with Docker on macOS

This guide provides step-by-step instructions for installing Open WebUI using Docker on a macOS system, including how to make it accessible to other devices on the same network.

Prerequisites

• Docker Desktop: Ensure Docker Desktop is installed on your Mac. Download it from Docker's official website if you haven't already.
• Terminal: Familiarity with basic terminal commands.
• Internet Connection: Required for downloading Docker images and dependencies.

Step 1: Install Docker Desktop

1. Download the Docker Desktop installer for macOS from Docker's official website.
2. Run the installer and follow the on-screen instructions to complete the installation.
3. Launch Docker Desktop from your Applications folder. Ensure it is running (check the Docker icon in the menu bar).
4. Verify Docker is installed by opening a terminal and running:

   docker --version
   

   You should see output like Docker version 27.3.1, build ce12230.

Step 2: Pull the Open WebUI Docker Image

1. Open a terminal.
2. Pull the latest Open WebUI Docker image from Docker Hub by running:

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

   This command downloads the Open WebUI image to your local machine.

Step 3: Run Open WebUI Container

1. Create a directory to persist Open WebUI data (e.g., for configuration and database):

   mkdir ~/open-webui-data
   

2. Run the Open WebUI container with the following command:

   docker run -d -p 0.0.0.0:8080:8080 --add-host=host.docker.internal:host-gateway -v ~/open-webui-data:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
   

   • -d: Runs the container in detached mode.
   • -p 0.0.0.0:8080:8080: Maps port 8080 on all network interfaces of your Mac to port 8080 in the container, allowing access from other devices on the same network.
   • --add-host=host.docker.internal:host-gateway: Allows the container to communicate with the host (required for some features).
   • -v ~/open-webui-data:/app/backend/data: Persists data in the ~/open-webui-data directory.
   • --name open-webui: Names the container for easy reference.
   • --restart always: Automatically restarts the container if it stops or your Mac reboots.

Step 4: Access Open WebUI

1. Local Access: Open a web browser on your Mac and navigate to http://localhost:8080.
2. Network Access: From another device on the same network, find your Mac's local IP address by running:

   ifconfig | grep inet
   

   Look for an IP address like 192.168.x.x (commonly under the en0 or en1 interface). Then, access Open WebUI from another device by navigating to http://<your-mac-ip>:8080 (e.g., http://192.168.1.100:8080).
3. You should see the Open WebUI interface. Follow any on-screen prompts to complete the initial setup (e.g., creating an admin account).

Step 5: Managing the Open WebUI Container

• Check container status:

  docker ps
  

  Look for the open-webui container in the output.
• Stop the container:

  docker stop open-webui
  

• Start the container:

  docker start open-webui
  

• Remove the container (if needed):

  docker rm open-webui
  

  Note: This does not delete the data in ~/open-webui-data.

Troubleshooting

• Port Conflict: If port 8080 is in use, you can change the host port (e.g., -p 0.0.0.0:8081:8080) and access Open WebUI at http://localhost:8081 or http://<your-mac-ip>:8081 from other devices.
• Docker Not Running: Ensure Docker Desktop is running before executing Docker commands.
• Image Pull Issues: Verify your internet connection and ensure you have enough disk space.
• Logs: View container logs for debugging:

  docker logs open-webui
  

• Network Access Issues: Ensure your Mac's firewall allows incoming connections on port 8080. Go to System Settings > Network > Firewall, and add an exception for port 8080 if needed.

Additional Notes

• Updates: To update Open WebUI, stop and remove the container, pull the latest image, and recreate the container:

  docker stop open-webui
  docker rm open-webui
  docker pull ghcr.io/open-webui/open-webui:main
  docker run -d -p 0.0.0.0:8080:8080 --add-host=host.docker.internal:host-gateway -v ~/open-webui-data:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
  

• Data Persistence: The ~/open-webui-data directory stores configuration and data. Back it up to avoid data loss.
• System Requirements: Ensure your Mac has sufficient resources (e.g., 4GB RAM and 10GB free disk space) for smooth operation.
• Network Security: Exposing port 8080 to the network (0.0.0.0) allows access from other devices but may pose security risks. Ensure your network is secure, and consider restricting access if not needed.

For further assistance, refer to the Open WebUI documentation or community forums.