Add howto/openwebui.md
This commit is contained in:
parent
6786d852a4
commit
fe4eaf22d4
205
howto/openwebui.md
Normal file
205
howto/openwebui.md
Normal file
|
|
@ -0,0 +1,205 @@
|
||||||
|
# Setup Guide for Open WebUI on Ubuntu 24.04 with Nginx
|
||||||
|
|
||||||
|
This guide provides a complete, step-by-step walkthrough for deploying [Open WebUI](https://github.com/open-webui/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](#1-prerequisites)
|
||||||
|
2. [Step 1: Install Docker](#2-step-1-install-docker)
|
||||||
|
3. [Step 2: Run Open WebUI Container](#3-step-2-run-open-webui-container)
|
||||||
|
4. [Step 3: Expose to the Public Internet](#4-step-3-expose-to-the-public-internet)
|
||||||
|
5. [Step 4: Configure Authentication](#5-step-4-configure-authentication)
|
||||||
|
6. [Step 5: Updating the Application](#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
|
||||||
|
```bash
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install ca-certificates curl gnupg -y
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2. Add Docker's Official GPG Key
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
```bash
|
||||||
|
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`.
|
||||||
|
```bash
|
||||||
|
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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
```bash
|
||||||
|
sudo apt install nginx -y
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2. Configure Firewall
|
||||||
|
```bash
|
||||||
|
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.
|
||||||
|
```bash
|
||||||
|
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.**
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
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.
|
||||||
|
```bash
|
||||||
|
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.
|
||||||
|
```bash
|
||||||
|
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.
|
||||||
|
```bash
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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](https://containrrr.dev/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:
|
||||||
|
```bash
|
||||||
|
docker run -d \
|
||||||
|
--name watchtower \
|
||||||
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||||
|
--restart always \
|
||||||
|
containrrr/watchtower
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue