gist/howto/openwebui.md

Setup Guide for Open WebUI on Ubuntu 24.04 with Nginx

This guide provides a complete, step-by-step walkthrough for deploying Open WebUI on an Ubuntu 24.04 server. It covers Docker installation, running the application, exposing it securely to the internet with Nginx and a free Let's Encrypt SSL certificate, and how to perform updates.

Table of Contents

1. Prerequisites
2. Step 1: Install Docker
3. Step 2: Run Open WebUI Container
4. Step 3: Expose to the Public Internet
5. Step 4: Configure Authentication
6. Step 5: Updating the Application

---

1. Prerequisites

Before you begin, ensure you have the following:

• An Ubuntu 24.04 server.
• sudo or root access.
• A domain name (e.g., my-webui.com) with its DNS A record pointing to your server's public IP address.
• Ports 80 (HTTP) and 443 (HTTPS) open in your server's firewall.

---

2. Step 1: Install Docker

We will use Docker to run Open WebUI in an isolated container, which is the recommended method.

2.1. Update System and Install Prerequisites

sudo apt update
sudo apt install ca-certificates curl gnupg -y

2.2. Add Docker's Official GPG Key

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

2.3. Set Up the Docker Repository

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.4. Install Docker Engine

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

2.5. (Recommended) Run Docker as a Non-Root User

This allows you to run docker commands without sudo.

sudo usermod -aG docker $USER

IMPORTANT: You must log out and log back in for this change to take effect.

---

3. Step 2: Run Open WebUI Container

Now, run the Open WebUI container. This command will also create a persistent volume (open-webui) to store all your data, like user accounts and chat history.

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

The application will now be running and accessible locally on your server at http://localhost:3000.

---

4. Step 3: Expose to the Public Internet

We will use Nginx as a reverse proxy to securely serve the application over HTTPS on your domain.

4.1. Install Nginx

sudo apt install nginx -y

4.2. Configure Firewall

sudo ufw allow 'Nginx Full'
sudo ufw reload

4.3. Create Nginx Configuration File

Replace yourdomain.com with your actual domain name in the command below.

sudo nano /etc/nginx/sites-available/yourdomain.com

Copy and paste the following configuration into the editor. Remember to replace yourdomain.com in the server_name line.

server {
    listen 80;
    listen [::]:80;

    server_name yourdomain.com www.yourdomain.com; # <-- REPLACE THIS

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Required for WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Save the file and exit (Ctrl+X, then Y, then Enter).

4.4. Enable the Site and Test Nginx

Replace yourdomain.com with your domain.

sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4.5. Obtain SSL Certificate with Certbot

Install Certbot and run it to automatically get an SSL certificate and configure Nginx for HTTPS. Replace yourdomain.com and your-email@example.com with your details.

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com --non-interactive --agree-tos -m your-email@example.com --redirect

Your Open WebUI is now live and secure at https://yourdomain.com.

---

5. Step 4: Configure Authentication

Choose one of the following two options.

Option A: Standard (Recommended) - With Authentication

By default, Open WebUI requires users to sign up and log in. The first user to register on your site automatically becomes an administrator. You can then manage users and registration settings from the admin panel. This is the secure and recommended approach.

No extra steps are needed if you want this behavior.

Option B: Public Access - No Authentication

If you want anyone with the link to use your instance without logging in, you must disable authentication.

⚠️ Warning: This is not recommended for most use cases as it allows anyone to consume your server resources (CPU/RAM/GPU). Proceed with caution.

To disable auth, you must recreate the container with an environment variable.

# Stop and remove the old container
docker stop open-webui
docker rm open-webui

# Run the new container with authentication disabled
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  -e WEBUI_AUTH=False \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

---

6. Step 5: Updating the Application

A running container is not automatically updated when a new image is pulled. You must recreate the container to use the new image. Your data will be safe because it is stored in the open-webui volume.

6.1. Manual Update (Recommended for Control)

This is the standard, reliable way to update.

# 1. Pull the latest image
docker pull ghcr.io/open-webui/open-webui:main

# 2. Stop the currently running container
docker stop open-webui

# 3. Remove the old container
docker rm open-webui

# 4. Run a new container using the new image and your existing data
# (Include any custom environment variables like -e WEBUI_AUTH=False if you use them)
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

6.2. Automated Update (with Watchtower)

For convenience, you can use Watchtower to automate the update process. Watchtower will monitor for new images and automatically perform the stop, remove, and recreate steps for you.

Run Watchtower once, and it will handle updates for all your containers:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --restart always \
  containrrr/watchtower