From 9fa6353bfb574f106dd3089adcf441cd83e9bdf9 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sun, 5 Oct 2025 22:54:06 +0200 Subject: [PATCH 01/16] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 25 ++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 27626d7c95..83c0edea7a 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -3028,6 +3028,31 @@ By default, OAuth configurations are stored in the database and managed via the address. This is considered unsafe as not all OAuth providers will verify email addresses and can lead to potential account takeovers. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `ENABLE_OAUTH_WITHOUT_EMAIL` +- Type: `bool` +- Default: `False` +- Description: Enables authentication with OpenID Connect (OIDC) providers that do not support or expose an email scope. When enabled, Open WebUI will create and manage user accounts without requiring an email address from the OAuth provider. +- Persistence: This environment variable is a `PersistentConfig` variable. + +:::warning +**Use with Caution** + +Enabling this option bypasses email-based user identification, which is the standard method for uniquely identifying users across authentication systems. When enabled: + +- User accounts will be created using the `sub` claim (or the claim specified in `OAUTH_SUB_CLAIM`) as the primary identifier +- Email-based features such as password recovery, email notifications, and account merging via `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` will not function properly +- Ensure your OIDC provider's `sub` claim is stable and unique to prevent authentication conflicts + +Only enable this if your identity provider does not support email scope and you have alternative user identification mechanisms in place. + +This setting is designed for enterprise environments using identity providers that: +- Use employee IDs, usernames, or other non-email identifiers as the primary user claim +- Have privacy policies that prevent sharing email addresses via OAuth +- Operate in air-gapped or highly restricted networks where email-based services are unavailable + +For most standard OAuth providers (Google, Microsoft, GitHub, etc.), this setting should remain `False`. +::: + #### `OAUTH_UPDATE_PICTURE_ON_LOGIN` - Type: `bool` From 2952ca2472a9ae594d47cd4da398ca9e328e329b Mon Sep 17 00:00:00 2001 From: silentoplayz Date: Sun, 5 Oct 2025 23:29:50 -0400 Subject: [PATCH 02/16] chore: format --- .../conversation-organization.md | 8 +- .../document-extraction/apachetika.md | 2 +- docs/features/document-extraction/docling.md | 3 +- docs/features/document-extraction/index.md | 3 +- .../document-extraction/mistral-ocr.md | 1 - docs/features/rag.md | 1 + docs/features/workspace/groups.md | 1 + docs/features/workspace/permissions.md | 29 +++--- docs/features/workspace/prompts.md | 56 ++++++----- docs/features/workspace/roles.md | 5 +- .../advanced-topics/development.md | 4 +- docs/getting-started/api-endpoints.md | 1 + docs/getting-started/index.md | 2 - .../quick-start/tab-docker/ManualDocker.md | 1 - .../quick-start/tab-docker/Podman.md | 1 - .../quick-start/tab-docker/PodmanKubePlay.md | 2 +- .../quick-start/tab-python/Uv.md | 6 +- docs/tutorials/https-caddy.md | 2 - docs/tutorials/https-haproxy.md | 25 +++-- docs/tutorials/https-nginx.md | 2 - docs/tutorials/images.md | 4 +- docs/tutorials/integrations/amazon-bedrock.md | 5 +- .../backend-controlled-ui-compatible-flow.md | 17 ++++ .../integrations/deepseekr1-dynamic.md | 14 ++- .../tutorials/integrations/firefox-sidebar.md | 6 +- docs/tutorials/integrations/helicone.md | 1 - .../tutorials/integrations/libre-translate.md | 1 + docs/tutorials/integrations/okta-oidc-sso.md | 94 +++++++++---------- docs/tutorials/jupyter.md | 1 - docs/tutorials/maintenance/backups.md | 27 +++--- .../tutorials/speech-to-text/env-variables.md | 1 - docs/tutorials/speech-to-text/stt-config.md | 5 +- docs/tutorials/tab-nginx/NginxProxyManager.md | 47 ++++++---- docs/tutorials/tab-nginx/SelfSigned.md | 1 - docs/tutorials/tab-nginx/Windows.md | 6 +- .../chatterbox-tts-api-integration.md | 13 +-- .../openai-edge-tts-integration.md | 7 +- .../tips/improve-performance-local.md | 3 + docs/tutorials/web-search/external.md | 48 +++++----- docs/tutorials/web-search/tavily.md | 2 + 40 files changed, 252 insertions(+), 206 deletions(-) diff --git a/docs/features/chat-features/conversation-organization.md b/docs/features/chat-features/conversation-organization.md index 3b2d88d06d..20046b6c64 100644 --- a/docs/features/chat-features/conversation-organization.md +++ b/docs/features/chat-features/conversation-organization.md @@ -35,10 +35,10 @@ You can give each folder a unique personality and context. By hovering over a fo :::tip **Creating a 'Python Expert' Project** Imagine you are working on a Python project. You can create a folder called "Python Expert". -1. **Edit the folder** and set the System Prompt to something like: `You are an expert Python developer. You provide clean, efficient, and well-documented code. When asked for code, you prioritize clarity and adherence to PEP 8 standards.` -2. **Attach Knowledge** by linking a knowledge base which contains a PDF of your project's technical specification, or a specific library's documentation. -3. **Activate/Select the folder** by clicking on it. -4. Now, any new chat you start will automatically have this expert persona, the context of your documents and is saved within the folder, ensuring you get highly relevant and specialized assistance for your project. +1. **Edit the folder** and set the System Prompt to something like: `You are an expert Python developer. You provide clean, efficient, and well-documented code. When asked for code, you prioritize clarity and adherence to PEP 8 standards.` +2. **Attach Knowledge** by linking a knowledge base which contains a PDF of your project's technical specification, or a specific library's documentation. +3. **Activate/Select the folder** by clicking on it. +4. Now, any new chat you start will automatically have this expert persona, the context of your documents and is saved within the folder, ensuring you get highly relevant and specialized assistance for your project. ::: ## Tagging Conversations diff --git a/docs/features/document-extraction/apachetika.md b/docs/features/document-extraction/apachetika.md index 59ccdd6e31..c5428e34b2 100644 --- a/docs/features/document-extraction/apachetika.md +++ b/docs/features/document-extraction/apachetika.md @@ -70,7 +70,7 @@ To use Apache Tika as the context extraction engine in Open WebUI, follow these * Update the context extraction engine URL to `http://tika:9998`. * Save the changes. - Verifying Apache Tika in Docker +Verifying Apache Tika in Docker ===================================== To verify that Apache Tika is working correctly in a Docker environment, you can follow these steps: diff --git a/docs/features/document-extraction/docling.md b/docs/features/document-extraction/docling.md index 01f06f6618..7d8dc84913 100644 --- a/docs/features/document-extraction/docling.md +++ b/docs/features/document-extraction/docling.md @@ -28,6 +28,7 @@ docker run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=true quay.io/docling-project/ ``` *With GPU support: + ```bash docker run --gpus all -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=true quay.io/docling-project/docling-serve-cu124 ``` @@ -52,7 +53,7 @@ docker run --gpus all -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=true quay.io/docli * fill in an **object value** as described at https://github.com/docling-project/docling-serve/blob/main/docs/usage.md#picture-description-options * Save the changes. - #### Make sure the object value is a valid JSON! Working examples below: + #### Make sure the object value is a valid JSON! Working examples below ![image](https://github.com/user-attachments/assets/f6524949-fb47-4686-9c81-6ab8fdda6db1) diff --git a/docs/features/document-extraction/index.md b/docs/features/document-extraction/index.md index 9d0184c873..6661d16cf5 100644 --- a/docs/features/document-extraction/index.md +++ b/docs/features/document-extraction/index.md @@ -10,12 +10,14 @@ Open WebUI provides powerful document extraction capabilities that allow you to ## What is Document Extraction? Document extraction refers to the process of automatically identifying and extracting text and data from various file formats, including: + - PDFs (both text-based and scanned) - Images containing text - Handwritten documents - And more With proper document extraction, Open WebUI can help you: + - Convert image-based documents to searchable text - Preserve document structure and layout information - Extract data in structured formats for further processing @@ -26,4 +28,3 @@ With proper document extraction, Open WebUI can help you: Open WebUI supports multiple document extraction engines to accommodate different needs and document types. Each extraction method has its own strengths and is suitable for different scenarios. Explore the documentation for each available extraction method to learn how to set it up and use it effectively with your Open WebUI instance. - diff --git a/docs/features/document-extraction/mistral-ocr.md b/docs/features/document-extraction/mistral-ocr.md index 237c6196e7..493b1057fd 100644 --- a/docs/features/document-extraction/mistral-ocr.md +++ b/docs/features/document-extraction/mistral-ocr.md @@ -46,7 +46,6 @@ Verifying Mistral OCR To verify that Mistral OCR is working correctly in script, please refer to `https://docs.mistral.ai/capabilities/document/` - ### Conclusion Integrating Mistral OCR with Open WebUI is a simple and effective way to enhance document processing and content extraction capabilities. By following the steps in this guide, you can set up Mistral OCR as the default extraction engine and leverage its advanced text recognition features. Once configured, Mistral OCR enables powerful, multilingual document parsing with support for various formats, enhancing AI-driven document analysis capabilities in Open WebUI. diff --git a/docs/features/rag.md b/docs/features/rag.md index 84dee140ab..07ed494ae3 100644 --- a/docs/features/rag.md +++ b/docs/features/rag.md @@ -61,6 +61,7 @@ A variety of parsers extract content from local and remote documents. For more, When paired with a Google Cloud project that has the Google Picker API and Google Drive API enabled, this feature allows users to directly access their Drive files from the chat interface and upload documents, slides, sheets and more and uploads them as context to your chat. Can be enabled `Admin Panel` > `Settings` > `Documents` menu. Must set [`GOOGLE_DRIVE_API_KEY and GOOGLE_DRIVE_CLIENT_ID`](https://github.com/open-webui/docs/blob/main/docs/getting-started/env-configuration.md) environment variables to use. ### Detailed Instructions + 1. Create an OAuth 2.0 client and configure both the Authorized JavaScript origins & Authorized redirect URI to be the URL (include the port if any) you use to access your Open-WebUI instance. 1. Make a note of the Client ID associated with that OAuth client. 1. Make sure that you enable both Google Drive API and Google Picker API for your project. diff --git a/docs/features/workspace/groups.md b/docs/features/workspace/groups.md index 5859a90a53..836fc49c8e 100644 --- a/docs/features/workspace/groups.md +++ b/docs/features/workspace/groups.md @@ -4,6 +4,7 @@ title: "🔐 Groups" --- Groups allow administrators to + * assign permissions to multiple users at once, simplifying access management * limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to specific groups * Specify access to a resource for a group to either "read" or "write" (write access implies read) diff --git a/docs/features/workspace/permissions.md b/docs/features/workspace/permissions.md index c0c405af47..a35abc9ce3 100644 --- a/docs/features/workspace/permissions.md +++ b/docs/features/workspace/permissions.md @@ -44,23 +44,26 @@ Features permissions control access to specialized capabilities within Open WebU By default, Open WebUI applies the following permission settings: **Workspace Permissions**: -- Models Access: Disabled (`USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS=False`) -- Knowledge Access: Disabled (`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS=False`) -- Prompts Access: Disabled (`USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS=False`) -- Tools Access: Disabled (`USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS=False`) + +* Models Access: Disabled (`USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS=False`) +* Knowledge Access: Disabled (`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS=False`) +* Prompts Access: Disabled (`USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS=False`) +* Tools Access: Disabled (`USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS=False`) **Chat Permissions**: -- Allow Chat Controls: Enabled -- Allow File Upload: Enabled (`USER_PERMISSIONS_CHAT_FILE_UPLOAD=True`) -- Allow Chat Delete: Enabled (`USER_PERMISSIONS_CHAT_DELETE=True`) -- Allow Chat Edit: Enabled (`USER_PERMISSIONS_CHAT_EDIT=True`) -- Allow Temporary Chat: Enabled (`USER_PERMISSIONS_CHAT_TEMPORARY=True`) + +* Allow Chat Controls: Enabled +* Allow File Upload: Enabled (`USER_PERMISSIONS_CHAT_FILE_UPLOAD=True`) +* Allow Chat Delete: Enabled (`USER_PERMISSIONS_CHAT_DELETE=True`) +* Allow Chat Edit: Enabled (`USER_PERMISSIONS_CHAT_EDIT=True`) +* Allow Temporary Chat: Enabled (`USER_PERMISSIONS_CHAT_TEMPORARY=True`) **Features Permissions**: -- Web Search: Enabled (`ENABLE_RAG_WEB_SEARCH=True`) -- Image Generation: Enabled (`ENABLE_IMAGE_GENERATION=True`) -- Code Interpreter: Enabled (`USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`) -- Direct Tool Servers: Disabled (`USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS=False`) + +* Web Search: Enabled (`ENABLE_RAG_WEB_SEARCH=True`) +* Image Generation: Enabled (`ENABLE_IMAGE_GENERATION=True`) +* Code Interpreter: Enabled (`USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`) +* Direct Tool Servers: Disabled (`USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS=False`) Administrators can change the default permissions in the user interface under "users" in the admin panel. diff --git a/docs/features/workspace/prompts.md b/docs/features/workspace/prompts.md index c74c056a33..d21e8147ad 100644 --- a/docs/features/workspace/prompts.md +++ b/docs/features/workspace/prompts.md @@ -61,23 +61,23 @@ By leveraging custom input variables, you can move beyond static text and build **How It Works** -1. **Create a prompt** with one or more custom variables using the syntax below. -2. **Use the prompt's slash command** in the chat input. -3. An **"Input Variables" popup window** will appear with a form field for each variable you defined. -4. **Fill out the form** and click `Save`. Note that by default, all fields are optional unless explicitly marked as required. -5. The variables in your prompt will be replaced with your input, and the final prompt will be sent to the model. +1. **Create a prompt** with one or more custom variables using the syntax below. +2. **Use the prompt's slash command** in the chat input. +3. An **"Input Variables" popup window** will appear with a form field for each variable you defined. +4. **Fill out the form** and click `Save`. Note that by default, all fields are optional unless explicitly marked as required. +5. The variables in your prompt will be replaced with your input, and the final prompt will be sent to the model. **Syntax** There are two ways to define a custom variable: -1. **Simple Input**: `{{variable_name}}` - * This creates a standard, single-line `text` type input field in the popup window. - * The field will be optional by default. +1. **Simple Input**: `{{variable_name}}` + * This creates a standard, single-line `text` type input field in the popup window. + * The field will be optional by default. -2. **Typed Input**: `{{variable_name | [type][:property="value"]}}` - * This allows you to specify the type of input field (e.g., a dropdown, a date picker) and configure its properties. - * The field will be optional by default unless you add the `:required` flag. +2. **Typed Input**: `{{variable_name | [type][:property="value"]}}` + * This allows you to specify the type of input field (e.g., a dropdown, a date picker) and configure its properties. + * The field will be optional by default unless you add the `:required` flag. **Required vs Optional Variables** @@ -91,9 +91,10 @@ To make a variable **required** (mandatory), add the `:required` flag: ``` When a field is marked as required: -- The form will display a visual indicator (asterisk) next to the field label -- Users cannot submit the form without providing a value -- Browser validation will prevent form submission if required fields are empty + +* The form will display a visual indicator (asterisk) next to the field label +* Users cannot submit the form without providing a value +* Browser validation will prevent form submission if required fields are empty **Input Types Overview** @@ -123,8 +124,9 @@ You can specify different input types to build rich, user-friendly forms. Here i Create a reusable prompt where the article content is required but additional parameters are optional. -* **Command:** `/summarize_article` -* **Prompt Content:** +* **Command:** `/summarize_article` +* **Prompt Content:** + ``` Please summarize the following article. {{article_text | textarea:placeholder="Paste the full text of the article here...":required}} @@ -134,14 +136,16 @@ Create a reusable prompt where the article content is required but additional pa {{include_quotes | checkbox}} Include key quotes from the article ``` + When you type `/summarize_article`, a modal will appear with a required text area for the article, and optional fields for customizing the summary style. **2. Advanced Bug Report Generator** This prompt ensures critical information is captured while allowing optional details. -* **Command:** `/bug_report` -* **Prompt Content:** +* **Command:** `/bug_report` +* **Prompt Content:** + ``` Generate a bug report with the following details: @@ -155,14 +159,16 @@ This prompt ensures critical information is captured while allowing optional det Please format this into a clear and complete bug report document. ``` + This creates a form where title, priority, and steps are mandatory, but additional context and workarounds are optional. **3. Social Media Post Generator with Smart Defaults** This prompt generates tailored content with required core information and optional customizations. -* **Command:** `/social_post` -* **Prompt Content:** +* **Command:** `/social_post` +* **Prompt Content:** + ``` Generate a social media post for {{platform | select:options=["LinkedIn","Twitter","Facebook","Instagram"]:required}}. @@ -180,8 +186,9 @@ This prompt generates tailored content with required core information and option Generate structured meeting minutes with required basics and optional details. -* **Command:** `/meeting_minutes` -* **Prompt Content:** +* **Command:** `/meeting_minutes` +* **Prompt Content:** + ``` # Meeting Minutes @@ -210,8 +217,9 @@ Generate structured meeting minutes with required basics and optional details. A flexible template for reviewing various types of content. -* **Command:** `/content_review` -* **Prompt Content:** +* **Command:** `/content_review` +* **Prompt Content:** + ``` Please review the following {{content_type | select:options=["Blog Post","Marketing Copy","Documentation","Email","Presentation"]:required}}: diff --git a/docs/features/workspace/roles.md b/docs/features/workspace/roles.md index 1b508f448a..bea8c1262c 100644 --- a/docs/features/workspace/roles.md +++ b/docs/features/workspace/roles.md @@ -8,7 +8,7 @@ Open WebUI implements a structured role-based access control system with three p | **Role** | **Description** | **Default Creation** | |---------------|---------------------------------------------------|----------------------------------| | Administrator | System administrator with full control | First user account | -| Regular User | Standard user with limited permissions | Subsequent approved users | +| Regular User | Standard user with limited permissions | Subsequent approved users | | Pending | Unapproved user awaiting administrator activation | New registrations (configurable) | ### Role Assignment @@ -29,8 +29,9 @@ When set to "pending", new users must be manually approved by an administrator b ## User Groups Groups allow administrators to + * assign permissions to multiple users at once, simplifying access management -* limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to +* limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to specific groups * Group access to a resource can be set as "read" or "write" diff --git a/docs/getting-started/advanced-topics/development.md b/docs/getting-started/advanced-topics/development.md index ecd9c974ea..6fe6c279a3 100644 --- a/docs/getting-started/advanced-topics/development.md +++ b/docs/getting-started/advanced-topics/development.md @@ -74,7 +74,7 @@ Let's get the user interface (what you see in your browser) up and running first ```bash npm install --force ``` - + *Some setups need this to get around version issues.* 2. **Start the Frontend Development Server:** @@ -87,7 +87,6 @@ Let's get the user interface (what you see in your browser) up and running first 🎉 **Access the Frontend:** Open your web browser and go to [http://localhost:5173](http://localhost:5173). You should see a message indicating that Open WebUI's frontend is running and is waiting for the backend to be available. Don't worry about that message yet! Let's set up the backend next. **Keep this terminal running** – it's serving your frontend! - ### 2.5: Build the Frontend (Recommended) Once you’ve verified that the frontend development server (`npm run dev`) is running correctly and you can see Open WebUI at [http://localhost:5173](http://localhost:5173), it's a **good practice to also build the frontend assets**. This step simulates the production environment and can help catch build-time errors that don't show up during development. @@ -102,7 +101,6 @@ npm run build - If the build completes successfully (without errors), you're ready! If there are errors, address them before proceeding. - You don't need to do anything more with `build` for local development, but building ensures your code will not break in production or during deployment. - ### 3. Backend Setup (API and Server) We **require** you to use separate terminal instances for your frontend and backend processes. This keeps your workflows organized and makes it easier to manage each part of the application independently. diff --git a/docs/getting-started/api-endpoints.md b/docs/getting-started/api-endpoints.md index e9eb8bf830..8270fbcaa1 100644 --- a/docs/getting-started/api-endpoints.md +++ b/docs/getting-started/api-endpoints.md @@ -57,6 +57,7 @@ Access detailed API documentation for different services provided by Open WebUI: ``` - **Python Example**: + ```python import requests diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 7b55b3ba66..14c3411ad7 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -6,10 +6,8 @@ title: "🚀 Getting Started" import { TopBanners } from "@site/src/components/TopBanners"; - - Welcome to the **Open WebUI Documentation Hub!** Below is a list of essential guides and resources to help you get started, manage, and develop with Open WebUI. --- diff --git a/docs/getting-started/quick-start/tab-docker/ManualDocker.md b/docs/getting-started/quick-start/tab-docker/ManualDocker.md index 10a2e0bdf7..614068dc82 100644 --- a/docs/getting-started/quick-start/tab-docker/ManualDocker.md +++ b/docs/getting-started/quick-start/tab-docker/ManualDocker.md @@ -45,7 +45,6 @@ For Nvidia GPU support, add `--gpus all` to the `docker run` command: docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:cuda ``` - #### Single-User Mode (Disabling Login) To bypass the login page for a single-user setup, set the `WEBUI_AUTH` environment variable to `False`: diff --git a/docs/getting-started/quick-start/tab-docker/Podman.md b/docs/getting-started/quick-start/tab-docker/Podman.md index 8b3738bada..99395435df 100644 --- a/docs/getting-started/quick-start/tab-docker/Podman.md +++ b/docs/getting-started/quick-start/tab-docker/Podman.md @@ -31,5 +31,4 @@ If you are using Ollama from your computer (not running inside a container), Once inside open-webui, navigate to Settings > Admin Settings > Connections and create a new Ollama API connection to `http://10.0.2.2:[OLLAMA PORT]`. By default, the Ollama port is 11434. - Refer to the Podman [documentation](https://podman.io/) for advanced configurations. diff --git a/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md b/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md index 10e3a8ac5c..23ce1bde7b 100644 --- a/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md +++ b/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md @@ -66,4 +66,4 @@ For Nvidia GPU support, you need to replace the container image with `ghcr.io/op To successfully have the open-webui container access the GPU(s), you will need to have the Container Device Interface (CDI) for the GPU you wish to access installed in your Podman Machine. You can check [Podman GPU container access](https://podman-desktop.io/docs/podman/gpu). -::: \ No newline at end of file +::: diff --git a/docs/getting-started/quick-start/tab-python/Uv.md b/docs/getting-started/quick-start/tab-python/Uv.md index 6d237e04f4..1affdc74a1 100644 --- a/docs/getting-started/quick-start/tab-python/Uv.md +++ b/docs/getting-started/quick-start/tab-python/Uv.md @@ -1,4 +1,4 @@ -### Installation with `uv` +### Installation with `uv` The `uv` runtime manager ensures seamless Python environment management for applications like Open WebUI. Follow these steps to get started: @@ -7,11 +7,13 @@ The `uv` runtime manager ensures seamless Python environment management for appl Pick the appropriate installation command for your operating system: - **macOS/Linux**: + ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` - **Windows**: + ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` @@ -21,11 +23,13 @@ Pick the appropriate installation command for your operating system: Once `uv` is installed, running Open WebUI is a breeze. Use the command below, ensuring to set the `DATA_DIR` environment variable to avoid data loss. Example paths are provided for each platform: - **macOS/Linux**: + ```bash DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve ``` - **Windows** (PowerShell): + ```powershell $env:DATA_DIR="C:\open-webui\data"; uvx --python 3.11 open-webui@latest serve ``` diff --git a/docs/tutorials/https-caddy.md b/docs/tutorials/https-caddy.md index 1c5edc1d19..14aa80112a 100644 --- a/docs/tutorials/https-caddy.md +++ b/docs/tutorials/https-caddy.md @@ -15,7 +15,6 @@ This guide is simple walkthrough to set up a Ubuntu server with Caddy as a rever There's a few steps we'll follow to get everything set up: - - [HTTPS using Caddy](#https-using-caddy) - [Docker](#docker) - [Installing Docker](#installing-docker) @@ -72,7 +71,6 @@ services: restart: unless-stopped ``` - ## Caddy Caddy is a powerful web server that automatically manages TLS certificates for you, making it an excellent choice for serving Open WebUI over HTTPS. diff --git a/docs/tutorials/https-haproxy.md b/docs/tutorials/https-haproxy.md index d32c45fc39..89b3f88d94 100644 --- a/docs/tutorials/https-haproxy.md +++ b/docs/tutorials/https-haproxy.md @@ -14,16 +14,20 @@ HAProxy (High Availability Proxy) is specialized load-balancing and reverse prox ## Install HAProxy and Let's Encrypt First, install HAProxy and Let's Encrypt's certbot: + ### Redhat derivatives + ```sudo dnf install haproxy certbot openssl -y``` + ### Debian derivatives + ```sudo apt install haproxy certbot openssl -y``` ## HAProxy Configuration Basics HAProxy's configuration is by default stored in ```/etc/haproxy/haproxy.cfg```. This file contains all the configuration directives that determine how HAProxy will operate. -The base configuration for HAProxy to work with Open WebUI is pretty simple. +The base configuration for HAProxy to work with Open WebUI is pretty simple. ``` #--------------------------------------------------------------------- @@ -51,8 +55,8 @@ global user haproxy group haproxy daemon - - #adjust the dh-param if too low + + #adjust the dh-param if too low tune.ssl.default-dh-param 2048 #--------------------------------------------------------------------- # common defaults that all the 'listen' and 'backend' sections will @@ -78,16 +82,16 @@ defaults #http frontend web - #Non-SSL + #Non-SSL bind 0.0.0.0:80 - #SSL/TLS - bind 0.0.0.0:443 ssl crt /path/to/ssl/folder/ + #SSL/TLS + bind 0.0.0.0:443 ssl crt /path/to/ssl/folder/ #Let's Encrypt SSL acl letsencrypt-acl path_beg /.well-known/acme-challenge/ use_backend letsencrypt-backend if letsencrypt-acl - #Subdomain method + #Subdomain method acl chat-acl hdr(host) -i subdomain.domain.tld #Path Method acl chat-acl path_beg /owui/ @@ -103,7 +107,7 @@ backend owui_chat option forwardfor # add X-CLIENT-IP http-request add-header X-CLIENT-IP %[src] - http-request set-header X-Forwarded-Proto https if { ssl_fc } + http-request set-header X-Forwarded-Proto https if { ssl_fc } server chat :3000 ``` @@ -155,15 +159,16 @@ cat /etc/letsencrypt/live/{domain}/fullchain.pem /etc/letsencrypt/live/{domain}/ chmod 600 /etc/haproxy/certs/{domain}.pem chown haproxy:haproxy /etc/haproxy/certs/{domain}.pem ``` + You can then restart HAProxy to apply the new certificate: `systemctl restart haproxy` ## HAProxy Manager (Easy Deployment Option) -If you would like to have something manage your HAProxy configuration and Let's Encrypt SSLs automatically, I have written a simple python script and created a docker container you can use to create and manage your HAProxy config and manage the Let's Encrypt certificate lifecycle. +If you would like to have something manage your HAProxy configuration and Let's Encrypt SSLs automatically, I have written a simple python script and created a docker container you can use to create and manage your HAProxy config and manage the Let's Encrypt certificate lifecycle. https://github.com/shadowdao/haproxy-manager :::warning Please do not expose port 8000 publicly if you use the script or container! -::: \ No newline at end of file +::: diff --git a/docs/tutorials/https-nginx.md b/docs/tutorials/https-nginx.md index 97ee7dd1ad..89d86f5148 100644 --- a/docs/tutorials/https-nginx.md +++ b/docs/tutorials/https-nginx.md @@ -19,7 +19,6 @@ This guide provides three methods to set up HTTPS: Choose the method that best fits your deployment needs. - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -43,7 +42,6 @@ import Windows from './tab-nginx/Windows.md'; - ## Next Steps After setting up HTTPS, access Open WebUI securely at: diff --git a/docs/tutorials/images.md b/docs/tutorials/images.md index bd1fd3241d..0b34c66bd4 100644 --- a/docs/tutorials/images.md +++ b/docs/tutorials/images.md @@ -191,7 +191,7 @@ Open WebUI also supports image generation through the **Image Router APIs**. Ima ## Using Image Generation -#### Method 1: +#### Method 1 1. Toggle the `Image Generation` switch to on. 2. Enter your image generation prompt. @@ -199,7 +199,7 @@ Open WebUI also supports image generation through the **Image Router APIs**. Ima ![Image Generation Tutorial](/images/tutorial_image_generation_2.png) -#### Method 2: +#### Method 2 ![Image Generation Tutorial](/images/tutorial_image_generation.png) diff --git a/docs/tutorials/integrations/amazon-bedrock.md b/docs/tutorials/integrations/amazon-bedrock.md index 70ca1275e0..3209f29cb7 100644 --- a/docs/tutorials/integrations/amazon-bedrock.md +++ b/docs/tutorials/integrations/amazon-bedrock.md @@ -15,7 +15,6 @@ In this tutorial, we'll explore one of the most common and popular approaches to ## Prerequisites - In order to follow this tutorial, you must have the following: - An active AWS account @@ -23,7 +22,6 @@ In order to follow this tutorial, you must have the following: - IAM permissions in AWS to enable Bedrock models or already enabled models - Docker installed on your system - ## What is Amazon Bedrock Direct from AWS' website: @@ -42,14 +40,12 @@ AWS provides good documentation for request accessing / enabling these models he ![Amazon Bedrock Base Models](/images/tutorials/amazon-bedrock/amazon-bedrock-base-models.png) - ## Step 2: Configure the Bedrock Access Gateway Now that we have access to at least one Bedrock base model, we need to configure the Bedrock Access Gateway, or BAG. You can think of the BAG as kind of proxy or middleware developed by AWS that wraps around AWS native endpoints/SDK for Bedrock and, in turn, exposes endpoints that are compatible with OpenAI's schema, which is what Open-WebUI requires. For reference, here is a simple mapping between the endpoints: - | OpenAI Endpoint | Bedrock Method | |-----------------------|------------------------| | `/models` | list_inference_profiles | @@ -60,6 +56,7 @@ For reference, here is a simple mapping between the endpoints: The BAG repo can be found here: [Bedrock Access Gateway Repo](https://github.com/aws-samples/bedrock-access-gateway) To set-up the BAG, follow the below steps: + - Clone the BAG repo - Remove the default `dockerfile` - Change the name of the `Dockerfile_ecs` to `Dockerfile` diff --git a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md index ec2f4e4c89..fed91679fa 100644 --- a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md +++ b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md @@ -49,6 +49,7 @@ This enables server-side orchestration while still making replies show up in the The assistant message needs to be added to the chat response object in memory as a critical prerequisite before triggering the completion. This step is essential because the Open WebUI frontend expects assistant messages to exist in a specific structure. The assistant message must appear in both locations: + - `chat.messages[]` - The main message array - `chat.history.messages[]` - The indexed message history @@ -272,9 +273,11 @@ curl -X POST https:///api/chat/completions \ Assistant responses can be handled in two ways depending on your implementation needs: #### Option A: Stream Processing (Recommended) + If using `stream: true` in the completion request, you can process the streamed response in real-time and wait for the stream to complete. This is the approach used by the OpenWebUI web interface and provides immediate feedback. #### Option B: Polling Approach + For implementations that cannot handle streaming, poll the chat endpoint until the response is ready. Use a retry mechanism with exponential backoff: ```java @@ -419,6 +422,7 @@ echo "$cleaned_response" | jq '.' ``` This cleaning process handles: + - Removal of ````json` prefix - Removal of ```` suffix - Trimming whitespace @@ -797,24 +801,29 @@ This cleaning process handles: #### Required vs Optional Fields **Chat Creation - Required Fields:** + - `title` - Chat title (string) - `models` - Array of model names (string[]) - `messages` - Initial message array **Chat Creation - Optional Fields:** + - `files` - Knowledge files for RAG (defaults to empty array) - `tags` - Chat tags (defaults to empty array) - `params` - Model parameters (defaults to empty object) **Message Structure - User Message:** + - **Required:** `id`, `role`, `content`, `timestamp`, `models` - **Optional:** `parentId` (for threading) **Message Structure - Assistant Message:** + - **Required:** `id`, `role`, `content`, `parentId`, `modelName`, `modelIdx`, `timestamp` - **Optional:** Additional metadata fields **ChatCompletionsRequest - Required Fields:** + - `chat_id` - Target chat ID - `id` - Assistant message ID - `messages` - Array of ChatCompletionMessage @@ -822,6 +831,7 @@ This cleaning process handles: - `session_id` - Session identifier **ChatCompletionsRequest - Optional Fields:** + - `stream` - Enable streaming (defaults to false) - `background_tasks` - Control automatic tasks - `features` - Enable/disable features @@ -832,22 +842,27 @@ This cleaning process handles: #### Field Constraints **Timestamps:** + - Format: Unix timestamp in milliseconds - Example: `1720000000000` (July 4, 2024, 00:00:00 UTC) **UUIDs:** + - All ID fields should use valid UUID format - Example: `550e8400-e29b-41d4-a716-446655440000` **Model Names:** + - Must match available models in your Open WebUI instance - Common examples: `gpt-4o`, `gpt-3.5-turbo`, `claude-3-sonnet` **Session IDs:** + - Can be any unique string identifier - Recommendation: Use UUID format for consistency **Knowledge File Status:** + - Valid values: `"processed"`, `"processing"`, `"error"` - Only use `"processed"` files for completions @@ -878,6 +893,7 @@ Use the Open WebUI backend APIs to: 7. **Fetch the final chat** - Retrieve and parse the completed conversation **Enhanced Capabilities:** + - **RAG Integration** - Include knowledge collections for context-aware responses - **Asynchronous Processing** - Handle long-running AI operations with streaming or polling - **Response Parsing** - Clean and validate JSON responses from the assistant @@ -890,6 +906,7 @@ The key advantage of this approach is that it maintains full compatibility with ## Testing You can test your implementation by following the step-by-step CURL examples provided above. Make sure to replace placeholder values with your actual: + - Host URL - Authentication token - Chat IDs diff --git a/docs/tutorials/integrations/deepseekr1-dynamic.md b/docs/tutorials/integrations/deepseekr1-dynamic.md index cf52de7e3b..4cbcb90b1b 100644 --- a/docs/tutorials/integrations/deepseekr1-dynamic.md +++ b/docs/tutorials/integrations/deepseekr1-dynamic.md @@ -16,6 +16,7 @@ This guide focuses on running the **full DeepSeek-R1 Dynamic 1.58-bit quantized ## Step 1: Install Llama.cpp You can either: + - [Download the prebuilt binaries](https://github.com/ggerganov/llama.cpp/releases) - **Or build it yourself**: Follow the instructions here: [Llama.cpp Build Guide](https://github.com/ggerganov/llama.cpp/blob/master/docs/build.md) @@ -23,14 +24,14 @@ You can either: Head over to [Unsloth’s Hugging Face page](https://huggingface.co/unsloth/DeepSeek-R1-GGUF) and download the appropriate **dynamic quantized version** of DeepSeek-R1. For this tutorial, we’ll use the **1.58-bit (131GB)** version, which is highly optimized yet remains surprisingly functional. - :::tip -Know your "working directory" — where your Python script or terminal session is running. The model files will download to a subfolder of that directory by default, so be sure you know its path! For example, if you're running the command below in `/Users/yourname/Documents/projects`, your downloaded model will be saved under `/Users/yourname/Documents/projects/DeepSeek-R1-GGUF`. +Know your "working directory" — where your Python script or terminal session is running. The model files will download to a subfolder of that directory by default, so be sure you know its path! For example, if you're running the command below in `/Users/yourname/Documents/projects`, your downloaded model will be saved under `/Users/yourname/Documents/projects/DeepSeek-R1-GGUF`. ::: To understand more about UnslothAI’s development process and why these dynamic quantized versions are so efficient, check out their blog post: [UnslothAI DeepSeek R1 Dynamic Quantization](https://unsloth.ai/blog/deepseekr1-dynamic). Here’s how to download the model programmatically: + ```python # Install Hugging Face dependencies before running this: # pip install huggingface_hub hf_transfer @@ -45,6 +46,7 @@ snapshot_download( ``` Once the download completes, you’ll find the model files in a directory structure like this: + ``` DeepSeek-R1-GGUF/ ├── DeepSeek-R1-UD-IQ1_S/ @@ -62,18 +64,19 @@ DeepSeek-R1-GGUF/ If you don’t already have **Open WebUI** installed, no worries! It’s a simple setup. Just follow the [Open WebUI documentation here](https://docs.openwebui.com/). Once installed, start the application — we’ll connect it in a later step to interact with the DeepSeek-R1 model. - ## Step 4: Serve the Model Using Llama.cpp Now that the model is downloaded, the next step is to run it using **Llama.cpp’s server mode**. Before you begin: 1. **Locate the `llama-server` binary.** If you built from source (as outlined in Step 1), the `llama-server` executable will be located in `llama.cpp/build/bin`. Navigate to this directory by using the `cd` command: + ```bash cd [path-to-llama-cpp]/llama.cpp/build/bin ``` Replace `[path-to-llama-cpp]` with the location where you cloned or built Llama.cpp. For example: + ```bash cd ~/Documents/workspace/llama.cpp/build/bin ``` @@ -82,6 +85,7 @@ Now that the model is downloaded, the next step is to run it using **Llama.cpp Use the full path to the downloaded GGUF files created in Step 2. When serving the model, specify the first part of the split GGUF files (e.g., `DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf`). Here’s the command to start the server: + ```bash ./llama-server \ --model /[your-directory]/DeepSeek-R1-GGUF/DeepSeek-R1-UD-IQ1_S/DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf \ @@ -90,7 +94,6 @@ Here’s the command to start the server: --n-gpu-layers 40 ``` - :::tip 🔑 **Parameters to Customize Based on Your Machine:** @@ -98,9 +101,11 @@ Here’s the command to start the server: - **`--port`:** The server default is `8080`, but feel free to change it based on your port availability. - **`--ctx-size`:** Determines context length (number of tokens). You can increase it if your hardware allows, but be cautious of rising RAM/VRAM usage. - **`--n-gpu-layers`:** Set the number of layers you want to offload to your GPU for faster inference. The exact number depends on your GPU’s memory capacity — reference Unsloth’s table for specific recommendations. + ::: For example, if your model was downloaded to `/Users/tim/Documents/workspace`, your command would look like this: + ```bash ./llama-server \ --model /Users/tim/Documents/workspace/DeepSeek-R1-GGUF/DeepSeek-R1-UD-IQ1_S/DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf \ @@ -110,6 +115,7 @@ For example, if your model was downloaded to `/Users/tim/Documents/workspace`, y ``` Once the server starts, it will host a **local OpenAI-compatible API** endpoint at: + ``` http://127.0.0.1:10000 ``` diff --git a/docs/tutorials/integrations/firefox-sidebar.md b/docs/tutorials/integrations/firefox-sidebar.md index eaa136bd1d..3d260a4288 100644 --- a/docs/tutorials/integrations/firefox-sidebar.md +++ b/docs/tutorials/integrations/firefox-sidebar.md @@ -22,8 +22,8 @@ Before integrating Open WebUI as a AI chatbot browser assistant in Mozilla Firef 1. Click on the hamburger button (three horizontal lines button at the top right corner, just below the `X` button) 2. Open up Firefox settings -2. Click on the `Firefox Labs` section -3. Toggle on `AI Chatbot` +3. Click on the `Firefox Labs` section +4. Toggle on `AI Chatbot` Alternatively, you can enable AI Chatbot through the `about:config` page (described in the next section). @@ -109,4 +109,4 @@ The following `about:config` settings can be adjusted for further customization: To access the AI chatbot sidebar, use one of the following methods: * Press `CTRL+B` to open the bookmarks sidebar and switch to AI Chatbot -* Press `CTRL+Alt+X` to open the AI chatbot sidebar directly \ No newline at end of file +* Press `CTRL+Alt+X` to open the AI chatbot sidebar directly diff --git a/docs/tutorials/integrations/helicone.md b/docs/tutorials/integrations/helicone.md index c55d539dc1..2a9b0622a5 100644 --- a/docs/tutorials/integrations/helicone.md +++ b/docs/tutorials/integrations/helicone.md @@ -21,7 +21,6 @@ By enabling Helicone, you can log LLM requests, evaluate and experiment with pro - **Debug capabilities** to troubleshoot issues with model responses - **Cost tracking** for your LLM usage across providers - ## How to integrate Helicone with OpenWebUI