khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2025-12-12 07:29:49 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #873 from open-webui/main

Browse Source
This commit is contained in:
Classic298
2025-12-02 23:39:44 +01:00
committed by GitHub
parent 58901d0376 be7d7e22fd
commit 47d0014ecd
3 changed files with 660 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

554
docs/getting-started/updating.mdx
View File

@@ -3,62 +3,155 @@ sidebar_position: 300
title: "Updating Open WebUI" title: "Updating Open WebUI"
--- ---
## Why isn't my Open WebUI updating? import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
To update your local Docker installation of Open WebUI to the latest version available, you can either use **Watchtower** or manually update the container. Follow either of the steps provided below to be guided through updating your existing Open WebUI image. ## Overview
### Manual Update Keeping Open WebUI updated ensures you have the latest features, security patches, and bug fixes. You can update manually or automate the process using container update tools.
1. **Stop and remove the current container**: :::info Before Updating
- **Backup your data** before major version updates
- **Check release notes** at https://github.com/open-webui/open-webui/releases for breaking changes
- **Clear browser cache** after updating to ensure the latest web interface loads
:::
This will stop the running container and remove it, but it won't delete the data stored in the Docker volume. (Replace `open-webui` with your container's name throughout the updating process if it's different for you.) ## Manual Update
```bash Manual updates give you complete control and are recommended for production environments or when you need to review changes before applying them.
### Step 1: Stop and Remove Current Container
This stops the running container and removes it without deleting your data stored in the Docker volume.
```bash title="Terminal"
# Replace 'open-webui' with your container name if different
# Use 'docker ps' to find your container name if unsure
docker rm -f open-webui docker rm -f open-webui
``` ```
2. **Pull the latest Docker image**: :::tip Find Your Container Name
If your container isn't named `open-webui`, find it with:
This will update the Docker image, but it won't update the running container or its data.
```bash ```bash
docker ps -a | grep open-webui
```
Look in the "NAMES" column for your actual container name.
:::
### Step 2: Pull Latest Docker Image
Download the newest Open WebUI image from the container registry.
```bash title="Terminal"
docker pull ghcr.io/open-webui/open-webui:main docker pull ghcr.io/open-webui/open-webui:main
``` ```
:::info **Expected output:**
```
**Remove any existing data in the Docker volume (NOT RECOMMENDED UNLESS ABSOLUTELY NECCESSARY!)**. Skip this step entirely if not needed and move on to the last step: main: Pulling from open-webui/open-webui
Digest: sha256:abc123...
If you want to start with a clean slate, you can remove the existing data in the Docker volume. Be careful, as this will delete all your chat histories and other data. Status: Downloaded newer image for ghcr.io/open-webui/open-webui:main
The data is stored in a Docker volume named `open-webui`. You can remove it with the following command:
```bash
docker volume rm open-webui
``` ```
:::note About Data Persistence
Your chat histories, settings, and uploaded files are stored in a Docker volume named `open-webui`. Pulling a new image does **not** affect this data. The volume persists independently of the container.
::: :::
3. **Start the container again with the updated image and existing volume attached**: ### Step 3: Start Container with Updated Image
If you didn't remove the existing data, this will start the container with the updated image and the existing data. If you removed the existing data, this will start the container with the updated image and a new, empty volume. **For Nvidia GPU support, add `--gpus all` to the docker run command** Recreate the container using the new image while mounting your existing data volume.
```bash <Tabs groupId="gpu-support">
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main <TabItem value="cpu" label="CPU Only" default>
```bash title="Terminal - Standard Deployment"
docker run -d \
-p 3000:8080 \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:main
``` ```
## Keeps being logged out after every update? </TabItem>
If you find yourself getting logged out after every update, ensure that `WEBUI_SECRET_KEY` is set in your environment variables. Without this key being consistently defined, your authentication sessions may be invalidated after updates. <TabItem value="nvidia" label="NVIDIA GPU">
To set `WEBUI_SECRET_KEY` persistently, include it when running your Docker container: ```bash title="Terminal - With NVIDIA GPU Support"
docker run -d \
```bash -p 3000:8080 \
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui -e WEBUI_SECRET_KEY=your_secret_key ghcr.io/open-webui/open-webui:main --gpus all \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:main
``` ```
Or, if using **docker-compose**, add it under the `environment` section: </TabItem>
</Tabs>
```yml :::warning About WEBUI_SECRET_KEY
If you're not setting `WEBUI_SECRET_KEY`, it will be auto-generated each time you recreate the container, **causing you to be logged out after every update**.
See the [Persistent Login Sessions](#persistent-login-sessions) section below to fix this.
:::
### Verify Update Success
Check that Open WebUI started successfully:
```bash title="Terminal - Check Container Logs"
docker logs open-webui
# Watch logs in real-time
docker logs -f open-webui
```
**Successful startup indicators:**
```
INFO: [db] Database initialization complete
INFO: [main] Open WebUI starting on http://0.0.0.0:8080
```
Then verify in your browser:
1. Navigate to `http://localhost:3000` (or your configured port)
2. Clear browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete)
3. Hard refresh the page (Ctrl+F5 or Cmd+Shift+R)
4. Log in and verify your data is intact
## Persistent Login Sessions
To avoid being logged out after every update, you must set a persistent `WEBUI_SECRET_KEY`.
### Generate and Set Secret Key
<Tabs groupId="setup-method">
<TabItem value="docker-run" label="Docker Run" default>
```bash title="Terminal - Docker Run with Secret Key"
docker run -d \
-p 3000:8080 \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
-e WEBUI_SECRET_KEY="your-secret-key-here" \
ghcr.io/open-webui/open-webui:main
```
:::tip Generate a Secure Key
Generate a cryptographically secure key with:
```bash
openssl rand -hex 32
```
Or use Python:
```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```
:::
</TabItem>
<TabItem value="docker-compose" label="Docker Compose">
```yaml title="docker-compose.yml"
version: '3' version: '3'
services: services:
open-webui: open-webui:
@@ -68,40 +161,83 @@ services:
volumes: volumes:
- open-webui:/app/backend/data - open-webui:/app/backend/data
environment: environment:
- WEBUI_SECRET_KEY=your_secret_key - WEBUI_SECRET_KEY=your-secret-key-here
restart: unless-stopped
volumes:
open-webui:
``` ```
For more details on environment variable settings, check the [Open WebUI documentation on security variables](https://docs.openwebui.com/getting-started/env-configuration#security-variables). </TabItem>
</Tabs>
## Automatically Updating Open WebUI with Watchtower :::danger Store Secret Key Securely
- **Never commit** your secret key to version control
- Use environment files (`.env`) or secret management tools
- Keep the same key across updates to maintain sessions
:::
You can use [Watchtower](https://containrrr.dev/watchtower/) to automate the update process for Open WebUI. Here are three options: For complete environment variable documentation, see [Environment Configuration](https://docs.openwebui.com/getting-started/env-configuration#security-variables).
### Option 1: One-time Update ## Automated Update Tools
You can run Watchtower as a one-time update to stop the current container, pull the latest image, and start a new container with the updated image and existing volume attached (**For Nvidia GPU support, add `--gpus all` to the docker run command**): Automated updates can save time but require careful consideration of the trade-offs.
```bash :::warning Important Considerations
docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui **Automated updates can break your deployment if:**
``` - A new version has breaking changes you haven't reviewed
- Custom configurations become incompatible
- Database migrations fail during unattended updates
- You have plugins or customizations that aren't forward-compatible
### Option 2: Running Watchtower as a Separate Container **Best practices:**
- Always review release notes before auto-updating production systems
- Test updates in a staging environment first
- Consider notification-only tools rather than automatic updates
- Have a rollback plan and recent backups
:::
You can run Watchtower as a separate container that watches and updates your Open WebUI container: ### Option 1: Watchtower (Community Fork)
```bash :::info Watchtower Status
docker run -d --name watchtower \ The original `containrrr/watchtower` is **no longer maintained** and **does not work with Docker 29+**. The community has created maintained forks that resolve these issues.
:::
The original Watchtower project hasn't received updates in over two years and fails with Docker version 29.0.0 or newer due to API version incompatibility. Two maintained forks are now available: nickfedor/watchtower and Marrrrrrrrry/watchtower, both compatible with Docker 29+.
**Recommended: nickfedor/watchtower fork**
<Tabs>
<TabItem value="one-time" label="One-Time Update" default>
Run Watchtower once to update all containers, then exit:
```bash title="Terminal - One-Time Update"
docker run --rm \
--volume /var/run/docker.sock:/var/run/docker.sock \ --volume /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower -i 300 open-webui nickfedor/watchtower \
--run-once open-webui
``` ```
This will start Watchtower in detached mode, watching your Open WebUI container for updates every 5 minutes. </TabItem>
<TabItem value="continuous" label="Continuous Monitoring">
### Option 3: Integrating Watchtower with a `docker-compose.yml` File Run Watchtower as a persistent container that checks for updates every 6 hours:
You can also integrate Watchtower with your `docker-compose.yml` file to automate updates for Open WebUI (**For Nvidia GPU support, add `--gpus all` to the docker run command**): ```bash title="Terminal - Continuous Watchtower"
docker run -d \
--name watchtower \
--restart unless-stopped \
--volume /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--interval 21600 \
open-webui
```
```yml </TabItem>
<TabItem value="compose" label="Docker Compose">
```yaml title="docker-compose.yml"
version: '3' version: '3'
services: services:
open-webui: open-webui:
@@ -110,12 +246,20 @@ services:
- "3000:8080" - "3000:8080"
volumes: volumes:
- open-webui:/app/backend/data - open-webui:/app/backend/data
environment:
- WEBUI_SECRET_KEY=your-secret-key-here
restart: unless-stopped
watchtower: watchtower:
image: containrrr/watchtower image: nickfedor/watchtower:latest
volumes: volumes:
- /var/run/docker.sock:/var/run/docker.sock - /var/run/docker.sock:/var/run/docker.sock
command: --interval 300 open-webui environment:
- WATCHTOWER_CLEANUP=true
- WATCHTOWER_INCLUDE_STOPPED=false
- WATCHTOWER_SCHEDULE=0 0 2 * * * # 2 AM daily
command: open-webui
restart: unless-stopped
depends_on: depends_on:
- open-webui - open-webui
@@ -123,29 +267,311 @@ volumes:
open-webui: open-webui:
``` ```
In this example, Watchtower is integrated with the `docker-compose.yml` file and watches the Open WebUI container for updates every 5 minutes. </TabItem>
</Tabs>
:::info **Watchtower configuration options:**
After updating, it's a good practice to clear your browser cache to ensure you are running the latest version of the web interface. | Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `WATCHTOWER_CLEANUP` | Remove old images after update | `false` |
| `WATCHTOWER_INCLUDE_STOPPED` | Update stopped containers too | `false` |
| `WATCHTOWER_SCHEDULE` | Cron expression for update schedule | `0 0 0 * * *` (midnight) |
| `WATCHTOWER_MONITOR_ONLY` | Only notify, don't update | `false` |
:::tip Monitor-Only Mode
To receive notifications without automatic updates:
```bash
docker run -d \
--name watchtower \
--volume /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_MONITOR_ONLY=true \
-e WATCHTOWER_NOTIFICATIONS=email \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=you@example.com \
nickfedor/watchtower
```
::: :::
## Persistent Data in Docker Volumes **Alternative fork:** Marrrrrrrrry/watchtower is another actively maintained fork with updated dependencies and simplified functions.
The data is stored in a Docker volume named `open-webui`. The path to the volume is not directly accessible, but you can inspect the volume with the following command: For complete Watchtower documentation, visit https://watchtower.nickfedor.com/
### Option 2: What's Up Docker (WUD)
What's Up Docker (WUD) is a notification-focused alternative that doesn't automatically update containers but instead provides a web UI to monitor updates and trigger them manually.
**Why choose WUD:**
- ✅ Web UI for visual monitoring
- ✅ Click-button manual updates
- ✅ Shows descriptive names and changelogs
- ✅ Auto-prunes old images
- ✅ Supports multiple Docker hosts
- ✅ Extensive notification options
- ❌ Requires manual intervention (not fully automated)
**Quick start with WUD:**
```yaml title="docker-compose.yml"
version: '3'
services:
wud:
image: fmartinou/whats-up-docker:latest
container_name: wud
ports:
- "3001:3000"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
# Authentication (optional but recommended)
- WUD_AUTH_BASIC_USER=admin
- WUD_AUTH_BASIC_HASH=$$apr1$$... # Generate with htpasswd
# Enable triggers for updates
- WUD_TRIGGER_DOCKERCOMPOSE_WUD_FILE=/docker-compose.yml
# Notification examples
- WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
restart: unless-stopped
```
After starting WUD, access the web interface at `http://localhost:3001`. You'll see all containers and available updates with click-to-update buttons.
:::tip Generate Password Hash
```bash ```bash
htpasswd -nbB admin yourpassword
```
Copy the part after the colon, and replace each `$` with `$$` in docker-compose.
:::
For complete WUD documentation, visit https://getwud.github.io/wud/
### Option 3: Diun (Docker Image Update Notifier)
Diun is a lightweight CLI tool that only sends notifications about available updates without performing any updates. It's ideal if you want complete control and just need alerts.
**Why choose Diun:**
- ✅ Notification-only (safest approach)
- ✅ No web UI overhead (lightweight)
- ✅ Multiple notification providers (email, Slack, Discord, Telegram, etc.)
- ✅ Fine-grained control over what to monitor
- ❌ No built-in update mechanism (purely informational)
```yaml title="docker-compose.yml"
version: '3'
services:
diun:
image: crazymax/diun:latest
container_name: diun
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./data:/data
environment:
- TZ=America/New_York
- LOG_LEVEL=info
- DIUN_WATCH_WORKERS=10
- DIUN_WATCH_SCHEDULE=0 */6 * * * # Every 6 hours
- DIUN_PROVIDERS_DOCKER=true
- DIUN_NOTIF_MAIL_HOST=smtp.gmail.com
- DIUN_NOTIF_MAIL_PORT=587
- DIUN_NOTIF_MAIL_USERNAME=your-email@gmail.com
- DIUN_NOTIF_MAIL_PASSWORD=your-app-password
- DIUN_NOTIF_MAIL_FROM=your-email@gmail.com
- DIUN_NOTIF_MAIL_TO=your-email@gmail.com
restart: unless-stopped
```
For complete Diun documentation, visit https://crazymax.dev/diun/
### Comparison: Which Tool Should You Use?
| Feature | Watchtower (Fork) | WUD | Diun |
|---------|------------------|-----|------|
| **Automatic Updates** | ✅ Yes | ⚠️ Manual via UI | ❌ No |
| **Web Interface** | ❌ No | ✅ Yes | ❌ No |
| **Notifications** | ✅ Yes | ✅ Yes | ✅ Yes |
| **Manual Control** | ⚠️ Limited | ✅ Full control | ✅ Full control |
| **Resource Usage** | Low | Medium | Very Low |
| **Docker 29+ Support** | ✅ Yes (forks) | ✅ Yes | ✅ Yes |
| **Best For** | Set-and-forget homelabs | Visual monitoring + control | Notification-only workflows |
:::tip Recommendation
- **For homelabs/personal use:** nickfedor/watchtower (automated)
- **For managed environments:** WUD (visual + manual control)
- **For production/critical systems:** Diun (notifications only) + manual updates
:::
## Troubleshooting Updates
### Container Won't Start After Update
**Check logs for errors:**
```bash title="Terminal"
docker logs open-webui
# Look for migration errors or startup failures
```
**Common causes:**
- Database migration failed
- Incompatible environment variables
- Port already in use
**Solution:** Restore previous version and investigate:
```bash title="Terminal - Rollback to Previous Version"
# Stop current container
docker stop open-webui
docker rm open-webui
# Pull specific older version (check GitHub releases for version tags)
docker pull ghcr.io/open-webui/open-webui:v0.4.0
# Start with old image
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
--name open-webui ghcr.io/open-webui/open-webui:v0.4.0
```
### Data Loss or Corruption
**If you suspect data issues:**
```bash title="Terminal - Inspect Volume"
# Find volume location
docker volume inspect open-webui
# Check database file exists
docker run --rm -v open-webui:/data alpine ls -lah /data
```
**Recovery steps:**
1. Stop Open WebUI: `docker stop open-webui`
2. Backup volume: `docker run --rm -v open-webui:/data -v $(pwd):/backup alpine tar czf /backup/openwebui-backup.tar.gz /data`
3. Restore from backup if needed
4. Check [Manual Migration Guide](./manual-database-migration) for database issues
### Watchtower Updates Too Frequently
Configure update schedule with cron expressions:
```bash title="Terminal - Custom Schedule"
# Daily at 3 AM
-e WATCHTOWER_SCHEDULE="0 0 3 * * *"
# Weekly on Sundays at 2 AM
-e WATCHTOWER_SCHEDULE="0 0 2 * * 0"
# Every 12 hours
-e WATCHTOWER_SCHEDULE="0 0 */12 * * *"
```
### "Logged Out After Update" Despite Setting Secret Key
**Diagnosis:**
```bash title="Terminal - Check Environment Variables"
docker inspect open-webui | grep WEBUI_SECRET_KEY
```
If the key isn't showing, you didn't pass it correctly when recreating the container.
**Fix:**
```bash title="Terminal - Recreate with Correct Key"
docker stop open-webui
docker rm open-webui
# Make sure to include -e WEBUI_SECRET_KEY
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
-e WEBUI_SECRET_KEY="your-persistent-key" \
--name open-webui ghcr.io/open-webui/open-webui:main
```
## Docker Volume Management
### Locate Your Data
The `open-webui` Docker volume contains all your data (chats, users, uploads, etc.).
```bash title="Terminal - Inspect Volume"
docker volume inspect open-webui docker volume inspect open-webui
``` ```
This will show you the details of the volume, including the mountpoint, which is usually located in `/var/lib/docker/volumes/open-webui/_data`. **Common volume locations:**
- Linux: `/var/lib/docker/volumes/open-webui/_data`
- Windows (WSL2): `\\wsl$\docker-desktop\mnt\docker-desktop-disk\data\docker\volumes\open-webui\_data`
- macOS: `~/Library/Containers/com.docker.docker/Data/vms/0/data/docker/volumes/open-webui/_data`
On Windows 10 + WSL 2, Docker volumes are located here (type in the Windows file explorer): :::warning Direct Access Risk
- \\\wsl$\docker-desktop\mnt\docker-desktop-disk\data\docker\volumes Avoid directly modifying files in the volume location. Always interact through the container or Docker commands to prevent corruption.
:::
For older versions of Docker (pre-Docker v26.1.4): ### Backup Volume
- \\\wsl$\docker-desktop-data\data\docker\volumes
- \\\wsl$\docker-desktop-data\version-pack-data\community\docker\volumes
*(Windows answer credit to StackOverflow user sarye-haddadi; [link to original SO post](https://stackoverflow.com/questions/43181654/locating-data-volumes-in-docker-desktop-windows))* ```bash title="Terminal - Backup Docker Volume"
# Create timestamped backup
docker run --rm \
-v open-webui:/data \
-v $(pwd):/backup \
alpine tar czf /backup/openwebui-$(date +%Y%m%d_%H%M%S).tar.gz /data
```
### Restore Volume
```bash title="Terminal - Restore from Backup"
# Stop container
docker stop open-webui
# Restore backup
docker run --rm \
-v open-webui:/data \
-v $(pwd):/backup \
alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-20241201_120000.tar.gz -C /"
# Start container
docker start open-webui
```
### Clean Up Old Images
After updating, old images remain on disk. Remove them to free space:
```bash title="Terminal - Remove Unused Images"
# Remove dangling images (not tagged or used)
docker image prune
# Remove all unused images (careful!)
docker image prune -a
# List all open-webui images
docker images | grep open-webui
```
Watchtower can do this automatically with:
```bash
-e WATCHTOWER_CLEANUP=true
```
## Post-Update Checklist
After updating, verify everything works:
- [ ] Open WebUI starts without errors (`docker logs open-webui`)
- [ ] Can access web interface at `http://localhost:3000`
- [ ] Can log in with existing credentials
- [ ] Chat history is intact
- [ ] Models are still configured correctly
- [ ] Custom settings are preserved
- [ ] No JavaScript console errors (F12 in browser)
- [ ] Clear browser cache if interface looks broken
:::tip Browser Cache Issues
If the interface looks broken or old after updating:
1. Hard refresh: Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac)
2. Clear site data: Browser Settings > Privacy > Clear browsing data
3. Try incognito/private window to verify it's a cache issue
:::
## Additional Resources
- [Open WebUI GitHub Releases](https://github.com/open-webui/open-webui/releases) - Version history and changelogs
- [Environment Configuration Guide](https://docs.openwebui.com/getting-started/env-configuration) - All environment variables
- [Manual Database Migration](troubleshooting/manual-database-migration.md) - Fix database issues after updates
- [Watchtower Documentation](https://watchtower.nickfedor.com/) - Advanced Watchtower configuration
- [WUD Documentation](https://getwud.github.io/wud/) - What's Up Docker setup guide

8
docs/license.mdx
View File

@@ -13,7 +13,7 @@ import { TopBanners } from "@site/src/components/TopBanners";
:::tip :::tip
**Here's the TL;DR:** **Here's the TL;DR:**
To keep Open WebUI thriving for the long term, we’ve introduced a **lightweight branding protection clause** with Open WebUI v0.6.6+ that helps us sustain the project while ensuring **every user** continues to benefit from rapid innovation **without resorting to gated features or paywalled functionality**. Branding requirements **only apply to larger deployments (50+ users)**. Deployments with 50 or fewer users may fully rebrand if they choose. To keep Open WebUI thriving for the long term, we’ve introduced a **lightweight branding protection clause** with Open WebUI v0.6.6+ that helps us sustain the project while ensuring **every user** continues to benefit from rapid innovation **without resorting to gated features or paywalled functionality**. Branding requirements **only apply to larger deployments (50+ users, aggregate)**. Self-hosted internal deployments with 50 or fewer users may fully rebrand if they choose.
As a small, independent team building mission-critical AI tooling, we rely on fair attribution to **support ongoing development, security, and quality**, all without restricting real users, contributors, or businesses who use Open WebUI responsibly. As a small, independent team building mission-critical AI tooling, we rely on fair attribution to **support ongoing development, security, and quality**, all without restricting real users, contributors, or businesses who use Open WebUI responsibly.
@@ -31,7 +31,7 @@ In plain terms:
- **You can still use, modify, and redistribute it for any purpose, just don’t remove or alter our branding unless you meet one of three clear criteria (see below).** - **You can still use, modify, and redistribute it for any purpose, just don’t remove or alter our branding unless you meet one of three clear criteria (see below).**
- **The original BSD-3 license continues to apply for all contributions made to the codebase up to and including release v0.6.5.** - **The original BSD-3 license continues to apply for all contributions made to the codebase up to and including release v0.6.5.**
We remain committed to transparency, openness, and supporting everyone, from hobbyists to enterprise. This is a “semi-copyleft” measure: we protect just the branding, to keep the project honest and sustainable; everything else is as free as you expect from open-source BSD. We remain committed to transparency, openness, and supporting everyone, from hobbyists to enterprise. This is a “semi-copyleft” measure: we protect just the branding, to keep the project honest and sustainable; everything else is as free as you expect from open-source.
We take your trust seriously. We want Open WebUI to stay **empowering and accessible**, **driven by real community spirit**, not gated, not locked-in, not co-opted by bad actors. We’re a small, lean team, but we care deeply about giving all our users the best experience and keeping our ecosystem clean and fair. **Thank you for supporting us, and for caring about the future of open AI.** We take your trust seriously. We want Open WebUI to stay **empowering and accessible**, **driven by real community spirit**, not gated, not locked-in, not co-opted by bad actors. We’re a small, lean team, but we care deeply about giving all our users the best experience and keeping our ecosystem clean and fair. **Thank you for supporting us, and for caring about the future of open AI.**
@@ -157,9 +157,9 @@ BSD-3 output/forks have **maximum flexibility**: as long as you keep the origina
### 6. Does this mean Open WebUI is “no longer open source”? ### 6. Does this mean Open WebUI is “no longer open source”?
It's a great, and complicated, question, because **"open source" can mean many different things to many people**. It's a great, and complicated, question, because "open source" can mean many different things to many people.
- **In the narrowest, most “by-the-book” sense, our new branding clause means Open WebUI v0.6.6+ isn’t OSI-certified "open source.”** - In the narrowest, most “by-the-book” sense, our new branding clause means: **No, Open WebUI v0.6.6+ isn’t OSI-certified "open source.”**
- Example: The OSI would not certify licenses that require you to keep original branding. - Example: The OSI would not certify licenses that require you to keep original branding.
- However, compared to what most people mean in practice , **“is the code available, can I use it, fork it, change it, build things with it, and not pay you or get a special key?”** , the answer is still a resounding **yes**. - However, compared to what most people mean in practice , **“is the code available, can I use it, fork it, change it, build things with it, and not pay you or get a special key?”** , the answer is still a resounding **yes**.

202
docs/troubleshooting/manual-database-migration.md
View File

@@ -161,12 +161,15 @@ export DATABASE_URL="sqlite:////app/backend/data/webui.db"
export DATABASE_URL="postgresql://user:password@localhost:5432/open_webui_db" export DATABASE_URL="postgresql://user:password@localhost:5432/open_webui_db"
# Required: WEBUI_SECRET_KEY # Required: WEBUI_SECRET_KEY
# Get from existing file # Get from existing file in backend directory (NOT data directory)
export WEBUI_SECRET_KEY=$(cat /app/backend/data/.webui_secret_key) export WEBUI_SECRET_KEY=$(cat /app/backend/.webui_secret_key)
# If .webui_secret_key doesn't exist, generate one # If that fails, try the data directory location
# export WEBUI_SECRET_KEY=$(cat /app/backend/data/.webui_secret_key)
# If neither file exists, generate one
# export WEBUI_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))") # export WEBUI_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
# echo $WEBUI_SECRET_KEY > /app/backend/data/.webui_secret_key # echo $WEBUI_SECRET_KEY > /app/backend/.webui_secret_key
# Verify both are set # Verify both are set
echo "DATABASE_URL: $DATABASE_URL" echo "DATABASE_URL: $DATABASE_URL"
@@ -304,7 +307,6 @@ INFO [alembic.runtime.migration] Running upgrade abc123 -> def456, add_new_colu
This is a **normal informational message** for SQLite, not an error. SQLite doesn't support rollback of schema changes, so migrations run without transaction protection. This is a **normal informational message** for SQLite, not an error. SQLite doesn't support rollback of schema changes, so migrations run without transaction protection.
If the process appears to hang after this message, wait 2-3 minutes - some migrations take time, especially: If the process appears to hang after this message, wait 2-3 minutes - some migrations take time, especially:
- Migrations that add indexes to large tables (1M+ rows: 1-5 minutes) - Migrations that add indexes to large tables (1M+ rows: 1-5 minutes)
- Migrations with data transformations (100K+ rows: 30 seconds to several minutes) - Migrations with data transformations (100K+ rows: 30 seconds to several minutes)
- Migrations that rebuild tables (SQLite doesn't support all ALTER operations) - Migrations that rebuild tables (SQLite doesn't support all ALTER operations)
@@ -401,7 +403,6 @@ INFO: [main] Open WebUI starting on http://0.0.0.0:8080
``` ```
**Smoke test after startup:** **Smoke test after startup:**
- Can access login page - Can access login page
- Can log in with existing credentials - Can log in with existing credentials
- Can view chat history - Can view chat history
@@ -419,12 +420,15 @@ INFO: [main] Open WebUI starting on http://0.0.0.0:8080
<TabItem value="docker" label="Docker" default> <TabItem value="docker" label="Docker" default>
```bash title="Terminal - Fix Missing Secret Key (Docker)" ```bash title="Terminal - Fix Missing Secret Key (Docker)"
# Method 1: Use existing key from file # Method 1: Check backend directory first (most common location)
export WEBUI_SECRET_KEY=$(cat /app/backend/data/.webui_secret_key) export WEBUI_SECRET_KEY=$(cat /app/backend/.webui_secret_key)
# Method 2: If file doesn't exist, generate new key # Method 2: If that fails, try data directory
export WEBUI_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))") # export WEBUI_SECRET_KEY=$(cat /app/backend/data/.webui_secret_key)
echo $WEBUI_SECRET_KEY > /app/backend/data/.webui_secret_key
# Method 3: If neither file exists, generate new key
# export WEBUI_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
# echo $WEBUI_SECRET_KEY > /app/backend/.webui_secret_key
# Verify it's set # Verify it's set
echo "WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY:0:10}..." echo "WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY:0:10}..."
@@ -616,6 +620,157 @@ git checkout /app/backend/open_webui/migrations/ # If using git
**Technical context:** The "autogenerate detects removed tables" issue occurs because Open WebUI's Alembic metadata configuration doesn't import all model definitions. This causes autogenerate to compare against incomplete metadata, thinking tables should be removed. This is a developer-level issue that doesn't affect users running `alembic upgrade`. **Technical context:** The "autogenerate detects removed tables" issue occurs because Open WebUI's Alembic metadata configuration doesn't import all model definitions. This causes autogenerate to compare against incomplete metadata, thinking tables should be removed. This is a developer-level issue that doesn't affect users running `alembic upgrade`.
### PostgreSQL Foreign Key Errors
:::info PostgreSQL Only
This troubleshooting applies only to PostgreSQL databases. SQLite handles foreign keys differently.
:::
**Symptom:** Errors like `psycopg2.errors.InvalidForeignKey: there is no unique constraint matching given keys for referenced table "user"`
**Cause:** PostgreSQL requires explicit primary key constraints that were missing in older schema versions.
**Solution for PostgreSQL:**
```sql title="PostgreSQL Fix"
-- Connect to your PostgreSQL database
psql -h localhost -U your_user -d open_webui_db
-- Add missing primary key constraint (PostgreSQL syntax)
ALTER TABLE public."user" ADD CONSTRAINT user_pk PRIMARY KEY (id);
-- Verify constraint was added
\d+ public."user"
```
**Note:** The `public.` schema prefix and quoted `"user"` identifier are PostgreSQL-specific. This SQL will not work on SQLite or MySQL.
### Duplicate Column Errors
:::danger Critical Issue
Duplicate column errors indicate schema corruption, usually from failed migrations or manual database modifications. This requires careful manual intervention.
:::
**Symptom:** Migration fails with error like:
```
sqlite3.OperationalError: duplicate column name: message.reply_to_id
```
Or when starting Open WebUI:
```
UNIQUE constraint failed: alembic_version.version_num
```
**Cause:**
<ul>
<li>A previous migration partially completed, leaving duplicate columns</li>
<li>Database was manually modified</li>
<li>Migration was interrupted mid-execution</li>
<li>Upgrading directly across many versions (skipping intermediate migrations)</li>
</ul>
**Diagnosis:**
```bash title="Terminal - Check for Duplicate Columns"
# List all columns in the message table
sqlite3 /app/backend/data/webui.db "PRAGMA table_info(message);"
# Look for duplicate column names in the output
# Example problematic output:
# 10|reply_to_id|TEXT|0||0
# 15|reply_to_id|TEXT|0||0 <- Duplicate!
```
**Solution - Manual Column Removal:**
:::warning Data Loss Risk
Removing columns can cause data loss. **Backup your database first** before proceeding.
:::
```bash title="Terminal - Remove Duplicate Column (SQLite)"
# 1. Backup database first!
cp /app/backend/data/webui.db /app/backend/data/webui.db.pre-fix
# 2. Enter SQLite
sqlite3 /app/backend/data/webui.db
# 3. Check current table structure
PRAGMA table_info(message);
# 4. SQLite doesn't support DROP COLUMN directly - must recreate table
# First, get the CREATE TABLE statement
.schema message
# 5. Create new table without duplicate column
-- Copy the CREATE TABLE statement but remove duplicate column definition
-- Example (adjust to your actual schema):
CREATE TABLE message_new (
id TEXT PRIMARY KEY,
content TEXT,
role TEXT,
-- ... other columns ...
reply_to_id TEXT, -- Only one instance
-- ... remaining columns ...
FOREIGN KEY (reply_to_id) REFERENCES message(id)
);
# 6. Copy data from old table to new table
INSERT INTO message_new SELECT * FROM message;
# 7. Drop old table
DROP TABLE message;
# 8. Rename new table
ALTER TABLE message_new RENAME TO message;
# 9. Exit SQLite
.quit
# 10. Verify fix worked
sqlite3 /app/backend/data/webui.db "PRAGMA table_info(message);"
# 11. Try migration again
cd /app/backend/open_webui
alembic upgrade head
```
**Alternative - Simpler approach if you know the duplicate column:**
```bash title="Terminal - Quick Fix for Known Duplicate"
# This only works if the column truly is completely duplicate
# and SQLite's table rebuilding handles it correctly
sqlite3 /app/backend/data/webui.db <<EOF
-- Create temporary table with correct schema
CREATE TABLE message_temp AS SELECT DISTINCT * FROM message;
-- Drop original table
DROP TABLE message;
-- Recreate with proper schema (get from .schema message originally)
-- Then copy data back
EOF
```
:::danger When to Seek Help
If you're not comfortable with SQL or aren't sure which column is the duplicate, **stop here and seek help** on the Open WebUI GitHub issues or Discord. Provide:
- Output of `PRAGMA table_info(message);`
- The full migration error message
- Your Open WebUI version history (what version you upgraded from/to)
:::
**Prevention:**
<ul>
<li>Never skip major versions when upgrading (don't jump from v0.1.x to v0.4.x)</li>
<li>Always backup before upgrading</li>
<li>Test upgrades on a copy of your database first</li>
<li>Review migration scripts for your version upgrade path</li>
</ul>
### Peewee to Alembic Transition Issues ### Peewee to Alembic Transition Issues
**Background:** Older Open WebUI versions (pre-0.4.x) used Peewee migrations. Current versions use Alembic. **Background:** Older Open WebUI versions (pre-0.4.x) used Peewee migrations. Current versions use Alembic.
@@ -647,31 +802,6 @@ alembic upgrade head
If upgrading from very old Open WebUI versions (< 0.3.x), consider a fresh install with data export/import rather than attempting to migrate the database schema across multiple major version changes. If upgrading from very old Open WebUI versions (< 0.3.x), consider a fresh install with data export/import rather than attempting to migrate the database schema across multiple major version changes.
::: :::
### PostgreSQL Foreign Key Errors
:::info PostgreSQL Only
This troubleshooting applies only to PostgreSQL databases. SQLite handles foreign keys differently.
:::
**Symptom:** Errors like `psycopg2.errors.InvalidForeignKey: there is no unique constraint matching given keys for referenced table "user"`
**Cause:** PostgreSQL requires explicit primary key constraints that were missing in older schema versions.
**Solution for PostgreSQL:**
```sql title="PostgreSQL Fix"
-- Connect to your PostgreSQL database
psql -h localhost -U your_user -d open_webui_db
-- Add missing primary key constraint (PostgreSQL syntax)
ALTER TABLE public."user" ADD CONSTRAINT user_pk PRIMARY KEY (id);
-- Verify constraint was added
\d+ public."user"
```
**Note:** The `public.` schema prefix and quoted `"user"` identifier are PostgreSQL-specific. This SQL will not work on SQLite or MySQL.
## Advanced Operations ## Advanced Operations
### Production and Multi-Server Deployments ### Production and Multi-Server Deployments