diff --git a/docs/getting-started/env-configuration.md b/docs/getting-started/env-configuration.md index aa074fdc..ef1d0354 100644 --- a/docs/getting-started/env-configuration.md +++ b/docs/getting-started/env-configuration.md @@ -1638,6 +1638,8 @@ Note: this configuration assumes that AWS credentials will be available to your ## Retrieval Augmented Generation (RAG) +### Core Configuration + #### `RAG_EMBEDDING_ENGINE` - Type: `str` @@ -1645,6 +1647,7 @@ Note: this configuration assumes that AWS credentials will be available to your - Leave empty for `Default (SentenceTransformers)` - Uses SentenceTransformers for embeddings. - `ollama` - Uses the Ollama API for embeddings. - `openai` - Uses the OpenAI API for embeddings. + - `azure` - Uses Azure OpenAI Services for embeddings. - Description: Selects an embedding engine to use for RAG. - Persistence: This environment variable is a `PersistentConfig` variable. @@ -1655,14 +1658,6 @@ Note: this configuration assumes that AWS credentials will be available to your - Description: Sets a model for embeddings. Locally, a Sentence-Transformer model is used. - Persistence: This environment variable is a `PersistentConfig` variable. -#### `ENABLE_RAG_HYBRID_SEARCH` - -- Type: `bool` -- Default: `False` -- Description: Enables the use of ensemble search with `BM25` + `ChromaDB`, with reranking using -`sentence_transformers` models. -- Persistence: This environment variable is a `PersistentConfig` variable. - #### `RAG_TOP_K` - Type: `int` @@ -1684,11 +1679,18 @@ Note: this configuration assumes that AWS credentials will be available to your - Description: Sets the relevance threshold to consider for documents when used with reranking. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `ENABLE_RAG_HYBRID_SEARCH` + +- Type: `bool` +- Default: `False` +- Description: Enables the use of ensemble search with `BM25` + `ChromaDB`, with reranking using `sentence_transformers` models. +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `RAG_HYBRID_BM25_WEIGHT` - Type: `float` - Default: `0.5` -- Description: Sets the weight given to the keyword search (BM25) during hybrid search. 1 means only keyword serach, 0 means only vector search. +- Description: Sets the weight given to the keyword search (BM25) during hybrid search. 1 means only keyword search, 0 means only vector search. - Persistence: This environment variable is a `PersistentConfig` variable. #### `RAG_TEMPLATE` @@ -1729,7 +1731,23 @@ Provide a clear and direct response to the user's query, including inline citati ``` -- Description: Template to use when injecting RAG documents into chat completion +- Description: Template to use when injecting RAG documents into chat completion. +- Persistence: This environment variable is a `PersistentConfig` variable. + +### Document Processing + +#### `CHUNK_SIZE` + +- Type: `int` +- Default: `1000` +- Description: Sets the document chunk size for embeddings. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### `CHUNK_OVERLAP` + +- Type: `int` +- Default: `100` +- Description: Specifies how much overlap there should be between chunks. - Persistence: This environment variable is a `PersistentConfig` variable. #### `RAG_TEXT_SPLITTER` @@ -1756,20 +1774,6 @@ Provide a clear and direct response to the user's query, including inline citati - Description: Sets the encoding name for TikToken. - Persistence: This environment variable is a `PersistentConfig` variable. -#### `CHUNK_SIZE` - -- Type: `int` -- Default: `1000` -- Description: Sets the document chunk size for embeddings. -- Persistence: This environment variable is a `PersistentConfig` variable. - -#### `CHUNK_OVERLAP` - -- Type: `int` -- Default: `100` -- Description: Specifies how much overlap there should be between chunks. -- Persistence: This environment variable is a `PersistentConfig` variable. - #### `PDF_EXTRACT_IMAGES` - Type: `bool` @@ -1789,17 +1793,11 @@ Provide a clear and direct response to the user's query, including inline citati - Description: Sets the maximum number of files that can be uploaded at once for document ingestion. - Persistence: This environment variable is a `PersistentConfig` variable. -:::info - -When configuring `RAG_FILE_MAX_SIZE` and `RAG_FILE_MAX_COUNT`, ensure that the values are reasonable to prevent excessive file uploads and potential performance issues. - -::: - #### `RAG_ALLOWED_FILE_EXTENSIONS` - Type: `list` of `str` - Default: `[]` (which means all supported file types are allowed) -- Description: Specifies which file extensions are permitted for upload. +- Description: Specifies which file extensions are permitted for upload. ```json ["pdf,docx,txt"] @@ -1807,12 +1805,46 @@ When configuring `RAG_FILE_MAX_SIZE` and `RAG_FILE_MAX_COUNT`, ensure that the v - Persistence: This environment variable is a `PersistentConfig` variable. -#### `RAG_RERANKING_MODEL` +:::info + +When configuring `RAG_FILE_MAX_SIZE` and `RAG_FILE_MAX_COUNT`, ensure that the values are reasonable to prevent excessive file uploads and potential performance issues. + +::: + +### Embedding Engine Configuration + +#### General Embedding Settings + +#### `RAG_EMBEDDING_BATCH_SIZE` + +- Type: `int` +- Default: `1` +- Description: Sets the batch size for embedding in RAG (Retrieval-Augmented Generator) models. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### `RAG_EMBEDDING_CONTENT_PREFIX` - Type: `str` -- Description: Sets a model for reranking results. Locally, a Sentence-Transformer model is used. +- Default: `None` +- Description: Specifies the prefix for the RAG embedding content. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `RAG_EMBEDDING_PREFIX_FIELD_NAME` + +- Type: `str` +- Default: `None` +- Description: Specifies the field name for the RAG embedding prefix. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### `RAG_EMBEDDING_QUERY_PREFIX` + +- Type: `str` +- Default: `None` +- Description: Specifies the prefix for the RAG embedding query. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### OpenAI Embeddings + #### `RAG_OPENAI_API_BASE_URL` - Type: `str` @@ -1833,11 +1865,35 @@ When configuring `RAG_FILE_MAX_SIZE` and `RAG_FILE_MAX_COUNT`, ensure that the v - Default: `1` - Description: Sets the batch size for OpenAI embeddings. -#### `RAG_EMBEDDING_BATCH_SIZE` +#### Azure OpenAI Embeddings -- Type: `int` -- Default: `1` -- Description: Sets the batch size for embedding in RAG (Retrieval-Augmented Generator) models. +#### `RAG_AZURE_OPENAI_BASE_URL` + +- Type: `str` +- Default: `None` +- Description: Sets the base URL for Azure OpenAI Services when using Azure OpenAI for RAG embeddings. Should be in the format `https://{your-resource-name}.openai.azure.com`. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### `RAG_AZURE_OPENAI_API_KEY` + +- Type: `str` +- Default: `None` +- Description: Sets the API key for Azure OpenAI Services when using Azure OpenAI for RAG embeddings. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### `RAG_AZURE_OPENAI_API_VERSION` + +- Type: `str` +- Default: `None` +- Description: Sets the API version for Azure OpenAI Services when using Azure OpenAI for RAG embeddings. Common values include `2023-05-15`, `2023-12-01-preview`, or `2024-02-01`. +- Persistence: This environment variable is a `PersistentConfig` variable. + +#### Ollama Embeddings + +#### `RAG_OLLAMA_BASE_URL` + +- Type: `str` +- Description: Sets the base URL for Ollama API used in RAG models. - Persistence: This environment variable is a `PersistentConfig` variable. #### `RAG_OLLAMA_API_KEY` @@ -1846,12 +1902,16 @@ When configuring `RAG_FILE_MAX_SIZE` and `RAG_FILE_MAX_COUNT`, ensure that the v - Description: Sets the API key for Ollama API used in RAG models. - Persistence: This environment variable is a `PersistentConfig` variable. -#### `RAG_OLLAMA_BASE_URL` +### Reranking + +#### `RAG_RERANKING_MODEL` - Type: `str` -- Description: Sets the base URL for Ollama API used in RAG models. +- Description: Sets a model for reranking results. Locally, a Sentence-Transformer model is used. - Persistence: This environment variable is a `PersistentConfig` variable. +### Query Generation + #### `ENABLE_RETRIEVAL_QUERY_GENERATION` - Type: `bool` @@ -1894,12 +1954,7 @@ Strictly return in JSON format: - Description: Sets the prompt template for query generation. - Persistence: This environment variable is a `PersistentConfig` variable. -#### `BYPASS_EMBEDDING_AND_RETRIEVAL` - -- Type: `bool` -- Default: `False` -- Description: Bypasses the embedding and retrieval process. -- Persistence: This environment variable is a `PersistentConfig` variable. +### Document Intelligence (Azure) #### `DOCUMENT_INTELLIGENCE_ENDPOINT` @@ -1915,32 +1970,13 @@ Strictly return in JSON format: - Description: Specifies the key for document intelligence. - Persistence: This environment variable is a `PersistentConfig` variable. -#### `ENABLE_RAG_LOCAL_WEB_FETCH` +### Advanced Settings + +#### `BYPASS_EMBEDDING_AND_RETRIEVAL` - Type: `bool` - Default: `False` -- Description: Enables or disables local web fetch for RAG. -- Persistence: This environment variable is a `PersistentConfig` variable. - -#### `RAG_EMBEDDING_CONTENT_PREFIX` - -- Type: `str` -- Default: `None` -- Description: Specifies the prefix for the RAG embedding content. -- Persistence: This environment variable is a `PersistentConfig` variable. - -#### `RAG_EMBEDDING_PREFIX_FIELD_NAME` - -- Type: `str` -- Default: `None` -- Description: Specifies the field name for the RAG embedding prefix. -- Persistence: This environment variable is a `PersistentConfig` variable. - -#### `RAG_EMBEDDING_QUERY_PREFIX` - -- Type: `str` -- Default: `None` -- Description: Specifies the prefix for the RAG embedding query. +- Description: Bypasses the embedding and retrieval process. - Persistence: This environment variable is a `PersistentConfig` variable. #### `RAG_FULL_CONTEXT` @@ -1950,6 +1986,13 @@ Strictly return in JSON format: - Description: Specifies whether to use the full context for RAG. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `ENABLE_RAG_LOCAL_WEB_FETCH` + +- Type: `bool` +- Default: `False` +- Description: Enables or disables local web fetch for RAG. +- Persistence: This environment variable is a `PersistentConfig` variable. + ### Google Drive #### `ENABLE_GOOGLE_DRIVE_INTEGRATION` @@ -1985,45 +2028,59 @@ For a step-by-step setup guide, check out our tutorial: [Configuring OneDrive & #### `ENABLE_ONEDRIVE_INTEGRATION` -- Type: `bool` -- Default: `False` -- Description: Enables or disables the Microsoft OneDrive integration feature globally. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Type: `bool` +- Default: `False` +- Description: Enables or disables the Microsoft OneDrive integration feature globally. +- Persistence: This environment variable is a `PersistentConfig` variable. + +:::warning +Configuring OneDrive integration is a multi-step process that requires creating and correctly configuring an Azure App Registration. +The authentication flow also depends on a browser pop-up window. Please ensure that your browser's pop-up blocker is disabled for your Open WebUI domain to allow the authentication and file selection window to appear. +::: #### `ENABLE_ONEDRIVE_PERSONAL` -- Type: `bool` -- Default: `True` -- Description: Controls whether the "Personal OneDrive" option appears in the attachment menu. Requires `ONEDRIVE_PERSONAL_CLIENT_ID` to be configured. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Type: `bool` +- Default: `True` +- Description: Controls whether the "Personal OneDrive" option appears in the attachment menu. Requires `ONEDRIVE_PERSONAL_CLIENT_ID` to be configured. +- Persistence: This environment variable is a `PersistentConfig` variable. #### `ENABLE_ONEDRIVE_BUSINESS` -- Type: `bool` -- Default: `True` -- Description: Controls whether the "Work/School OneDrive" option appears in the attachment menu. Requires `ONEDRIVE_CLIENT_ID` to be configured. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Type: `bool` +- Default: `True` +- Description: Controls whether the "Work/School OneDrive" option appears in the attachment menu. Requires `ONEDRIVE_CLIENT_ID` to be configured. +- Persistence: This environment variable is a `PersistentConfig` variable. #### `ONEDRIVE_CLIENT_ID` -- Type: `str` -- Default: `None` -- Description: Specifies the Application (client) ID for the **Work/School (Business) OneDrive & SharePoint** integration. This is obtained from an Azure App Registration configured for your organization's tenant. **Do not put the personal OneDrive client ID here!** -- Persistence: This environment variable is a `PersistentConfig` variable. +- Type: `str` +- Default: `None` +- Description: Specifies the Application (client) ID for the **Work/School (Business) OneDrive & SharePoint** integration. This is obtained from an Azure App Registration configured for your organization's tenant. **Do not put the personal OneDrive client ID here!** +- Persistence: This environment variable is a `PersistentConfig` variable. #### `ONEDRIVE_PERSONAL_CLIENT_ID` -- Type: `str` -- Default: `None` -- Description: Specifies the Application (client) ID for the **Personal OneDrive** integration. This requires a separate Azure App Registration configured to support personal Microsoft accounts. **Do not put the business OneDrive client ID here!** -- Persistence: This environment variable is a `PersistentConfig` variable. +- Type: `str` +- Default: `None` +- Description: Specifies the Application (client) ID for the **Personal OneDrive** integration. This requires a separate Azure App Registration configured to support personal Microsoft accounts. **Do not put the business OneDrive client ID here!** +- Persistence: This environment variable is a `PersistentConfig` variable. + +:::info +This Client ID (also known as Application ID) is obtained from an Azure App Registration within your Microsoft Entra ID (formerly Azure AD) tenant. +When configuring the App Registration in Azure, the Redirect URI must be set to the URL of your Open WebUI instance and configured as a **Single-page application (SPA)** type for the authentication to succeed. +::: #### `ONEDRIVE_SHAREPOINT_URL` -- Type: `str` -- Default: `None` -- Description: Specifies the root SharePoint site URL for the work/school integration, e.g., `https://companyname.sharepoint.com`. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Type: `str` +- Default: `None` +- Description: Specifies the root SharePoint site URL for the work/school integration, e.g., `https://companyname.sharepoint.com`. +- Persistence: This environment variable is a `PersistentConfig` variable. + +:::info +This variable is essential for the work/school integration. It should point to the root SharePoint site associated with your tenant, enabling access to SharePoint document libraries. +::: #### `ONEDRIVE_SHAREPOINT_TENANT_ID` @@ -2032,6 +2089,10 @@ For a step-by-step setup guide, check out our tutorial: [Configuring OneDrive & - Description: Specifies the Directory (tenant) ID for the work/school integration. This is obtained from your business-focused Azure App Registration. - Persistence: This environment variable is a `PersistentConfig` variable. +:::info +This Tenant ID (also known as Directory ID) is required for the work/school integration. You can find this value on the main overview page of your Azure App Registration in the Microsoft Entra ID portal. +::: + ## Web Search #### `ENABLE_WEB_SEARCH` @@ -3089,8 +3150,10 @@ Even when using Microsoft, GitHub or other providers, you MUST set the `OPENID_P #### `OAUTH_CODE_CHALLENGE_METHOD` - Type: `str` +- Options: + - `S256` - Hash `code_verifier` with SHA-256. - Default: Empty string (' '), since `None` is set as default. -- Description: Specifies the code challenge method for OAuth authentication. +- Description: Specifies the code challenge method for OAuth authentication. Set to `S256` when PKCE is required by the provider. - Persistence: This environment variable is a `PersistentConfig` variable. #### `OAUTH_PROVIDER_NAME` diff --git a/docs/tutorials/integrations/onedrive-sharepoint.mdx b/docs/tutorials/integrations/onedrive-sharepoint.mdx new file mode 100644 index 00000000..1fe2a14d --- /dev/null +++ b/docs/tutorials/integrations/onedrive-sharepoint.mdx @@ -0,0 +1,130 @@ +--- +sidebar_position: 32 +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. +::: + +--- + +# Configuring OneDrive & SharePoint Integration + +This guide will walk you through the entire process of configuring Open WebUI to allow users to attach files directly from their Microsoft accounts. This process involves creating one or two application registrations in the Microsoft Azure portal and setting the correct environment variables in your Open WebUI instance. + +## Prerequisites + +To successfully complete this tutorial, you will need: + +- An active Microsoft Azure account with administrative privileges to create and manage App Registrations. +- Access to your Open WebUI instance's environment variables (e.g., via a `.env` file or Docker environment settings). + +# Integration for OneDrive for Business & SharePoint (Work/School) + +This is the primary integration for organizational use. Follow these steps to allow users to access files from their work or school accounts. + +## Step 1: Create the Azure App Registration + +First, you need to register an application in your organization's Microsoft Entra ID (formerly Azure AD) tenant. + +1. Navigate to the [Microsoft Entra ID admin center](https://entra.microsoft.com/). +2. Go to **Identity** > **Applications** > **App registrations**. +3. Select **+ New registration**. +4. Give your application a descriptive name, such as "Open WebUI Business Integration". +5. Under "Supported account types," select **"Accounts in this organizational directory only (Single tenant)"** or **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)"**. +6. Leave the "Redirect URI" section blank for now. Click **Register**. + +## Step 2: Configure the SPA Redirect URI + +Open WebUI is a Single-Page Application (SPA) and uses the Microsoft Authentication Library (MSAL). It is critical to configure the Redirect URI correctly. + +1. From your new App Registration's overview page, go to the **Authentication** tab. +2. Click **+ Add a platform** and select **Single-page application (SPA)**. +3. Under "Redirect URIs", enter the base URL of your Open WebUI instance (e.g., `https://open-webui.yourdomain.com`). +4. Click **Configure**. + +## Step 3: Configure API Permissions + +Next, grant the application permission to read files from OneDrive and SharePoint on behalf of your users. + +1. From the App Registration menu, go to the **API permissions** tab. +2. Click **+ Add a permission** and select **Microsoft Graph**. +3. Select **Delegated permissions**. +4. In the search box, find and add the following two permissions: + - `Files.Read.All`: Allows the app to read all files the signed-in user can access. + - `Sites.Read.All`: Allows the app to read items in all site collections the signed-in user can access. +5. After adding the permissions, you must grant admin consent. Click the **"Grant admin consent for [Your Tenant Name]"** button. The status for these permissions should change to "Granted". + +:::warning Admin Consent is Mandatory +Open WebUI uses the `.default` scope for a seamless enterprise experience, meaning it relies on pre-approved permissions. If admin consent is not granted here, non-admin users will be blocked from logging in with an "Admin approval required" error. +::: + +## Step 4: Gather Credentials for Business Integration + +From the **Overview** page of the App Registration you just created, copy the following values: + +- **Application (client) ID**: This will be your `ONEDRIVE_CLIENT_ID`. +- **Directory (tenant) ID**: This will be your `ONEDRIVE_SHAREPOINT_TENANT_ID`. + +## Step 5: Configure Environment Variables for Business Integration + +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 + +# --- Business & SharePoint Configuration --- +# The Application (client) ID from your Business App Registration +ONEDRIVE_CLIENT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + +# The Directory (tenant) ID from your Business App Registration +ONEDRIVE_SHAREPOINT_TENANT_ID="yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" + +# The root URL of your SharePoint instance +ONEDRIVE_SHAREPOINT_URL="https://your-tenant-name.sharepoint.com" +``` + +--- + +# Integration for Personal OneDrive (Optional) + +To enable support for personal Microsoft accounts, you must create a **second, separate App Registration** configured for consumers. + +## Step 1: Create a Separate App Registration for Personal Accounts + +1. Navigate back to **App registrations** in Microsoft Entra ID and select **+ New registration**. +2. Give it a distinct name, like "Open WebUI Personal Integration". +3. Under "Supported account types," select the option: **"Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"**. +4. Configure the **SPA Redirect URI** with your Open WebUI base URL, just as you did for the business app. +5. For this personal registration, no special API permissions or admin consent are required, as users will consent to `OneDrive.ReadWrite` individually. + +## Step 2: Gather the Client ID for Personal Integration + +From the **Overview** page of this new "Personal" App Registration, copy the **Application (client) ID**. This will be used for a different environment variable. + +## Step 3: Configure the Environment Variable for Personal Integration + +Add the following environment variable to your Open WebUI deployment: + +```bash +# --- Personal Account Configuration (Optional) --- +# The Application (client) ID from your *second*, Personal App Registration +ONEDRIVE_PERSONAL_CLIENT_ID="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz" +``` + +--- + +## Final Step: Browser Configuration and Verification + +After setting your environment variables and restarting your Open WebUI instance, verify the integration. + +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. + +:::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. +::: + +You have now successfully configured OneDrive integration, providing seamless file access for your users. diff --git a/docs/tutorials/tab-nginx/SelfSigned.md b/docs/tutorials/tab-nginx/SelfSigned.md index f6bcf6c8..679990ff 100644 --- a/docs/tutorials/tab-nginx/SelfSigned.md +++ b/docs/tutorials/tab-nginx/SelfSigned.md @@ -26,6 +26,12 @@ Using self-signed certificates is suitable for development or internal use where location / { 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"; + proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; diff --git a/docs/tutorials/tips/one-click-ollama-launcher.mdx b/docs/tutorials/tips/one-click-ollama-launcher.mdx new file mode 100644 index 00000000..69d1c127 --- /dev/null +++ b/docs/tutorials/tips/one-click-ollama-launcher.mdx @@ -0,0 +1,266 @@ +--- +sidebar_position: 21 +title: "🚀 One-Click Ollama + Open WebUI Launcher" +--- + +:::warning +This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial. +::: + +# One-Click Ollama + Open WebUI Launcher (Linux) + +This tutorial shows you how to create a convenient desktop launcher that automatically starts both Ollama and Open WebUI services with a single click, then opens your browser to the correct local address. This is perfect for users who have Open WebUI installed in a conda environment and want a streamlined startup experience. + +## Prerequisites + +Before starting this tutorial, ensure you have: + +- **Linux system** with GNOME desktop environment (or compatible terminal) +- **Ollama installed** as a system service +- **Open WebUI installed** in a conda environment +- **Basic terminal knowledge** and sudo access + +## Overview + +This solution creates three components: +1. A script to properly stop the Ollama service (prevents port conflicts) +2. A main startup script that launches both services in separate terminal tabs +3. A desktop entry for one-click access from your application menu + +## Step 1: Create the Ollama Stop Script + +First, we'll create a script to cleanly stop the Ollama service. This prevents the common "address already in use" error when restarting Ollama. + +Create a directory for your scripts and the stop script: + +```bash +mkdir -p ~/ollama-open-webui +cd ~/ollama-open-webui +``` + +Create `stop_ollama.sh`: + +```bash +nano stop_ollama.sh +``` + +Add the following content: + +```bash +#!/bin/bash +systemctl stop ollama +``` + +Make the script executable: + +```bash +chmod +x ~/ollama-open-webui/stop_ollama.sh +``` + +## Step 2: Configure Sudo Permissions + +To avoid entering your password every time the script runs, we'll configure sudo to allow passwordless execution of our stop script. + +**⚠️ Important:** This step requires careful attention to security. Only grant permissions to the specific script path. + +Open the sudo configuration: + +```bash +sudo visudo +``` + +Add this line at the bottom of the file (replace `yourusername` with your actual username): + +```bash +yourusername ALL=(ALL) NOPASSWD: /home/yourusername/ollama-open-webui/stop_ollama.sh +``` + +Save and exit the editor (in nano: `Ctrl+X`, then `Y`, then `Enter`). + +## Step 3: Create the Main Startup Script + +Now create the main script that orchestrates the entire startup process. + +Create `start_services.sh`: + +```bash +nano ~/ollama-open-webui/start_services.sh +``` + +Add the following content (make sure to replace `yourusername` with your actual username and `openwebui` with your actual conda environment name): + +```bash +#!/usr/bin/env bash +###################################################### +# A script to start up Ollama and Open WebUI # +###################################################### + +# Stop Ollama service to prevent port conflicts +sudo /home/yourusername/ollama-open-webui/stop_ollama.sh + +# Start Ollama in a new terminal tab +gnome-terminal --tab --title="Ollama" -- bash -i -c " + echo 'Starting Ollama service...'; + ollama serve; + exec bash +" + +# Start Open WebUI in another new terminal tab +gnome-terminal --tab --title="Open-WebUI" -- bash -i -c " + echo 'Activating conda environment and starting Open WebUI...'; + conda activate openwebui; + open-webui serve; + exec bash +" + +# Open browser tab after services have time to start +gnome-terminal --tab --title="Browser" -- bash -i -c " + echo 'Waiting for services to start...'; + sleep 5; + echo 'Opening browser...'; + xdg-open http://localhost:8080/; + exec bash +" + +echo "All services are starting. Check the terminal tabs for status." +``` + +Make the script executable: + +```bash +chmod +x ~/ollama-open-webui/start_services.sh +``` + +## Step 4: Test the Script + +Before creating the desktop entry, test your script to ensure it works: + +```bash +~/ollama-open-webui/start_services.sh +``` + +You should see: +- Three new terminal tabs opening +- Ollama starting in the first tab +- Open WebUI starting in the second tab (after conda activation) +- Your default browser opening to `http://localhost:8080/` after a 5-second delay + +If there are any errors, check that: +- Your conda environment name is correct +- Ollama is properly installed +- Open WebUI is installed in the specified conda environment + +## Step 5: Create the Desktop Entry + +Create a desktop entry file to make this accessible from your application menu: + +```bash +nano ~/.local/share/applications/start_ollama_webui.desktop +``` + +Add the following content (replace `yourusername` with your actual username): + +```desktop +[Desktop Entry] +Name=Ollama + Open WebUI +Comment=Start Ollama and Open WebUI services with one click +Exec=/home/yourusername/ollama-open-webui/start_services.sh +Icon=utilities-terminal +Terminal=true +Type=Application +Categories=Development;Utility; +``` + +Make the desktop entry executable: + +```bash +chmod +x ~/.local/share/applications/start_ollama_webui.desktop +``` + +## Step 6: Optional Customizations + +### Custom Icon + +You can download an Ollama icon and use it instead of the default terminal icon: + +1. Download an icon (PNG format recommended) and save it as `~/ollama-open-webui/ollama_icon.png` +2. Update the desktop entry's `Icon=` line to point to your icon: + ``` + Icon=/home/yourusername/ollama-open-webui/ollama_icon.png + ``` + +### Different Terminal Emulator + +If you're not using GNOME Terminal, modify the `gnome-terminal` commands in the startup script. For example: + +- **For Konsole (KDE):** Replace `gnome-terminal --tab --title="Title"` with `konsole --new-tab -e` +- **For xterm:** Use `xterm -T "Title" -e` +- **For Terminal (XFCE):** Use `xfce4-terminal --tab --title="Title" --command` + +### Different Conda Environment + +If your Open WebUI is installed in a different conda environment, update the environment name in the startup script: + +```bash +conda activate your-environment-name; +``` + +## Usage + +After completing all steps: + +1. **From Application Menu:** Search for "Ollama" or "Open WebUI" in your application launcher +2. **From Desktop:** If you copied the desktop entry to your desktop, double-click it +3. **From Terminal:** Run the script directly with `~/ollama-open-webui/start_services.sh` + +The launcher will: +- Stop any existing Ollama service +- Start Ollama in a new terminal tab +- Start Open WebUI in another terminal tab +- Automatically open your browser to the correct URL +- Keep all terminal tabs open so you can monitor the services + +## Troubleshooting + +### Permission Denied Errors + +If you get permission denied errors: +- Ensure all scripts have execute permissions (`chmod +x`) +- Verify the sudo configuration is correct +- Check that file paths match your actual username + +### Services Don't Start + +If services fail to start: +- Check that Ollama is properly installed system-wide +- Verify your conda environment name is correct +- Ensure Open WebUI is installed in the specified environment +- Look at the terminal output for specific error messages + +### Browser Doesn't Open + +If the browser doesn't open automatically: +- Check that `xdg-open` is available on your system +- Try manually opening `http://localhost:8080/` in your browser +- Increase the sleep duration in the script if services need more time to start + +### Different Desktop Environment + +For non-GNOME environments: +- Replace `gnome-terminal` with your system's terminal emulator +- Adjust the command-line arguments as needed for your terminal +- Test the modified script before creating the desktop entry + +## Security Considerations + +This setup requires sudo access for stopping the Ollama service. The sudo configuration is limited to a specific script to minimize security risks, but you should: + +- Regularly review your sudo configuration +- Ensure the stop script only contains the necessary systemctl command +- Keep your scripts in a secure location with appropriate permissions + +## Conclusion + +You now have a convenient one-click solution for starting your Ollama and Open WebUI setup! This approach is particularly useful for development workflows where you frequently start and stop these services. + +The terminal tabs remain open so you can monitor service logs and easily stop the services when needed (Ctrl+C in each respective tab). diff --git a/docs/tutorials/tips/sqlite-database.md b/docs/tutorials/tips/sqlite-database.md index d029faef..f427b56a 100644 --- a/docs/tutorials/tips/sqlite-database.md +++ b/docs/tutorials/tips/sqlite-database.md @@ -8,7 +8,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: > [!WARNING] -> This documentation was created based on the current version (0.5.11) and is constantly being updated. +> This documentation was created/updated based on version 0.6.30. # Open-WebUI Internal SQLite Database @@ -70,10 +70,12 @@ Here is a complete list of tables in Open-WebUI's SQLite database. The tables ar | 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 | prompt | Stores templates and configurations for AI prompts | -| 20 | tag | Manages tags/labels for content categorization | -| 21 | tool | Stores configurations for system tools and integrations | -| 22 | user | Maintains user profiles and account information | +| 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 | 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: @@ -205,11 +207,12 @@ The `meta` field's expected structure: | **Column Name** | **Data Type** | **Constraints** | **Description** | | --------------- | ------------- | --------------- | ------------------------------ | -| id | Text | PRIMARY KEY | Unique identifier (UUID) | +| id | Text | PK (composite) | Unique identifier (UUID) | | parent_id | Text | nullable | Parent folder ID for hierarchy | -| user_id | Text | - | Owner of the folder | +| user_id | Text | PK (composite) | Owner of the folder | | name | Text | - | Folder name | | items | JSON | nullable | Folder contents | +| data | JSON | nullable | Additional folder data | | meta | JSON | nullable | Folder metadata | | is_expanded | Boolean | default=False | UI expansion state | | created_at | BigInteger | - | Creation timestamp | @@ -217,9 +220,10 @@ The `meta` field's expected structure: Things to know about the folder table: -- Folders can be nested (parent_id reference) -- Root folders have null parent_id -- Folder names must be unique within same parent +- Primary key is composite (`id`, `user_id`) +- Folders can be nested (`parent_id` reference) +- Root folders have null `parent_id` +- Folder names must be unique within the same parent ## Function Table @@ -237,7 +241,7 @@ Things to know about the folder table: | created_at | BigInteger | - | Creation timestamp | | updated_at | BigInteger | - | Last update timestamp | -Things to know about the folder table: +Things to know about the function table: - `type` can only be: ["filter", "action"] @@ -334,6 +338,31 @@ The `access_control` fields expected structure: | created_at | BigInteger | - | Creation timestamp | | updated_at | BigInteger | - | Last update timestamp | +## Note Table + +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| --------------- | ------------- | --------------- | -------------------------- | +| id | Text | PRIMARY KEY | Unique identifier | +| user_id | Text | nullable | Owner of the note | +| title | Text | nullable | Note title | +| data | JSON | nullable | Note content and data | +| meta | JSON | nullable | Note metadata | +| access_control | JSON | nullable | Permission settings | +| created_at | BigInteger | nullable | Creation timestamp | +| updated_at | BigInteger | nullable | Last update timestamp | + +## OAuth Session Table + +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| --------------- | ------------- | -------------------- | --------------------------------- | +| id | Text | PRIMARY KEY | Unique session identifier | +| user_id | Text | FOREIGN KEY(user.id) | Associated user | +| provider | Text | - | OAuth provider (e.g., 'google') | +| token | Text | - | OAuth session token | +| expires_at | BigInteger | - | Token expiration timestamp | +| created_at | BigInteger | - | Session creation timestamp | +| updated_at | BigInteger | - | Session last update timestamp | + ## Prompt Table | **Column Name** | **Data Type** | **Constraints** | **Description** | @@ -375,20 +404,24 @@ Things to know about the tag table: ## User Table -| **Column Name** | **Data Type** | **Constraints** | **Description** | -| ----------------- | ------------- | ---------------- | ------------------------ | -| id | String | PRIMARY KEY | Unique identifier | -| name | String | - | User's name | -| email | String | - | User's email | -| role | String | - | User's role | -| profile_image_url | Text | - | Profile image path | -| last_active_at | BigInteger | - | Last activity timestamp | -| updated_at | BigInteger | - | Last update timestamp | -| created_at | BigInteger | - | Creation timestamp | -| api_key | String | UNIQUE, nullable | API authentication key | -| settings | JSON | nullable | User preferences | -| info | JSON | nullable | Additional user info | -| oauth_sub | Text | UNIQUE | OAuth subject identifier | +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| ----------------- | ------------- | ---------------- | -------------------------- | +| id | String | PRIMARY KEY | Unique identifier | +| username | String(50) | nullable | User's unique username | +| name | String | - | User's name | +| email | String | - | User's email | +| role | String | - | User's role | +| profile_image_url | Text | - | Profile image path | +| bio | Text | nullable | User's biography | +| gender | Text | nullable | User's gender | +| date_of_birth | Date | nullable | User's date of birth | +| last_active_at | BigInteger | - | Last activity timestamp | +| updated_at | BigInteger | - | Last update timestamp | +| created_at | BigInteger | - | Creation timestamp | +| api_key | String | UNIQUE, nullable | API authentication key | +| settings | JSON | nullable | User preferences | +| info | JSON | nullable | Additional user info | +| oauth_sub | Text | UNIQUE | OAuth subject identifier | # Entity Relationship Diagram @@ -412,6 +445,8 @@ erDiagram user ||--o{ prompt : "creates" user ||--o{ tag : "creates" user ||--o{ tool : "manages" + user ||--o{ note : "owns" + user ||--|| oauth_session : "has" %% Content Relationships message ||--o{ message_reaction : "has" @@ -422,10 +457,14 @@ erDiagram user { string id PK + string username string name string email string role text profile_image_url + text bio + text gender + date date_of_birth bigint last_active_at string api_key json settings @@ -501,11 +540,12 @@ erDiagram } folder { - text id PK + text id PK "composite" + text user_id PK "composite" text parent_id FK - text user_id FK text name json items + json data json meta boolean is_expanded } @@ -559,6 +599,23 @@ erDiagram boolean is_active } + note { + text id PK + text user_id FK + text title + json data + json meta + json access_control + } + + oauth_session { + text id PK + text user_id FK + text provider + text token + bigint expires_at + } + prompt { string command PK string user_id FK