centersl/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-03-27 13:28:37 +07:00
Code Issues Packages Projects Releases Wiki Activity

update various docs

Browse Source
This commit is contained in:
DrMelone
2025-12-20 18:21:21 +01:00
parent dd29bae504
commit 5cf87a0036
7 changed files with 496 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/features/channels/index.md
View File

@@ -9,6 +9,35 @@ title: "Channels"
Channels is currently a **Beta** feature. Functionality is subject to change, and it must be explicitly enabled by an Administrator before it appears in the interface.
:::
## Channel Types
Open WebUI supports three types of channels:
| Type | Description |
|------|-------------|
| **Standard** | Traditional topic-based channels with public or private visibility |
| **Group** | Membership-based channels where users explicitly join as members |
| **Direct Message** | Private one-on-one or multi-user conversations |
### Group Channels
Group channels are collaboration spaces where:
- Users explicitly join as members rather than accessing through permissions
- Support public or private visibility
- Can automatically include members from specified user groups
- Channel managers can add or remove members through the channel info modal
### Direct Message Channels
Direct Message (DM) channels enable private conversations:
- One-on-one or multi-user private messaging
- Automatic deduplication for existing conversations
- Optional channel naming
- Display participant avatars instead of channel icons
- Can be hidden from sidebar while preserving message history
- Automatically reappear when new messages arrive
- Show online/offline status indicator for participants
## Enabling Channels
By default, the Channels feature may be hidden. An **Admin** must enable it globally for the instance.
@@ -22,12 +51,19 @@ By default, the Channels feature may be hidden. An **Admin** must enable it glob
## Creating a Channel
:::note
Channel creation is restricted to administrators only by default.
:::
1. Locate the **Channels** header in the sidebar.
2. Click the **(+) Plus** icon next to the "Channels" header.
3. **Name:** Enter a channel name (e.g., `general`, `python-dev`). Spaces should get converted to hyphens.
4. **Access Control:**
* **Public:** All registered users on your Open WebUI instance can see and join this channel.
* **Private/Group Access:** Only you or users with permission can access this channel.
3. **Select Channel Type:** Choose Standard, Group, or Direct Message.
4. **Name:** Enter a channel name (e.g., `general`, `python-dev`). Spaces are converted to hyphens.
5. **Access Control:**
* **Public:** All registered users can see and join this channel.
* **Private/Group Access:** Only you or users with permission can access.
* For Group channels, select which user groups to auto-include.
* For DM channels, use the user selection interface to choose participants.
## Using Channels
@@ -79,22 +115,33 @@ If a user **does not** have access to view a linked channel (e.g., `#admin-only`
Hover over any message in the timeline to access interaction options:
* **Add Reaction:** Click the **Smiley Face** icon to add a visual emoji eaction to a message.
* **Reply:** Quotes the message within the main channel stream, linking your response to the original message while keeping it visible to everyone in the main flow.
* **Reply in Thread:** Starts a separate, nested conversation thread centered on that specific message. This allows for focused discussions without cluttering the main channel history.
* **Edit:** Click the **Pencil** icon to modify the content of your message.
* **Delete:** Click the **Trash** icon to remove the message from the channel.
* **Add Reaction:** Click the **Smiley Face** icon to add an emoji reaction. Hovering over reactions shows the names of users who reacted (up to 3 names plus a count for additional reactors).
* **Pin Message:** Pin important messages for easy reference. Pinned messages are highlighted and accessible via a dedicated modal in the navbar.
* **Reply:** Quotes the message within the main channel stream.
* **Reply in Thread:** Starts a separate, nested conversation thread.
* **Edit:** Click the **Pencil** icon to modify your message.
* **Delete:** Click the **Trash** icon to remove the message.
:::note
Currently, reactions are purely visual and do not influence model behavior.
:::
### File Attachments
Channels support file sharing:
* **Paste from clipboard:** Images and files can be pasted directly using Ctrl+V / Cmd+V
* **Drag and drop:** Drag files directly into the message input
* **Image processing:** AI models in channels can view and analyze shared images
### Collaboration
If your Open WebUI instance supports multiple users:
* **Real-time updates:** Messages appear instantly for all users currently viewing the channel.
* **Shared Context:** When a teammate asks an AI a question, the AI's response becomes part of the context for the *next* user's query. This allows teams to iterate on AI outputs together.
* **Real-time updates:** Messages appear instantly using optimistic UI rendering.
* **Shared Context:** AI responses become part of the context for subsequent queries.
* **Unread indicators:** Visual badges show unread message counts in the sidebar.
* **User list:** Click to view all users with access to the channel.
## Managing Channels
@@ -106,9 +153,17 @@ To manage an existing channel:
2. Click the **Gear (Edit)** icon.
:::info
Only the Channel Creator or an Admin can delete a channel.
Channel creators can edit and delete their own group and DM channels without administrator privileges. Standard channels require admin access.
:::
### Permissions
Channels support granular access control:
* **Write access:** Required for posting, editing, and deleting messages
* **Read-only access:** Users can view content but cannot contribute
* **Feature toggle:** Administrators can control channel access via `USER_PERMISSIONS_FEATURES_CHANNELS` environment variable or group permissions in the admin panel
## Use Cases
### 1. Team Development (`#dev-team`)

22
docs/features/notes.md
View File

@@ -24,6 +24,10 @@ Notes utilizes a context-aware **Floating Toolbar** for formatting, rather than
* **Styling:** **Bold**, *Italic*, Underline, and ~~Strikethrough~~.
* **Code:** Inline code formatting `</>`.
### Drag-and-Drop List Reordering
List items can be reordered by dragging. Visual drag handles appear when hovering over list items, making it easy to reorganize content.
While this toolbar is native to the Notes workspace, it can also be enabled for standard Chats.
:::info To see this toolbar in your main chat input:
@@ -100,7 +104,7 @@ You can export your notes in standard formats:
* **Plain text (.txt):** The raw text content.
* **Plain text (.md):** Preserves Markdown structure (headers, code blocks, etc.).
* **PDF document (.pdf):** A rendered document with visual formatting applied.
* **PDF document (.pdf):** A rendered document with visual formatting applied. Dark mode styling is automatically detected and applied.
### Sharing
@@ -114,6 +118,22 @@ You can delete notes permanently from two locations:
1. **From the Notes Dashboard:** Click the **More (`...`)** button on the individual note card in the list view and select **Delete**.
2. **From the Editor:** While inside an open note, click the **More (`...`)** button in the top right corner of the screen and select **Delete**.
### Sharing Permissions
Administrators can control whether users are allowed to share notes publicly:
* **Environment Variable:** `USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING`
* **Admin Panel:** Settings > Users > Default Permissions
### Quick Note Creation via URL
Notes can be created directly by navigating to `/notes/new` with optional query parameters:
* `/notes/new` — Opens a blank note
* `/notes/new?title=My%20Title&content=Initial%20text` — Pre-populates title and content
This enables bookmarks and shortcuts for fast note creation.
---
## Use Cases

2
docs/tutorials/maintenance/backups.md
View File

@@ -403,7 +403,7 @@ In the interest of keeping this guide reasonably thorough these additional subje
| Topic | Description |
|---|---|
| SQLite Built-in Backup | Consider using SQLite's `.backup` command for a consistent database backup solution. |
| Encryption | Modify backup scripts to incorporate encryption at rest for enhanced security. |
| Encryption | Modify backup scripts to incorporate encryption at rest. See [Database Encryption with SQLCipher](/tutorials/tips/sqlite-database#database-encryption-with-sqlcipher) for database-level encryption. |
| Disaster Recovery and Testing | Develop a disaster recovery plan and regularly test the backup and restore process. |
| Alternative Backup Tools | Explore other command-line backup tools like `borgbackup` or `restic` for advanced features. |
| Email Notifications and Webhooks | Implement email notifications or webhooks to monitor backup success or failure. |

9
docs/tutorials/maintenance/database.mdx
View File

@@ -93,4 +93,11 @@ docker cp ./webui.db open-webui:/app/backend/data/webui.db
docker start open-webui
```
With these steps, you can easily manage your Open WebUI migration or backup process. Keep in mind the database format you're using to ensure compatibility.
With these steps, you can easily manage your Open WebUI migration or backup process. Keep in mind the database format you're using to ensure compatibility.
---
## Related Guides
- [SQLite Database Overview](/tutorials/tips/sqlite-database) - Detailed database schema and SQLCipher encryption setup
- [Backups](/tutorials/maintenance/backups) - Comprehensive backup strategies for your instance

117
docs/tutorials/tips/improve-performance-local.md
View File

@@ -15,16 +15,16 @@ This guide explains how to optimize your setup by configuring a dedicated, light
## Why Does Open-WebUI Feel Slow?
By default, Open-WebUI has several background tasks that can make it feel like magic but can also place a eavy load on local resources:
By default, Open-WebUI has several background tasks that can make it feel like magic but can also place a heavy load on local resources:
- **Title Generation**
- **Tag Generation**
- **Autocomplete Generation** (this function triggers on every keystroke)
- **Search Query Generation**
Each of these features makes asynchronous requests to your model. For example, continuous calls from the utocomplete feature can significantly delay responses on devices with limited memory >or processing power, uch as a Mac with 32GB of RAM running a 32B quantized model.
Each of these features makes asynchronous requests to your model. For example, continuous calls from the autocomplete feature can significantly delay responses on devices with limited memory or processing power, such as a Mac with 32GB of RAM running a 32B quantized model.
Optimizing the task model can help isolate these background tasks from your main chat application, improving verall responsiveness.
Optimizing the task model can help isolate these background tasks from your main chat application, improving overall responsiveness.
:::
@@ -78,6 +78,109 @@ Implementing these recommendations can greatly improve the responsiveness of Ope
---
## ⚙️ Environment Variables for Performance
You can also configure performance-related settings via environment variables. Add these to your Docker Compose file or `.env` file.
:::tip
Many of these settings can also be configured directly in the **Admin Panel > Settings** interface. Environment variables are useful for initial deployment configuration or when managing settings across multiple instances.
:::
### Task Model Configuration
Set a dedicated lightweight model for background tasks:
```bash
TASK_MODEL=llama3.2:3b
# For OpenAI-compatible endpoints
TASK_MODEL_EXTERNAL=gpt-4o-mini
```
### Disable Unnecessary Features
```bash
# Disable automatic title generation
ENABLE_TITLE_GENERATION=False
# Disable follow-up question suggestions
ENABLE_FOLLOW_UP_GENERATION=False
# Disable autocomplete suggestions (triggers on every keystroke - high impact!)
ENABLE_AUTOCOMPLETE_GENERATION=False
# Disable automatic tag generation
ENABLE_TAGS_GENERATION=False
# Disable search query generation for RAG (if not using web search)
ENABLE_SEARCH_QUERY_GENERATION=False
# Disable retrieval query generation
ENABLE_RETRIEVAL_QUERY_GENERATION=False
```
### Enable Caching and Optimization
```bash
# Cache model list responses (seconds) - reduces API calls
MODELS_CACHE_TTL=300
# Cache LLM-generated search queries - eliminates duplicate LLM calls when both web search and RAG are active
ENABLE_QUERIES_CACHE=True
# Convert base64 images to file URLs - reduces response size and database strain
ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION=True
# Batch streaming tokens to reduce CPU load (recommended: 5-10 for high concurrency)
CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE=5
# Enable gzip compression for HTTP responses (enabled by default)
ENABLE_COMPRESSION_MIDDLEWARE=True
```
### Database and Persistence
```bash
# Disable real-time chat saving for better performance (trades off data persistence)
ENABLE_REALTIME_CHAT_SAVE=False
```
### Network Timeouts
```bash
# Increase timeout for slow models (default: 300 seconds)
AIOHTTP_CLIENT_TIMEOUT=300
# Faster timeout for model list fetching (default: 10 seconds)
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=5
```
### RAG Performance
```bash
# Enable parallel embedding for faster document processing (requires sufficient resources)
RAG_EMBEDDING_BATCH_SIZE=100
```
### High Concurrency Settings
For larger instances with many concurrent users:
```bash
# Increase thread pool size (default is 40)
THREAD_POOL_SIZE=500
```
:::info
For a complete list of environment variables, see the [Environment Variable Configuration](/getting-started/env-configuration) documentation.
:::
---
## 💡 Additional Tips
- **Monitor System Resources:** Use your operating system’s tools (such as Activity Monitor on macOS or Task Manager on Windows) to keep an eye on resource usage.
@@ -87,4 +190,12 @@ Implementing these recommendations can greatly improve the responsiveness of Ope
---
## Related Guides
- [Reduce RAM Usage](/tutorials/tips/reduce-ram-usage) - For memory-constrained environments like Raspberry Pi
- [SQLite Database Overview](/tutorials/tips/sqlite-database) - Database schema, encryption, and advanced configuration
- [Environment Variable Configuration](/getting-started/env-configuration) - Complete list of all configuration options
---
By applying these configuration changes, you'll support a more responsive and efficient Open-WebUI experience, allowing your local LLM to focus on delivering high-quality chat interactions without unnecessary delays.

165
docs/tutorials/tips/reduce-ram-usage.md
View File

@@ -5,23 +5,164 @@ title: "Reduce RAM Usage"
## Reduce RAM Usage
If you are deploying this image in a RAM-constrained environment, there are a few things you can do to slim down the image.
If you are deploying Open WebUI in a RAM-constrained environment (such as a Raspberry Pi, small VPS, or shared hosting), there are several strategies to significantly reduce memory consumption.
On a Raspberry Pi 4 (arm64) with version v0.3.10, this was able to reduce idle memory consumption from >1GB to ~200MB (as observed with `docker container stats`).
On a Raspberry Pi 4 (arm64) with version v0.3.10, these optimizations reduced idle memory consumption from >1GB to ~200MB (as observed with `docker container stats`).
## TLDR
---
Set the following environment variables (or the respective UI settings for an existing deployment): `RAG_EMBEDDING_ENGINE: ollama`, `AUDIO_STT_ENGINE: openai`.
## Quick Start
## Longer explanation
Set the following environment variables for immediate RAM savings:
Much of the memory consumption is due to loaded ML models. Even if you are using an external language model (OpenAI or unbundled ollama), many models may be loaded for additional purposes.
```bash
# Use external embedding instead of local SentenceTransformers
RAG_EMBEDDING_ENGINE=ollama
As of v0.3.10 this includes:
# Use external Speech-to-Text instead of local Whisper
AUDIO_STT_ENGINE=openai
```
- Speech-to-text (whisper by default)
- RAG embedding engine (defaults to local SentenceTransformers model)
- Image generation engine (disabled by default)
:::tip
These settings can also be configured in the **Admin Panel > Settings** interface - set RAG embedding to Ollama or OpenAI, and Speech-to-Text to OpenAI or WebAPI.
:::
---
## Why Does Open WebUI Use So Much RAM?
Much of the memory consumption comes from locally loaded ML models. Even when using an external LLM (OpenAI or separate Ollama instance), Open WebUI may load additional models for:
| Feature | Default | RAM Impact | Solution |
|---------|---------|------------|----------|
| **RAG Embedding** | Local SentenceTransformers | ~500-800MB | Use Ollama or OpenAI embeddings |
| **Speech-to-Text** | Local Whisper | ~300-500MB | Use OpenAI or WebAPI |
| **Reranking** | Disabled | ~200-400MB when enabled | Keep disabled or use external |
| **Image Generation** | Disabled | Variable | Keep disabled if not needed |
---
## ⚙️ Environment Variables for RAM Reduction
### Offload Embedding to External Service
The biggest RAM saver is using an external embedding engine:
```bash
# Option 1: Use Ollama for embeddings (if you have Ollama running separately)
RAG_EMBEDDING_ENGINE=ollama
# Option 2: Use OpenAI for embeddings
RAG_EMBEDDING_ENGINE=openai
OPENAI_API_KEY=your-api-key
```
### Offload Speech-to-Text
Local Whisper models consume significant RAM:
```bash
# Use OpenAI's Whisper API
AUDIO_STT_ENGINE=openai
# Or use browser-based WebAPI (no external service needed)
AUDIO_STT_ENGINE=webapi
```
### Disable Unused Features
Disable features you don't need to prevent model loading:
```bash
# Disable image generation (prevents loading image models)
ENABLE_IMAGE_GENERATION=False
# Disable code execution (reduces overhead)
ENABLE_CODE_EXECUTION=False
# Disable code interpreter
ENABLE_CODE_INTERPRETER=False
```
### Reduce Background Task Overhead
These settings reduce memory usage from background operations:
```bash
# Disable autocomplete (high resource usage)
ENABLE_AUTOCOMPLETE_GENERATION=False
# Disable automatic title generation
ENABLE_TITLE_GENERATION=False
# Disable tag generation
ENABLE_TAGS_GENERATION=False
# Disable follow-up suggestions
ENABLE_FOLLOW_UP_GENERATION=False
```
### Database and Cache Optimization
```bash
# Disable real-time chat saving (reduces database overhead)
ENABLE_REALTIME_CHAT_SAVE=False
# Reduce thread pool size for low-resource systems
THREAD_POOL_SIZE=10
```
### Vector Database Multitenancy
If using Milvus or Qdrant, enable multitenancy mode to reduce RAM:
```bash
# For Milvus
ENABLE_MILVUS_MULTITENANCY_MODE=True
# For Qdrant
ENABLE_QDRANT_MULTITENANCY_MODE=True
```
---
## 🚀 Recommended Minimal Configuration
For extremely RAM-constrained environments, use this combined configuration:
```bash
# Offload ML models to external services
RAG_EMBEDDING_ENGINE=ollama
AUDIO_STT_ENGINE=openai
# Disable all non-essential features
ENABLE_IMAGE_GENERATION=False
ENABLE_CODE_EXECUTION=False
ENABLE_CODE_INTERPRETER=False
ENABLE_AUTOCOMPLETE_GENERATION=False
ENABLE_TITLE_GENERATION=False
ENABLE_TAGS_GENERATION=False
ENABLE_FOLLOW_UP_GENERATION=False
# Reduce worker overhead
THREAD_POOL_SIZE=10
```
---
## 💡 Additional Tips
- **Monitor Memory Usage**: Use `docker container stats` or `htop` to monitor RAM consumption
- **Restart After Changes**: Environment variable changes require a container restart
- **Fresh Deployments**: Some environment variables only take effect on fresh deployments without an existing `config.json`
- **Consider Alternatives**: For very constrained systems, consider running Open WebUI on a more capable machine and accessing it remotely
---
## Related Guides
- [Improve Local LLM Performance](/tutorials/tips/improve-performance-local) - For optimizing performance without reducing features
- [Environment Variable Configuration](/getting-started/env-configuration) - Complete list of all configuration options
The first 2 are enabled and set to local models by default. You can change the models in the admin panel (RAG: Documents category, set it to Ollama or OpenAI, Speech-to-text: Audio section, work with OpenAI or WebAPI).
If you are deploying a fresh Docker image, you can also set them with the following environment variables: `RAG_EMBEDDING_ENGINE: ollama`, `AUDIO_STT_ENGINE: openai`. Note that these environment variables have no effect if a `config.json` already exists.

156
docs/tutorials/tips/sqlite-database.md
View File

@@ -10,7 +10,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI
:::
> [!WARNING]
> This documentation was created/updated based on version 0.6.30.
> This documentation was created/updated based on version 0.6.41 and updated for recent migrations.
## Open-WebUI Internal SQLite Database
@@ -56,28 +56,31 @@ Here is a complete list of tables in Open-WebUI's SQLite database. The tables ar
| ------- | ---------------- | ------------------------------------------------------------ |
| 01 | auth | Stores user authentication credentials and login information |
| 02 | channel | Manages chat channels and their configurations |
| 03 | channel_member | Tracks user membership and permissions within channels |
| 04 | chat | Stores chat sessions and their metadata |
| 05 | chatidtag | Maps relationships between chats and their associated tags |
| 06 | config | Maintains system-wide configuration settings |
| 07 | document | Stores documents and their metadata for knowledge management |
| 08 | feedback | Captures user feedback and ratings |
| 09 | file | Manages uploaded files and their metadata |
| 10 | folder | Organizes files and content into hierarchical structures |
| 11 | function | Stores custom functions and their configurations |
| 12 | group | Manages user groups and their permissions |
| 13 | knowledge | Stores knowledge base entries and related information |
| 14 | memory | Maintains chat history and context memory |
| 15 | message | Stores individual chat messages and their content |
| 16 | message_reaction | Records user reactions (emojis/responses) to messages |
| 17 | migrate_history | Tracks database schema version and migration records |
| 18 | model | Manages AI model configurations and settings |
| 19 | note | Stores user-created notes and annotations |
| 20 | oauth_session | Manages active OAuth sessions for users |
| 21 | prompt | Stores templates and configurations for AI prompts |
| 22 | tag | Manages tags/labels for content categorization |
| 23 | tool | Stores configurations for system tools and integrations |
| 24 | user | Maintains user profiles and account information |
| 03 | channel_file | Links files to channels and messages |
| 04 | channel_member | Tracks user membership and permissions within channels |
| 05 | chat | Stores chat sessions and their metadata |
| 06 | chatidtag | Maps relationships between chats and their associated tags |
| 07 | config | Maintains system-wide configuration settings |
| 08 | document | Stores documents and their metadata for knowledge management |
| 09 | feedback | Captures user feedback and ratings |
| 10 | file | Manages uploaded files and their metadata |
| 11 | folder | Organizes files and content into hierarchical structures |
| 12 | function | Stores custom functions and their configurations |
| 13 | group | Manages user groups and their permissions |
| 14 | group_member | Tracks user membership within groups |
| 15 | knowledge | Stores knowledge base entries and related information |
| 16 | knowledge_file | Links files to knowledge bases |
| 17 | memory | Maintains chat history and context memory |
| 18 | message | Stores individual chat messages and their content |
| 19 | message_reaction | Records user reactions (emojis/responses) to messages |
| 20 | migrate_history | Tracks database schema version and migration records |
| 21 | model | Manages AI model configurations and settings |
| 22 | note | Stores user-created notes and annotations |
| 23 | oauth_session | Manages active OAuth sessions for users |
| 24 | prompt | Stores templates and configurations for AI prompts |
| 25 | tag | Manages tags/labels for content categorization |
| 26 | tool | Stores configurations for system tools and integrations |
| 27 | user | Maintains user profiles and account information |
Note: there are two additional tables in Open-WebUI's SQLite database that are not related to Open-WebUI's core functionality, that have been excluded:
@@ -129,6 +132,24 @@ Things to know about the auth table:
| user_id | TEXT | NOT NULL | Reference to the user |
| created_at | BIGINT | - | Timestamp when membership was created |
## Channel File Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
| --------------- | ------------- | ---------------------------------- | --------------------------------- |
| id | Text | PRIMARY KEY | Unique identifier (UUID) |
| user_id | Text | NOT NULL | Owner of the relationship |
| channel_id | Text | FOREIGN KEY(channel.id), NOT NULL | Reference to the channel |
| file_id | Text | FOREIGN KEY(file.id), NOT NULL | Reference to the file |
| message_id | Text | FOREIGN KEY(message.id), nullable | Reference to associated message |
| created_at | BigInteger | NOT NULL | Creation timestamp |
| updated_at | BigInteger | NOT NULL | Last update timestamp |
Things to know about the channel_file table:
- Unique constraint on (`channel_id`, `file_id`) to prevent duplicate entries
- Foreign key relationships with CASCADE delete
- Indexed on `channel_id`, `file_id`, and `user_id` for performance
## Chat Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
@@ -258,10 +279,26 @@ Things to know about the function table:
| data | JSON | nullable | Additional group data |
| meta | JSON | nullable | Group metadata |
| permissions | JSON | nullable | Permission configuration |
| user_ids | JSON | nullable | List of member user IDs |
| created_at | BigInteger | - | Creation timestamp |
| updated_at | BigInteger | - | Last update timestamp |
Note: The `user_ids` column has been migrated to the `group_member` table.
## Group Member Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
| --------------- | ------------- | -------------------------------- | --------------------------------- |
| id | Text | PRIMARY KEY, UNIQUE | Unique identifier (UUID) |
| group_id | Text | FOREIGN KEY(group.id), NOT NULL | Reference to the group |
| user_id | Text | FOREIGN KEY(user.id), NOT NULL | Reference to the user |
| created_at | BigInteger | nullable | Creation timestamp |
| updated_at | BigInteger | nullable | Last update timestamp |
Things to know about the group_member table:
- Unique constraint on (`group_id`, `user_id`) to prevent duplicate memberships
- Foreign key relationships with CASCADE delete to group and user tables
## Knowledge Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
@@ -276,6 +313,23 @@ Things to know about the function table:
| created_at | BigInteger | - | Creation timestamp |
| updated_at | BigInteger | - | Last update timestamp |
## Knowledge File Table
| **Column Name** | **Data Type** | **Constraints** | **Description** |
| --------------- | ------------- | ------------------------------------ | --------------------------------- |
| id | Text | PRIMARY KEY | Unique identifier (UUID) |
| user_id | Text | NOT NULL | Owner of the relationship |
| knowledge_id | Text | FOREIGN KEY(knowledge.id), NOT NULL | Reference to the knowledge base |
| file_id | Text | FOREIGN KEY(file.id), NOT NULL | Reference to the file |
| created_at | BigInteger | NOT NULL | Creation timestamp |
| updated_at | BigInteger | NOT NULL | Last update timestamp |
Things to know about the knowledge_file table:
- Unique constraint on (`knowledge_id`, `file_id`) to prevent duplicate entries
- Foreign key relationships with CASCADE delete
- Indexed on `knowledge_id`, `file_id`, and `user_id` for performance
The `access_control` fields expected structure:
```python
@@ -644,3 +698,57 @@ erDiagram
json access_control
}
```
---
## Database Encryption with SQLCipher
For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed.
### Prerequisites
SQLCipher encryption requires additional dependencies that are **not included by default**. Before using this feature, you must install:
- The **SQLCipher system library** (e.g., `libsqlcipher-dev` on Debian/Ubuntu, `sqlcipher` on macOS via Homebrew)
- The **`sqlcipher3-wheels`** Python package (`pip install sqlcipher3-wheels`)
For Docker users, this means building a custom image with these dependencies included.
### Configuration
To enable encryption, set the following environment variables:
```bash
# Required: Set the database type to use SQLCipher
DATABASE_TYPE=sqlite+sqlcipher
# Required: Set a secure password for database encryption
DATABASE_PASSWORD=your-secure-password
```
When these are set and a full `DATABASE_URL` is **not** explicitly defined, Open WebUI will automatically create and use an encrypted database file at `./data/webui.db`.
### Important Notes
:::danger
- The **`DATABASE_PASSWORD`** environment variable is **required** when using `sqlite+sqlcipher`.
- The **`DATABASE_TYPE`** variable tells Open WebUI which connection logic to use. Setting it to `sqlite+sqlcipher` activates the encryption feature.
- **Keep the password secure**, as it is needed to decrypt and access all application data.
- **Losing the password means losing access to all data** in the encrypted database.
:::
### Related Database Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_TYPE` | `None` | Set to `sqlite+sqlcipher` for encrypted SQLite |
| `DATABASE_PASSWORD` | - | Encryption password (required for SQLCipher) |
| `DATABASE_ENABLE_SQLITE_WAL` | `False` | Enable Write-Ahead Logging for better performance |
| `DATABASE_POOL_SIZE` | `None` | Database connection pool size |
| `DATABASE_POOL_TIMEOUT` | `30` | Pool connection timeout in seconds |
| `DATABASE_POOL_RECYCLE` | `3600` | Pool connection recycle time in seconds |
For more details, see the [Environment Variable Configuration](/getting-started/env-configuration) documentation.