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

Merge pull request #821 from open-webui/dev

Browse Source 
0.6.37
This commit is contained in:
Tim Baek
2025-11-23 23:12:04 -05:00
committed by GitHub
parent e6e00efc8e bd20fa2b69
commit a8b88bce34
14 changed files with 989 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/tutorials/https/nginx.md
View File

@@ -19,6 +19,14 @@ This guide provides three methods to set up HTTPS:
- **Let's Encrypt**: Perfect for production environments requiring trusted SSL certificates, using docker.
- **Windows+Self-Signed**: Simplified instructions for development and internal use on windows, no docker required.
:::danger Critical: Configure CORS for WebSocket Connections
A very common and difficult-to-debug issue with WebSocket connections is a misconfigured Cross-Origin Resource Sharing (CORS) policy. When running Open WebUI behind a reverse proxy like Nginx Proxy Manager, you **must** set the `CORS_ALLOW_ORIGIN` environment variable in your Open WebUI configuration.
Failure to do so will cause WebSocket connections to fail, even if you have enabled "Websockets support" in Nginx Proxy Manager.
:::
Choose the method that best fits your deployment needs.
import Tabs from '@theme/Tabs';

50
docs/tutorials/integrations/onedrive-sharepoint.mdx
View File

@@ -5,7 +5,7 @@ title: "Integrate with OneDrive & SharePoint"
:::info
This tutorial provides a step-by-step guide for integrating Open WebUI with **Microsoft OneDrive for Business & SharePoint**, as well as the separate, optional integration for **Personal Microsoft OneDrive** accounts. You can enable one or both integrations. This documentation is up to date as of Open WebUI v0.6.32.
This tutorial provides a step-by-step guide for integrating Open WebUI with **Microsoft OneDrive for Business & SharePoint**, as well as the separate, optional integration for **Personal Microsoft OneDrive** accounts. You can enable one or both integrations. This documentation is up to date as of Open WebUI v0.6.37.
:::
@@ -84,7 +84,6 @@ From the **Overview** page of the App Registration you just created, copy the fo
Set the following environment variables in your Open WebUI deployment to enable the work/school integration:
```bash
# Enable the OneDrive integration feature globally
ENABLE_ONEDRIVE_INTEGRATION=true
@@ -100,6 +99,12 @@ ONEDRIVE_SHAREPOINT_TENANT_ID="yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
ONEDRIVE_SHAREPOINT_URL="https://your-tenant-name.sharepoint.com"
```
:::info
After setting these variables and restarting Open WebUI, you must also enable the OneDrive toggle in the admin panel. See the Final Step section below for details.
:::
---
# Integration for Personal OneDrive (Optional)
@@ -133,9 +138,25 @@ ONEDRIVE_CLIENT_ID_PERSONAL="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
---
## Final Step: Browser Configuration and Verification
## Final Step: Enable OneDrive Integration in Admin Settings
After setting your environment variables and restarting your Open WebUI instance, verify the integration.
After setting your environment variables and restarting your Open WebUI instance, you must explicitly enable the feature in the admin panel. **The environment variables alone do not activate the integration.**
1. Navigate to **Settings → Admin → Documents**.
2. Toggle on the **"OneDrive"** switch.
3. Refresh your browser or log out and log back in.
:::warning
Admin Toggle is Required
This step is mandatory even though you've set `ENABLE_ONEDRIVE_INTEGRATION=true` in your environment. Some configuration options in Open WebUI are persistent database settings that are initialized on first startup but must be activated through the admin interface.
:::
## Verifying the Integration
After enabling the admin toggle and refreshing, verify the integration is working:
1. In Open WebUI, open the attachment menu (+) in the chat input. You should see menu items for **"Microsoft OneDrive (work/school)"** and/or **"Microsoft OneDrive (personal)"**, depending on your configuration.
2. Clicking either option should trigger a pop-up window for Microsoft authentication.
@@ -143,8 +164,27 @@ After setting your environment variables and restarting your Open WebUI instance
:::caution
Disable Pop-up Blockers!
The OneDrive file picker and authentication flow happen in a pop-up window. If nothing happens when you click a OneDrive option, it is almost certainly because your browser is blocking pop-ups. **You must disable the pop-up blocker for your Open WebUI domain** for the integration to work.
The OneDrive file picker and authentication flow happen in a pop-up window. If nothing happens when you click a OneDrive option, your browser is almost certainly blocking pop-ups. **You must disable the pop-up blocker for your Open WebUI domain** for the integration to work. Note that some browsers (like Chrome) may have additional restrictions compared to others (like Edge).
:::
## Troubleshooting
**OneDrive option not appearing in the attachment menu:**
- Verify the admin toggle is enabled in Settings → Admin → Documents
- Refresh your browser after enabling the toggle
- Check that your environment variables are correctly set and the container has been restarted
**Files not loading or folders not clickable:**
- Log out of Open WebUI completely and log back in to refresh your authentication tokens
- Verify the Azure App Registration permissions are correctly configured and admin consent is granted
- Check browser console for any authentication errors
**Authentication pop-up not appearing:**
- Disable pop-up blockers for your Open WebUI domain
- Try a different browser (Edge tends to work more reliably than Chrome for Microsoft authentication flows)
---
You have now successfully configured OneDrive integration, providing seamless file access for your users.

45
docs/tutorials/offline-mode.mdx
View File

@@ -25,9 +25,10 @@ The offline mode of Open WebUI lets you run the application without the need for
**Disabled functionality when offline mode is enabled:**
- Automatic version update checks
- Downloads of embedding models from Hugging Face Hub
- If you did not download an embedding model prior to activating `OFFLINE_MODE` any RAG, web search and document analysis functionality may not work properly
- Automatic version update checks (controlled by `ENABLE_VERSION_UPDATE_CHECK`)
- Downloads of embedding models from Hugging Face Hub (controlled by `HF_HUB_OFFLINE`)
- If you did not download an embedding model prior to activating offline mode, RAG, web search and document analysis functionality will not work properly
- Automatic model updates for embeddings, reranking, and Whisper models
- Update notifications in the UI
**Still functional:**
@@ -40,8 +41,31 @@ The offline mode of Open WebUI lets you run the application without the need for
## How to enable offline mode?
The offline mode has to be enabled via the [environment variable](https://docs.openwebui.com/getting-started/env-configuration#offline_mode) `OFFLINE_MODE`.
Apply the environment variable depending on your way of deploying Open WebUI.
Offline mode requires setting multiple environment variables to fully disconnect Open WebUI from external network dependencies. The primary variables are:
**Required Environment Variables:**
- `OFFLINE_MODE=true` - Disables version checks and prevents automatic model downloads
- `HF_HUB_OFFLINE=1` - Tells Hugging Face Hub to operate in offline mode, preventing all automatic downloads
**Optional but Recommended:**
- `RAG_EMBEDDING_MODEL_AUTO_UPDATE=false` - Prevents automatic updates of embedding models
- `RAG_RERANKING_MODEL_AUTO_UPDATE=false` - Prevents automatic updates of reranking models
- `WHISPER_MODEL_AUTO_UPDATE=false` - Prevents automatic updates of Whisper models
Apply these environment variables depending on your deployment method.
:::warning Critical: HF_HUB_OFFLINE Behavior
When `HF_HUB_OFFLINE=1` is set:
- **Downloads of models, sentence transformers, and other Hugging Face content will NOT WORK**
- RAG will not work on a default installation if this is enabled without pre-downloading models
- Only pre-downloaded models in the correct cache directories will be accessible
This variable provides the strictest offline enforcement but requires careful preparation.
:::
:::tip
@@ -113,7 +137,16 @@ services:
image: ghcr.io/open-webui/open-webui:main
restart: unless-stopped
environment:
- OFFLINE_MODE=True
# Core offline mode settings
- OFFLINE_MODE=true
- HF_HUB_OFFLINE=1
# Disable automatic model updates
- RAG_EMBEDDING_MODEL_AUTO_UPDATE=false
- RAG_RERANKING_MODEL_AUTO_UPDATE=false
- WHISPER_MODEL_AUTO_UPDATE=false
# Specify pre-downloaded models
- RAG_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
- WHISPER_MODEL=Systran/faster-whisper-large-v3
volumes:

48
docs/tutorials/tab-nginx/LetsEncrypt.md
View File

@@ -162,6 +162,16 @@ Now we'll run a script that uses Docker to fetch the certificate.
-----
### Important: Caching Configuration
When using NGINX with Open WebUI, proper caching is crucial for performance while ensuring authentication remains secure. The configuration below includes:
- **Cached**: Static assets (CSS, JS, fonts, images) for better performance
- **Not Cached**: Authentication endpoints, API calls, SSO/OAuth callbacks, and session data
- **Result**: Faster page loads without breaking login functionality
The configuration below implements these rules automatically.
### Step 3: Finalize Nginx Configuration for HTTPS
With the certificate saved in your `ssl` directory, you can now update the Nginx configuration to enable HTTPS.
@@ -190,22 +200,52 @@ With the certificate saved in your `ssl` directory, you can now update the Nginx
}
}
# Main HTTPS server block
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name <YOUR_DOMAIN_NAME>;
# SSL certificate paths
ssl_certificate /etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/privkey.pem;
# Security enhancements
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES128-GCM-SHA256';
ssl_prefer_server_ciphers off;
location ~* ^/(auth|api|oauth|admin|signin|signup|signout|login|logout|sso)/ {
proxy_pass http://open-webui:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 10m;
proxy_buffering off;
client_max_body_size 20M;
proxy_no_cache 1;
proxy_cache_bypass 1;
add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
add_header Pragma "no-cache" always;
expires -1;
}
location ~* \.(css|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot)$ {
proxy_pass http://open-webui:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Cache static assets for 7 days
expires 7d;
add_header Cache-Control "public, immutable";
}
location / {
proxy_pass http://open-webui:8080;
proxy_http_version 1.1;
@@ -218,6 +258,8 @@ With the certificate saved in your `ssl` directory, you can now update the Nginx
proxy_read_timeout 10m;
proxy_buffering off;
client_max_body_size 20M;
add_header Cache-Control "public, max-age=300, must-revalidate";
}
}
```

14
docs/tutorials/tab-nginx/NginxProxyManager.md
View File

@@ -77,6 +77,20 @@ A very common and difficult-to-debug issue with WebSocket connections is a misco
Failure to do so will cause WebSocket connections to fail, even if you have enabled "Websockets support" in Nginx Proxy Manager.
:::
:::tip Caching Best Practice
While Nginx Proxy Manager handles most configuration automatically, be aware that:
- **Static assets** (CSS, JS, images) are cached by default for better performance
- **Authentication endpoints** should never be cached
- If you add custom caching rules in NPM's "Advanced" tab, ensure you exclude paths like `/api/`, `/auth/`, `/signup/` , `/signin/`, `/sso/`, `/admin/`, `/signout/`, `/oauth/`, `/login/`, and `/logout/`
The default NPM configuration handles this correctly - only modify caching if you know what you're doing.
:::
**Example:**
If you access your UI at `https://openwebui.hello.duckdns.org`, you must set:

41
docs/tutorials/tab-nginx/SelfSigned.md
View File

@@ -23,10 +23,9 @@ Using self-signed certificates is suitable for development or internal use where
ssl_certificate_key /etc/nginx/ssl/nginx.key;
ssl_protocols TLSv1.2 TLSv1.3;
location / {
location ~* ^/(auth|api|oauth|admin|signin|signup|signout|login|logout|sso)/ {
proxy_pass http://host.docker.internal:3000;
# Add WebSocket support (Necessary for version 0.5.0 and up)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
@@ -36,12 +35,44 @@ Using self-signed certificates is suitable for development or internal use where
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# (Optional) Disable proxy buffering for better streaming response from models
proxy_buffering off;
# (Optional) Increase max request size for large attachments and long audio messages
client_max_body_size 20M;
proxy_read_timeout 10m;
# Disable caching for auth endpoints
proxy_no_cache 1;
proxy_cache_bypass 1;
add_header Cache-Control "no-store, no-cache, must-revalidate" always;
expires -1;
}
location ~* \.(css|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot)$ {
proxy_pass http://host.docker.internal:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
expires 7d;
add_header Cache-Control "public, immutable";
}
location / {
proxy_pass http://host.docker.internal:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
client_max_body_size 20M;
proxy_read_timeout 10m;
add_header Cache-Control "public, max-age=300, must-revalidate";
}
}
```

59
docs/tutorials/tab-nginx/Windows.md
View File

@@ -75,27 +75,14 @@ http {
include mime.types;
default_type application/octet-stream;
#log_format main '$remote_addr - $remote_user [$time_local] "$request" '
# '$status $body_bytes_sent "$http_referer" '
# '"$http_user_agent" "$http_x_forwarded_for"';
#access_log logs/access.log main;
sendfile on;
#tcp_nopush on;
#keepalive_timeout 0;
keepalive_timeout 120;
#gzip on;
# needed to properly handle websockets (streaming)
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# Redirect all HTTP traffic to HTTPS
server {
listen 80;
server_name 192.168.1.15;
@@ -103,28 +90,19 @@ http {
return 301 https://$host$request_uri;
}
# Handle HTTPS traffic
server {
listen 443 ssl;
server_name 192.168.1.15;
# SSL Settings (ensure paths are correct)
ssl_certificate C:\\nginx\\nginx.crt;
ssl_certificate_key C:\\nginx\\nginx.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers on;
# OCSP Stapling
#ssl_stapling on;
#ssl_stapling_verify on;
# Proxy settings to your local service
location / {
# proxy_pass should point to your running localhost version of open-webui
location ~* ^/(auth|api|oauth|admin|signin|signup|signout|login|logout|sso)/ {
proxy_pass http://localhost:8080;
# Add WebSocket support (Necessary for version 0.5.0 and up)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
@@ -134,15 +112,42 @@ http {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# (Optional) Disable proxy buffering for better streaming response from models
proxy_buffering off;
# (Optional) Increase max request size for large attachments and long audio messages
client_max_body_size 20M;
proxy_read_timeout 10m;
add_header Cache-Control "no-store, no-cache, must-revalidate" always;
expires -1;
}
location ~* \.(css|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot)$ {
proxy_pass http://localhost:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
expires 7d;
add_header Cache-Control "public, immutable";
}
location / {
proxy_pass http://localhost:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
client_max_body_size 20M;
proxy_read_timeout 10m;
add_header Cache-Control "public, max-age=300, must-revalidate";
}
}
}
```