mirror of
https://github.com/open-webui/docs.git
synced 2026-07-21 10:05:26 -04:00
refac
This commit is contained in:
Tim Baek
@@ -0,0 +1,164 @@
|
||||
---
|
||||
sidebar_position: 0
|
||||
title: "API Keys"
|
||||
---
|
||||
|
||||
# 🔑 API Keys
|
||||
|
||||
**Programmatic access to Open WebUI, for scripts, bots, and integrations.**
|
||||
|
||||
API keys are personal access tokens that let external code call the same endpoints the web UI uses. Anything you can do in a browser - chat completions, model listing, file uploads, RAG queries - your scripts can do with a single `Authorization: Bearer` header. Each key inherits the permissions of the user who created it, so there's no separate permission model to learn.
|
||||
|
||||
---
|
||||
|
||||
## Why API Keys?
|
||||
|
||||
### Automation without a browser
|
||||
|
||||
Scripts, CI/CD pipelines, monitoring bots, and third-party tools all need programmatic access. API keys give them a stable credential that doesn't expire with a browser session.
|
||||
|
||||
### Same permissions, different interface
|
||||
|
||||
An API key acts as you. It inherits your role and group permissions - the same access controls that govern the web UI apply to every API request.
|
||||
|
||||
### Revocable and auditable
|
||||
|
||||
Name each key descriptively (e.g., "CI Pipeline", "Monitoring Bot") to track usage. Delete a key instantly if it's compromised - no password reset, no session invalidation, just a single click.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🔐 **Bearer token auth** | Standard `Authorization: Bearer` header, works with any HTTP client or SDK |
|
||||
| 🛡️ **Scoped to user** | Key inherits the creating user's role and group permissions |
|
||||
| 🚫 **Endpoint restrictions** | Optionally limit which API routes a key can access |
|
||||
| 👥 **Permission-gated** | Requires a global admin toggle plus per-group feature permission for non-admins |
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Step 1: Enable API Keys Globally (Admin)
|
||||
|
||||
1. Log in as an **administrator**
|
||||
2. Open **Admin Panel > Settings > General**
|
||||
3. Scroll to the **Authentication** section
|
||||
4. Toggle **Enable API Keys** on
|
||||
5. Click **Save**
|
||||
|
||||
:::info
|
||||
This is the global master switch. When it's off, no one - not even admins - can generate keys. When it's on:
|
||||
- **Admin** users can generate keys immediately
|
||||
- **Non-admin** users still need the API Keys feature permission (Step 2)
|
||||
:::
|
||||
|
||||
*(Optional)* Enable **API Key Endpoint Restrictions** to limit which routes API keys can call. Specify allowed endpoints as a comma-separated list (e.g., `/api/v1/models,/api/v1/chat/completions`).
|
||||
|
||||
### Step 2: Grant Permission to Non-admin Users (Admin)
|
||||
|
||||
Non-admin users need the **API Keys** feature permission. Grant it using either method:
|
||||
|
||||
#### Option A: Default Permissions (all users)
|
||||
|
||||
1. **Admin Panel > Users > Groups > Default Permissions**
|
||||
2. Under **Features Permissions**, toggle **API Keys** on
|
||||
3. Click **Save**
|
||||
|
||||
:::warning
|
||||
This grants every user with the "user" role the ability to generate API keys. For tighter control, use Option B.
|
||||
:::
|
||||
|
||||
#### Option B: User Groups (specific users)
|
||||
|
||||
1. **Admin Panel > Users > Groups**
|
||||
2. Select or create a group (e.g., "API Users")
|
||||
3. Under **Permissions > Features Permissions**, toggle **API Keys** on
|
||||
4. Click **Save**
|
||||
|
||||
:::tip
|
||||
Create a dedicated "API Users" or "Monitoring" group and add only the accounts that need programmatic access. This follows the principle of least privilege.
|
||||
:::
|
||||
|
||||
### Step 3: Generate a Key
|
||||
|
||||
1. Click your **profile icon** (bottom-left sidebar)
|
||||
2. Select **Settings > Account**
|
||||
3. In the **API Keys** section, click **Generate New API Key**
|
||||
4. Give it a descriptive name (e.g., "Monitoring Bot")
|
||||
5. **Copy the key immediately** - you won't be able to view it again
|
||||
|
||||
:::warning
|
||||
Treat API keys like passwords. Store them in a secrets manager, never commit them to version control, and never share them in public channels. If a key is compromised, delete it immediately and generate a new one.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Using Your API Key
|
||||
|
||||
Pass the key as a Bearer token in the `Authorization` header:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
http://localhost:8080/api/models
|
||||
```
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.get(
|
||||
"http://localhost:8080/api/models",
|
||||
headers={"Authorization": "Bearer YOUR_API_KEY"}
|
||||
)
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
For the full endpoint reference - chat completions, Ollama proxy, RAG, file management, and more - see [API Endpoints](/reference/api-endpoints).
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Dedicated service accounts
|
||||
|
||||
Create a **non-admin user** specifically for automation (e.g., `monitoring-bot`, `ci-pipeline`). Generate keys from that account. If a key leaks, the attacker only gets that user's permissions - not admin access.
|
||||
|
||||
### Endpoint restrictions
|
||||
|
||||
Enable **API Key Endpoint Restrictions** and whitelist only the routes your integration actually needs. A monitoring bot only needs `/api/models` and `/api/chat/completions` - don't give it access to `/api/v1/files/` or admin endpoints.
|
||||
|
||||
### Key rotation
|
||||
|
||||
Periodically delete old keys and generate new ones, especially for long-lived integrations. Name keys with a date or version to track rotation (`"Monitoring Bot - 2025-Q1"`).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Can't see the API Keys section in Settings > Account?**
|
||||
|
||||
- **Check the global toggle:** Verify that an admin has enabled API keys in **Admin Panel > Settings > General > Enable API Keys**. See [`ENABLE_API_KEYS`](/reference/env-configuration#enable_api_keys).
|
||||
- **Check your permissions (non-admin users):** Verify that your account or group has the **API Keys** feature permission under **Features Permissions**. See [`USER_PERMISSIONS_FEATURES_API_KEYS`](/reference/env-configuration#user_permissions_features_api_keys).
|
||||
|
||||
**Getting `401 Unauthorized` responses?**
|
||||
|
||||
- Verify the key is formatted correctly: `Authorization: Bearer sk-...`
|
||||
- Check that the key hasn't been deleted
|
||||
- If endpoint restrictions are enabled, confirm the route you're calling is in the allowlist
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### No post-creation viewing
|
||||
|
||||
API keys cannot be viewed after creation. If you lose a key, delete it and generate a new one.
|
||||
|
||||
### No per-key permissions
|
||||
|
||||
Keys inherit the full permissions of the user who created them. You cannot restrict a key to a subset of its owner's permissions (beyond endpoint restrictions).
|
||||
|
||||
### No automatic expiration
|
||||
|
||||
API keys do not expire automatically. You must manually delete and rotate them.
|
||||
@@ -2,20 +2,7 @@
|
||||
|
||||
To update your local Docker installation to the latest version, you can either use **Watchtower** or manually update the container.
|
||||
|
||||
### Option 1: Using Watchtower (Recommended Fork)
|
||||
|
||||
:::info Deprecation Notice
|
||||
The original `containrrr/watchtower` is **no longer maintained** and may fail with newer Docker versions. We recommend using the `nicholas-fedor/watchtower` fork.
|
||||
:::
|
||||
|
||||
:::warning Multi-Worker Environments
|
||||
If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environment), you **MUST** ensure the update migration runs on a single worker first to prevent database schema corruption.
|
||||
|
||||
**Steps for proper update:**
|
||||
1. Update and start your container with `UVICORN_WORKERS=1`.
|
||||
2. Wait for the application to fully start and complete migrations.
|
||||
3. Stop and restart the container with your desired number of workers.
|
||||
:::
|
||||
### Option 1: Using Watchtower
|
||||
|
||||
With [Watchtower](https://github.com/nicholas-fedor/watchtower), you can automate the update process:
|
||||
|
||||
@@ -42,7 +29,14 @@ docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/wat
|
||||
3. Start the container again:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
|
||||
-e WEBUI_SECRET_KEY="your-secret-key" \
|
||||
--name open-webui --restart always \
|
||||
ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
Both methods will get your Docker instance updated and running with the latest build.
|
||||
:::warning Set WEBUI_SECRET_KEY
|
||||
Without a persistent `WEBUI_SECRET_KEY`, you'll be logged out every time the container is recreated. Generate one with `openssl rand -hex 32`.
|
||||
:::
|
||||
|
||||
For version pinning, rollback, automated update tools, and backup procedures, see the [full update guide](/getting-started/updating).
|
||||
|
||||
@@ -8,7 +8,11 @@ pip install -U open-webui
|
||||
|
||||
The `-U` (or `--upgrade`) flag ensures that `pip` upgrades the package to the latest available version.
|
||||
|
||||
That's it! Your **Open-WebUI** package is now updated and ready to use.
|
||||
After upgrading, restart the server and verify it starts correctly:
|
||||
|
||||
```bash
|
||||
open-webui serve
|
||||
```
|
||||
|
||||
:::warning Multi-Worker Environments
|
||||
If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environment), you **MUST** ensure the update migration runs on a single worker first to prevent database schema corruption.
|
||||
@@ -19,3 +23,5 @@ If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environm
|
||||
3. Wait for the application to fully start and complete migrations.
|
||||
4. Stop and restart the application with your desired number of workers.
|
||||
:::
|
||||
|
||||
For version pinning, rollback, and backup procedures, see the [full update guide](/getting-started/updating).
|
||||
|
||||
@@ -6,16 +6,52 @@ title: "Updating Open WebUI"
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Overview
|
||||
# Updating Open WebUI
|
||||
|
||||
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.
|
||||
**Stay current without losing your data.**
|
||||
|
||||
:::info Before Updating
|
||||
- **Backup your data** — especially before releases that include database migrations, since they can be hard to undo. Check [release notes](https://github.com/open-webui/open-webui/releases) for breaking changes
|
||||
- **Clear browser cache** after updating (Ctrl+F5 / Cmd+Shift+R)
|
||||
- **Multiple workers/replicas?** Run migrations with `UVICORN_WORKERS=1` first, or set `ENABLE_DB_MIGRATIONS=False` on all but one instance
|
||||
Your data (chats, users, settings, uploads) lives in a Docker volume or local database, not inside the container. Updating Open WebUI means swapping the container image for a newer one. Your data stays exactly where it is.
|
||||
|
||||
---
|
||||
|
||||
## Choose Your Update Strategy
|
||||
|
||||
Before running any commands, decide how you want to track releases. The right choice depends on how you use Open WebUI.
|
||||
|
||||
| Scenario | Recommended approach |
|
||||
|---|---|
|
||||
| **Personal / homelab** | Use the `:main` tag and pull manually when you want the latest |
|
||||
| **Shared / team instance** | Pin a specific version (e.g. `:v0.8.6`) and use [Diun](#diun) for update notifications |
|
||||
| **Production / critical** | Pin a version, review [release notes](https://github.com/open-webui/open-webui/releases) before upgrading, test in staging first |
|
||||
|
||||
### `:main` vs. Pinned Versions
|
||||
|
||||
The `:main` tag always points to the **latest build**. It's convenient but can include breaking changes without warning.
|
||||
|
||||
For stability, pin a specific release tag:
|
||||
|
||||
```
|
||||
ghcr.io/open-webui/open-webui:v0.8.6
|
||||
ghcr.io/open-webui/open-webui:v0.8.6-cuda
|
||||
ghcr.io/open-webui/open-webui:v0.8.6-ollama
|
||||
```
|
||||
|
||||
Browse all available tags on the [GitHub releases page](https://github.com/open-webui/open-webui/releases).
|
||||
|
||||
---
|
||||
|
||||
## Before You Update
|
||||
|
||||
1. **Back up your data** (see [Backup & Restore](#backup--restore) below). Especially important before releases with database migrations, which can be hard to undo.
|
||||
2. **Check the [release notes](https://github.com/open-webui/open-webui/releases)** for breaking changes.
|
||||
3. **Clear your browser cache** after updating (`Ctrl+F5` / `Cmd+Shift+R`) to avoid stale frontend assets.
|
||||
|
||||
:::warning Running multiple workers or replicas?
|
||||
Run migrations on a single instance first: set `UVICORN_WORKERS=1` or `ENABLE_DB_MIGRATIONS=false` on all but one instance. See the [Scaling guide](/getting-started/advanced-topics/scaling) for details.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Manual Update
|
||||
|
||||
<Tabs groupId="setup-method">
|
||||
@@ -25,7 +61,7 @@ Keeping Open WebUI updated ensures you have the latest features, security patche
|
||||
# 1. Stop and remove the container (data in the volume is preserved)
|
||||
docker rm -f open-webui
|
||||
|
||||
# 2. Pull the latest image
|
||||
# 2. Pull the latest image (or replace :main with a pinned version)
|
||||
docker pull ghcr.io/open-webui/open-webui:main
|
||||
|
||||
# 3. Recreate the container
|
||||
@@ -64,87 +100,110 @@ volumes:
|
||||
open-webui:
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="python" label="Python (pip)">
|
||||
|
||||
```bash
|
||||
pip install -U open-webui
|
||||
```
|
||||
|
||||
The `-U` flag upgrades to the latest version. Then restart the server:
|
||||
|
||||
```bash
|
||||
open-webui serve
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::warning Set WEBUI_SECRET_KEY to avoid logout on every update
|
||||
Without a persistent `WEBUI_SECRET_KEY`, a new key is generated each time the container is recreated, invalidating all sessions. Generate one with `openssl rand -hex 32` and keep it across updates.
|
||||
Without a persistent `WEBUI_SECRET_KEY`, a new key is generated each time the container is recreated, invalidating all sessions. Generate one with `openssl rand -hex 32` and keep it across updates. See the [Environment Variable Reference](/reference/env-configuration) for details.
|
||||
:::
|
||||
|
||||
### Pinning a Version
|
||||
### Verify the Update
|
||||
|
||||
By default the `:main` tag always points to the latest build. For production, pin a specific release:
|
||||
After updating, confirm everything is working:
|
||||
|
||||
```
|
||||
ghcr.io/open-webui/open-webui:v0.8.6
|
||||
ghcr.io/open-webui/open-webui:v0.8.6-cuda
|
||||
ghcr.io/open-webui/open-webui:v0.8.6-ollama
|
||||
```
|
||||
1. **Check version in logs:**
|
||||
```bash
|
||||
docker logs open-webui 2>&1 | head -20
|
||||
```
|
||||
2. **Load the UI** at [http://localhost:3000](http://localhost:3000). You should see the login page.
|
||||
3. **If the UI looks broken**, clear your browser cache (`Ctrl+F5` / `Cmd+Shift+R`).
|
||||
4. **If you see migration errors** in the logs, check the [release notes](https://github.com/open-webui/open-webui/releases) for known issues and the [Connection Errors](/troubleshooting/connection-error) troubleshooting page.
|
||||
|
||||
### Rolling Back
|
||||
---
|
||||
|
||||
If an update causes problems, pin the previous version:
|
||||
## Rolling Back
|
||||
|
||||
If an update causes problems, you can go back to a previous version by pinning its tag.
|
||||
|
||||
<Tabs groupId="setup-method">
|
||||
<TabItem value="docker-run" label="Docker Run" default>
|
||||
|
||||
```bash
|
||||
docker rm -f open-webui
|
||||
docker pull ghcr.io/open-webui/open-webui:v0.8.3
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
|
||||
-e WEBUI_SECRET_KEY="your-secret-key" \
|
||||
--name open-webui ghcr.io/open-webui/open-webui:v0.8.3
|
||||
--name open-webui --restart always \
|
||||
ghcr.io/open-webui/open-webui:v0.8.3
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="docker-compose" label="Docker Compose">
|
||||
|
||||
Change the image tag in your `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
image: ghcr.io/open-webui/open-webui:v0.8.3
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="python" label="Python (pip)">
|
||||
|
||||
```bash
|
||||
pip install open-webui==0.8.3
|
||||
open-webui serve
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::caution Database migrations are one-way
|
||||
If the version you updated to ran a database migration, rolling back the container **does not** undo the migration. The older version may not work with the newer database schema. In that case, you need to restore from a backup taken **before** the update. For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration) guide.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Automated Updates
|
||||
## Stay Notified About Updates
|
||||
|
||||
:::warning
|
||||
Automated updates can break your deployment if a release includes breaking changes or migration issues. Review release notes before auto-updating production systems, and always have a backup.
|
||||
:::
|
||||
|
||||
### Choosing a Tool
|
||||
|
||||
| Feature | Watchtower | WUD | Diun |
|
||||
|---------|:---:|:---:|:---:|
|
||||
| **Auto-updates containers** | ✅ | ❌ (manual via UI) | ❌ |
|
||||
| **Web interface** | ❌ | ✅ | ❌ |
|
||||
| **Notifications** | ✅ | ✅ | ✅ |
|
||||
| **Docker 29+** | ✅ (forks) | ✅ | ✅ |
|
||||
| **Resource usage** | Low | Medium | Very Low |
|
||||
| **Best for** | Homelabs | Visual monitoring | Notification-only |
|
||||
Instead of checking manually, use a tool to monitor for new releases. Options are listed from safest to most hands-on.
|
||||
|
||||
:::tip Recommendation
|
||||
- **For homelabs/personal use:** nicholas-fedor/watchtower (automated)
|
||||
- **For managed environments:** WUD (visual + manual control)
|
||||
- **For production/critical systems:** Diun (notifications only) + manual updates
|
||||
- **Production / critical systems:** Diun (notification-only) + manual updates
|
||||
- **Managed environments:** WUD (visual dashboard + manual trigger)
|
||||
- **Homelabs / personal use:** Watchtower (fully automated)
|
||||
:::
|
||||
|
||||
### Watchtower
|
||||
|
||||
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 available: [nicholas-fedor/watchtower](https://watchtower.nickfedor.com/) and Marrrrrrrrry/watchtower, both compatible with Docker 29+.
|
||||
|
||||
**One-time update:**
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --run-once open-webui
|
||||
```
|
||||
|
||||
**Continuous (check every 6 hours):**
|
||||
```bash
|
||||
docker run -d --name watchtower --restart unless-stopped \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --interval 21600 open-webui
|
||||
```
|
||||
|
||||
Set `WATCHTOWER_CLEANUP=true` to auto-remove old images. See [Watchtower docs](https://watchtower.nickfedor.com/) for scheduling, notifications, and monitor-only mode.
|
||||
|
||||
### What's Up Docker (WUD)
|
||||
|
||||
Web UI for monitoring container updates and triggering them manually. See [WUD documentation](https://getwud.github.io/wud/) for setup.
|
||||
| Feature | Diun | WUD | Watchtower |
|
||||
|---------|:---:|:---:|:---:|
|
||||
| **Auto-updates containers** | ❌ | ❌ (manual via UI) | ✅ |
|
||||
| **Web interface** | ❌ | ✅ | ❌ |
|
||||
| **Notifications** | ✅ | ✅ | ✅ |
|
||||
| **Docker 29+** | ✅ | ✅ | ✅ (forks) |
|
||||
| **Resource usage** | Very Low | Medium | Low |
|
||||
|
||||
### Diun
|
||||
|
||||
Notification-only — alerts you when updates are available (email, Slack, Discord, Telegram, etc.) without touching your containers.
|
||||
Notification-only. Alerts you when updates are available (email, Slack, Discord, Telegram, etc.) without touching your containers. You decide when and how to update.
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
@@ -171,24 +230,78 @@ services:
|
||||
|
||||
See [Diun documentation](https://crazymax.dev/diun/) for full setup and notification options.
|
||||
|
||||
### What's Up Docker (WUD)
|
||||
|
||||
Web UI for monitoring container updates and triggering them manually. See [WUD documentation](https://getwud.github.io/wud/) for setup.
|
||||
|
||||
### Watchtower
|
||||
|
||||
Fully automated. Pulls new images and recreates containers without intervention.
|
||||
|
||||
:::warning
|
||||
The original `containrrr/watchtower` is **no longer maintained** and fails with Docker 29+. Use the [nicholas-fedor/watchtower](https://watchtower.nickfedor.com/) fork instead.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
Automated updates can break your deployment if a release includes breaking changes or database migrations. Review release notes before auto-updating production systems, and always have a backup.
|
||||
:::
|
||||
|
||||
**One-time update:**
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --run-once open-webui
|
||||
```
|
||||
|
||||
**Continuous (check every 6 hours):**
|
||||
```bash
|
||||
docker run -d --name watchtower --restart unless-stopped \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
nickfedor/watchtower --interval 21600 open-webui
|
||||
```
|
||||
|
||||
Set `WATCHTOWER_CLEANUP=true` to auto-remove old images. See [Watchtower docs](https://watchtower.nickfedor.com/) for scheduling, notifications, and monitor-only mode.
|
||||
|
||||
---
|
||||
|
||||
## Backup & Restore
|
||||
|
||||
All data (chats, users, uploads) lives in the `open-webui` Docker volume.
|
||||
All data lives in the `open-webui` Docker volume, including:
|
||||
- **Database**: chats, users, settings, admin configuration
|
||||
- **Uploaded files**: documents, images, knowledge base content
|
||||
- **Generated content**: image generation outputs, exported data
|
||||
|
||||
### Backup
|
||||
|
||||
**Backup:**
|
||||
```bash
|
||||
docker run --rm -v open-webui:/data -v $(pwd):/backup \
|
||||
alpine tar czf /backup/openwebui-$(date +%Y%m%d).tar.gz /data
|
||||
```
|
||||
|
||||
**Restore:**
|
||||
Back up **before every update** and on a regular schedule (daily or weekly, depending on how actively you use Open WebUI).
|
||||
|
||||
### Restore
|
||||
|
||||
:::caution
|
||||
The restore command **deletes everything in the volume** before extracting the backup. Make sure you're restoring the right file.
|
||||
:::
|
||||
|
||||
```bash
|
||||
docker stop open-webui
|
||||
docker run --rm -v open-webui:/data -v $(pwd):/backup \
|
||||
alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-20250216.tar.gz -C /"
|
||||
alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-YYYYMMDD.tar.gz -C /"
|
||||
docker start open-webui
|
||||
```
|
||||
|
||||
For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration.md) guide.
|
||||
Replace `YYYYMMDD` with the actual date of your backup file.
|
||||
|
||||
For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration) guide.
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
- [Scaling Open WebUI](/getting-started/advanced-topics/scaling): multi-worker and multi-instance deployments
|
||||
- [Connection Errors](/troubleshooting/connection-error): troubleshooting post-update connectivity issues
|
||||
- [Environment Variable Reference](/reference/env-configuration): all configuration options including `WEBUI_SECRET_KEY`
|
||||
- [Release Notes](https://github.com/open-webui/open-webui/releases): changelog for every version
|
||||
|
||||
@@ -7,7 +7,7 @@ This guide provides essential information on how to interact with the API endpoi
|
||||
|
||||
## Authentication
|
||||
|
||||
To ensure secure access to the API, authentication is required 🛡️. You can authenticate your API requests using the Bearer Token mechanism. Obtain your API key from **Settings > Account** in the Open WebUI, or alternatively, use a JWT (JSON Web Token) for authentication.
|
||||
To ensure secure access to the API, authentication is required 🛡️. You can authenticate your API requests using the Bearer Token mechanism. Obtain your API key from **Settings > Account** in the Open WebUI, or alternatively, use a JWT (JSON Web Token) for authentication. For full instructions on enabling and generating API keys - including the admin toggle and group permissions required for non-admin users - see [API Keys](/features/access-security/api-keys).
|
||||
|
||||
## Swagger Documentation Links
|
||||
|
||||
|
||||
+35
-19
@@ -47,21 +47,6 @@ Open WebUI exposes a full REST API authenticated via Bearer tokens or JWTs. Use
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Network Diagrams
|
||||
|
||||
**See exactly how Open WebUI, Ollama, and Docker talk to each other.**
|
||||
|
||||
Visual C4 diagrams for every common deployment topology: host networking, Docker Compose stacks, separate networks, and Linux vs. macOS/Windows differences. Use these to debug connectivity issues or plan your architecture.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🖥️ **macOS / Windows** | Host Ollama, Compose stack, separate networks, host-network pitfalls |
|
||||
| 🐧 **Linux** | Same topologies with Linux-specific networking behavior |
|
||||
|
||||
[**View network diagrams →**](/reference/network-diagrams)
|
||||
|
||||
---
|
||||
|
||||
## 🔒 HTTPS Configuration
|
||||
|
||||
**Terminate TLS in front of Open WebUI with Nginx, Caddy, or HAProxy.**
|
||||
@@ -81,16 +66,47 @@ Step-by-step reverse proxy configurations for securing your deployment with HTTP
|
||||
|
||||
---
|
||||
|
||||
## 📊 Monitoring
|
||||
## 🔑 API Keys
|
||||
|
||||
**Observe your deployment with OpenTelemetry, Prometheus, Grafana, and Langfuse.**
|
||||
**Programmatic access to Open WebUI for scripts, bots, and integrations.**
|
||||
|
||||
Production monitoring guides covering traces, metrics, structured logs, and LLM-specific observability. Integrate with your existing observability stack or set up a new one from scratch.
|
||||
Generate personal access tokens that let external code call the same endpoints the web UI uses. Each key inherits the permissions of the user who created it.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🔐 **Bearer token auth** | Standard `Authorization: Bearer` header, works with any HTTP client |
|
||||
| 🛡️ **Scoped to user** | Key inherits your role and group permissions |
|
||||
| 🚫 **Endpoint restrictions** | Optionally limit which API routes a key can access |
|
||||
|
||||
[**Set up API keys →**](/features/access-security/api-keys)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
**Observe your deployment with Uptime Kuma, OpenTelemetry, Prometheus, and Grafana.**
|
||||
|
||||
Production monitoring guides covering health checks, model connectivity verification, distributed tracing, metrics, and structured logs. Integrate with your existing observability stack or set up a new one from scratch.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| ✅ **Health checks** | Basic, model connectivity, and deep health checks with Uptime Kuma |
|
||||
| 📡 **OpenTelemetry** | Traces, metrics, and logs piped to any OTLP-compatible backend |
|
||||
| 📈 **Dashboards** | Prometheus + Grafana for real-time system and model metrics |
|
||||
| 🔍 **LLM tracing** | Langfuse integration for prompt-level observability |
|
||||
|
||||
[**Set up monitoring →**](/reference/monitoring)
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Network Diagrams
|
||||
|
||||
**See how Open WebUI, Ollama, and Docker communicate across different deployment topologies.**
|
||||
|
||||
Visual C4 diagrams covering host networking, Docker Compose stacks, separate networks, and platform-specific differences. Useful for debugging connectivity issues or planning your architecture.
|
||||
|
||||
| | |
|
||||
| :--- | :--- |
|
||||
| 🖥️ **macOS / Windows** | Host Ollama, Compose stack, separate networks, host-network pitfalls |
|
||||
| 🐧 **Linux** | Same topologies with Linux-specific networking behavior |
|
||||
|
||||
[**View network diagrams →**](/reference/network-diagrams)
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
title: "API Keys & Monitoring"
|
||||
title: "Monitoring"
|
||||
---
|
||||
|
||||
# API Keys & Monitoring Your Open WebUI 🔑🩺
|
||||
# Monitoring Your Open WebUI 🩺
|
||||
|
||||
This guide covers two essential topics: setting up API keys for programmatic access to Open WebUI, and monitoring your instance to ensure reliability and performance.
|
||||
This guide covers monitoring your Open WebUI instance to ensure reliability and performance.
|
||||
|
||||
**Why Monitor?**
|
||||
|
||||
@@ -73,119 +73,21 @@ See the [Open WebUI API documentation](https://docs.openwebui.com/reference/api-
|
||||
|
||||
**How to Test with `curl` (Authenticated):**
|
||||
|
||||
You'll need an API key to access this endpoint. See the "Authentication Setup" section below for instructions on generating an API key.
|
||||
You'll need an API key to access this endpoint. See [API Keys](/features/access-security/api-keys) for instructions on generating one.
|
||||
|
||||
```bash
|
||||
# Authenticated model connectivity check
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" https://your-open-webui-instance/api/models
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" http://your-open-webui-instance:8080/api/models
|
||||
```
|
||||
|
||||
*(Replace `YOUR_API_KEY` with your actual API key and `your-open-webui-instance` with your Open WebUI address.)*
|
||||
|
||||
**Expected Output:** A successful request will return a `200 OK` status code and a JSON response containing a list of models.
|
||||
|
||||
### Authentication Setup for API Key 🔑
|
||||
|
||||
Before you can monitor the `/api/models` endpoint, you need to configure API keys in Open WebUI. API key creation requires that the global API keys feature is enabled. For non-admin users, API key creation also requires the API Keys feature permission.
|
||||
|
||||
#### Step 1: Enable API Keys Globally (Admin Required)
|
||||
|
||||
1. Log in to Open WebUI as an **administrator**.
|
||||
2. Click on your **profile icon** in the bottom-left corner of the sidebar, then select **Admin Panel**.
|
||||
3. Navigate to **Settings** > **General**.
|
||||
4. Scroll down to the **Authentication** section.
|
||||
5. Find the **"Enable API Keys"** toggle and **turn it ON**.
|
||||
6. *(Optional)* Configure additional API key restrictions:
|
||||
- **API Key Endpoint Restrictions**: Enable this to limit which endpoints can be accessed via API keys.
|
||||
- **Allowed Endpoints**: Specify a comma-separated list of allowed endpoints (e.g., `/api/v1/models,/api/v1/chat/completions`).
|
||||
7. Click **Save** at the bottom of the page.
|
||||
|
||||
:::info
|
||||
|
||||
This enables the API key feature globally.
|
||||
|
||||
- Admin users can now generate API keys immediately.
|
||||
- Non-admin users still require API Keys permission (configured in Step 2).
|
||||
|
||||
:::tip Dedicated Monitoring Account
|
||||
For production monitoring, create a **non-admin user** specifically for monitoring (e.g., `monitoring-bot`), generate an API key from that account, and use it for all monitoring requests. This limits blast radius if the key is ever compromised.
|
||||
:::
|
||||
|
||||
#### Step 2: Grant API Key Permission (Admin Required)
|
||||
|
||||
Non-admin users need explicit API Keys permission. Administrators can grant API key permissions for non-admin users using one of the following methods:
|
||||
|
||||
##### Option A: Grant Permission via Default Permissions
|
||||
|
||||
This grants the API Keys permission to **all users with the "user" role**:
|
||||
|
||||
1. In the **Admin Panel**, navigate to **Users** > **Groups**.
|
||||
2. At the bottom of the Groups page, click on **"Default permissions"** (this applies to all users with the "user" role).
|
||||
3. In the modal that opens, scroll to the **Features Permissions** section.
|
||||
4. Find **"API Keys"** and **toggle it ON**.
|
||||
5. Click **Save**.
|
||||
|
||||
:::info
|
||||
|
||||
**Note for Administrators:** "Default permissions" only applies to accounts with the "user" role. Admin accounts do not need `features.api_keys` to generate API keys, but you may still use groups to grant that permission to non-admin users.
|
||||
|
||||
:::
|
||||
|
||||
:::warning
|
||||
|
||||
Enabling API Keys for all users means any user can generate API keys that provide programmatic access to Open WebUI with their account's permissions. Consider using User Groups (Option B) for more restrictive access control.
|
||||
|
||||
:::
|
||||
|
||||
##### Option B: Grant Permission via User Groups
|
||||
|
||||
For more granular control, you can grant API key permissions to specific user groups only:
|
||||
|
||||
1. In the **Admin Panel**, navigate to **Users** > **Groups**.
|
||||
2. Select the group you want to grant API key permissions to (or click the **+ button** to create a new group).
|
||||
3. In the group edit modal, click on the **Permissions** tab.
|
||||
4. Scroll to **Features Permissions**.
|
||||
5. Find **"API Keys"** and **toggle it ON**.
|
||||
6. Click **Save**.
|
||||
|
||||
:::tip
|
||||
|
||||
Create a dedicated monitoring group (e.g., "Monitoring Users") and add only the accounts that need API key access for monitoring purposes. This follows the principle of least privilege.
|
||||
|
||||
:::
|
||||
|
||||
#### Step 3: Generate an API Key (User Action)
|
||||
|
||||
Once global API keys are enabled (and for non-admin users, API Keys permission is granted):
|
||||
|
||||
1. Log in to Open WebUI with a user account that has API key permissions.
|
||||
2. Click on your **profile icon** in the bottom-left corner of the sidebar.
|
||||
3. Select **Settings** > **Account**.
|
||||
4. In the **API Keys** section, click **Generate New API Key**.
|
||||
5. Give the API key a descriptive name (e.g., "Monitoring API Key").
|
||||
6. **Copy the generated API key** immediately and store it securely—you won't be able to view it again.
|
||||
|
||||
:::warning
|
||||
|
||||
Treat your API key like a password! Store it securely and never share it publicly. If you suspect an API key has been compromised, delete it immediately and generate a new one.
|
||||
|
||||
:::
|
||||
|
||||
#### Recommended: Create a Dedicated Monitoring Account
|
||||
|
||||
For production monitoring, we recommend:
|
||||
|
||||
1. Create a **non-administrator user account** specifically for monitoring (e.g., "monitoring-bot").
|
||||
2. Add this account to a group with API key permissions (or ensure default permissions allow API key creation).
|
||||
3. Generate an API key from this account.
|
||||
|
||||
This approach limits the potential impact if the monitoring API key is compromised—the attacker would only have access to the permissions granted to that specific monitoring account, not administrator privileges.
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
If you don't see the API key generation option in your account settings:
|
||||
|
||||
- **Check global setting**: Verify that an administrator has enabled API keys globally under **Admin Panel** > **Settings** > **General** > **Enable API Keys**. See [`ENABLE_API_KEYS`](/reference/env-configuration#enable_api_keys).
|
||||
- **Check your permissions (non-admin users)**: Verify that your user account or group has been granted the "API Keys" feature permission under **Features Permissions**. See [`USER_PERMISSIONS_FEATURES_API_KEYS`](/reference/env-configuration#user_permissions_features_api_keys).
|
||||
|
||||
### Using Uptime Kuma for Model Connectivity Monitoring 🐻
|
||||
|
||||
1. **Create a New Monitor in Uptime Kuma:**
|
||||
@@ -251,3 +153,10 @@ curl -X POST https://your-open-webui-instance/api/chat/completions \
|
||||
**Setting up Level 3 Monitoring in Uptime Kuma would involve configuring an HTTP(s) monitor with a POST request, JSON body, authentication headers, and potentially JSON query to validate the response content. This is a more advanced setup and can be customized based on your specific needs.**
|
||||
|
||||
By implementing these monitoring levels, you can proactively ensure the health, reliability, and performance of your Open WebUI instance, providing a consistently positive experience for users.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **[OpenTelemetry](/reference/monitoring/otel)** - Distributed tracing, metrics, and logs with Grafana, Prometheus, Jaeger, and more
|
||||
- **[API Keys](/features/access-security/api-keys)** - Full guide on enabling and generating API keys for programmatic access
|
||||
|
||||
@@ -1,15 +1,19 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
sidebar_position: 100
|
||||
title: "Network Diagrams"
|
||||
---
|
||||
|
||||
Here, we provide clear and structured diagrams to help you understand how various components of the network interact within different setups. This documentation is designed to assist both macOS/Windows and Linux users. Each scenario is illustrated using Mermaid diagrams to show how the interactions are set up depending on the different system configurations and deployment strategies.
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
## Mac OS/Windows Setup Options 🖥️
|
||||
Visual C4 diagrams for common deployment topologies showing how Open WebUI, Ollama, and Docker communicate. Use these to debug connectivity issues or plan your architecture.
|
||||
|
||||
<Tabs groupId="os-platform">
|
||||
<TabItem value="macos-windows" label="macOS / Windows" default>
|
||||
|
||||
### Ollama on Host, Open WebUI in Container
|
||||
|
||||
In this scenario, `Ollama` runs directly on the host machine while `Open WebUI` operates within a Docker container.
|
||||
`Ollama` runs directly on the host machine while `Open WebUI` operates within a Docker container.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -47,7 +51,7 @@ UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
|
||||
### Ollama and Open WebUI, Separate Networks
|
||||
|
||||
Here, `Ollama` and `Open WebUI` are deployed in separate Docker networks, potentially leading to connectivity issues.
|
||||
`Ollama` and `Open WebUI` are deployed in separate Docker networks. This leads to connectivity issues.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -69,7 +73,7 @@ UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
|
||||
### Open WebUI in Host Network
|
||||
|
||||
In this configuration, `Open WebUI` utilizes the host network, which impacts its ability to connect in certain environments.
|
||||
`Open WebUI` utilizes the host network, which impacts its ability to connect in certain environments.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -83,11 +87,12 @@ Rel(user, openwebui, "Unable to connect, host network is the VM's network")
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
## Linux Setup Options 🐧
|
||||
</TabItem>
|
||||
<TabItem value="linux" label="Linux">
|
||||
|
||||
### Ollama on Host, Open WebUI in Container (Linux)
|
||||
### Ollama on Host, Open WebUI in Container
|
||||
|
||||
This diagram is specific to the Linux platform, with `Ollama` running on the host and `Open WebUI` deployed inside a Docker container.
|
||||
`Ollama` runs on the host and `Open WebUI` is deployed inside a Docker container.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -103,9 +108,9 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Ollama and Open WebUI in Compose Stack (Linux)
|
||||
### Ollama and Open WebUI in Compose Stack
|
||||
|
||||
A set-up where both `Ollama` and `Open WebUI` reside within the same Docker Compose stack, allowing for straightforward networking on Linux.
|
||||
Both `Ollama` and `Open WebUI` reside within the same Docker Compose stack, allowing for straightforward networking.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -123,9 +128,9 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Ollama and Open WebUI, Separate Networks (Linux)
|
||||
### Ollama and Open WebUI, Separate Networks
|
||||
|
||||
A scenario in which `Ollama` and `Open WebUI` are in different Docker networks under a Linux environment, which could hinder connectivity.
|
||||
`Ollama` and `Open WebUI` are in different Docker networks, which can hinder connectivity.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -143,9 +148,9 @@ Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://loc
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
### Open WebUI in Host Network, Ollama on Host (Linux)
|
||||
### Open WebUI in Host Network, Ollama on Host
|
||||
|
||||
An optimal layout where both `Open WebUI` and `Ollama` use the host’s network, facilitating seamless interaction on Linux systems.
|
||||
Both `Open WebUI` and `Ollama` use the host's network, enabling seamless interaction.
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
@@ -159,4 +164,5 @@ Rel(user, openwebui, "Makes requests via listening port", "http://localhost:8080
|
||||
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
|
||||
```
|
||||
|
||||
Each setup addresses different deployment strategies and networking configurations to help you choose the best layout for your requirements.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Reference in New Issue
Block a user