# collections

id: d30b042c-1609-4957-8338-e92c8b275043
name: file-2f44a99b-3fcc-431a-a67d-14a77fe79961
database_id: 00000000-0000-0000-0000-000000000000
config_json_str:
{"hnsw_configuration": {"space": "l2", "ef_construction": 100, "ef_search": 10, "num_threads": 16, "M": 16, "resize_factor": 1.2, "batch_size": 100, "sync_threshold": 1000, "_type": "HNSWConfigurationInternal"}, "_type": "CollectionConfigurationInternal"}


# embedding_metadata

key: chroma:document
string_value:
---
sidebar_position: 6
title: "🎬 Actions"
---

Action functions allow you to write custom buttons to the message toolbar for end users to interact
with. This feature enables more interactive messaging, enabling users to grant permission before a
task is performed, generate visualizations of structured data, download an audio snippet of chats,
and many other use cases.

A scaffold of Action code can be found [in the community section](https://openwebui.com/f/hub/custom_action/).

An example of a graph visualization Action can be seen in the video below.

<p align="center">
  <a href="#">
    <img src="/img/pipelines/graph-viz-action.gif" alt="Graph Visualization Action" />
  </a>
</p>


key: chroma:document
string_value:
---
sidebar_position: 7
title: "🗄️ Hosting UI and Models separately"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::


key: chroma:document
string_value:
:::note
If you plan to expose this to the wide area network, consider implementing security like a [network firewall](https://github.com/chr0mag/geoipsets), [web application firewall](https://github.com/owasp-modsecurity/ModSecurity), and [threat intelligence](https://github.com/crowdsecurity/crowdsec).
Additionally, it's strongly recommended to enable HSTS possibly like `Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"` within your **HTTPS** configuration and a redirect of some kind to your **HTTPS URL** within your **HTTP** configuration. For free SSL certification, [Let's Encrypt](https://letsencrypt.org/) is a good option coupled with [Certbot](https://github.com/certbot/certbot) management.
:::

Sometimes, its beneficial to host Ollama, separate from the UI, but retain the RAG and RBAC support features shared across users:

## UI Configuration

For the UI configuration, you can set up the Apache VirtualHost as follows:


key: chroma:document
string_value:
## UI Configuration

For the UI configuration, you can set up the Apache VirtualHost as follows:

```
# Assuming you have a website hosting this UI at "server.com"
<VirtualHost 192.168.1.100:80>
    ServerName server.com
    DocumentRoot /home/server/public_html

    ProxyPass / http://server.com:3000/ nocanon
    ProxyPassReverse / http://server.com:3000/

    RewriteEngine on
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://server.com:3000/$1" [P,L]
</VirtualHost>
```

Enable the site first before you can request SSL:


key: chroma:document
string_value:
Enable the site first before you can request SSL:

:::warning
Use of the `nocanon` option may [affect the security of your backend](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#proxypass). It's recommended to enable this only if required by your configuration.
_Normally, mod_proxy will canonicalise ProxyPassed URLs. But this may be incompatible with some backends, particularly those that make use of PATH_INFO. The optional nocanon keyword suppresses this and passes the URL path "raw" to the backend. Note that this keyword may affect the security of your backend, as it removes the normal limited protection against URL-based attacks provided by the proxy._
:::

`a2ensite server.com.conf` # this will enable the site. a2ensite is short for "Apache 2 Enable Site"

```
# For SSL
<VirtualHost 192.168.1.100:443>
    ServerName server.com
    DocumentRoot /home/server/public_html

    ProxyPass / http://server.com:3000/ nocanon
    ProxyPassReverse / http://server.com:3000/


key: chroma:document
string_value:
ProxyPass / http://server.com:3000/ nocanon
    ProxyPassReverse / http://server.com:3000/

    RewriteEngine on
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://server.com:3000/$1" [P,L]

    SSLEngine on
    SSLCertificateFile /etc/ssl/virtualmin/170514456861234/ssl.cert
    SSLCertificateKeyFile /etc/ssl/virtualmin/170514456861234/ssl.key
    SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1

    SSLProxyEngine on
    SSLCACertificateFile /etc/ssl/virtualmin/170514456865864/ssl.ca
</VirtualHost>

```

I'm using virtualmin here for my SSL clusters, but you can also use certbot directly or your preferred SSL method. To use SSL:

### Prerequisites

Run the following commands:

`snap install certbot --classic`
`snap apt install python3-certbot-apache` (this will install the apache plugin).

Navigate to the apache sites-available directory:

`cd /etc/apache2/sites-available/`


key: chroma:document
string_value:
Navigate to the apache sites-available directory:

`cd /etc/apache2/sites-available/`

Create server.com.conf if it is not yet already created, containing the above `<virtualhost>` configuration (it should match your case. Modify as necessary). Use the one without the SSL:

Once it's created, run `certbot --apache -d server.com`, this will request and add/create an SSL keys for you as well as create the server.com.le-ssl.conf

# Configuring Ollama Server

On your latest installation of Ollama, make sure that you have setup your api server from the official Ollama reference:

[Ollama FAQ](https://github.com/jmorganca/ollama/blob/main/docs/faq.md)

### TL;DR

The guide doesn't seem to match the current updated service file on linux. So, we will address it here:

Unless when you're compiling Ollama from source, installing with the standard install `curl https://ollama.com/install.sh | sh` creates a file called `ollama.service` in /etc/systemd/system. You can use nano to edit the file:


key: chroma:document
string_value:
```
sudo nano /etc/systemd/system/ollama.service
```

Add the following lines:

```
Environment="OLLAMA_HOST=0.0.0.0:11434" # this line is mandatory. You can also specify
```

For instance:

```
[Unit]
Description=Ollama Service
After=network-online.target

[Service]
ExecStart=/usr/local/bin/ollama serve
Environment="OLLAMA_HOST=0.0.0.0:11434" # this line is mandatory. You can also specify 192.168.254.109:DIFFERENT_PORT, format
Environment="OLLAMA_ORIGINS=http://192.168.254.106:11434,https://models.server.city" # this line is optional
User=ollama
Group=ollama
Restart=always
RestartSec=3
Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/s>

[Install]
WantedBy=default.target
```

Save the file by pressing CTRL+S, then press CTRL+X


key: chroma:document
string_value:
[Install]
WantedBy=default.target
```

Save the file by pressing CTRL+S, then press CTRL+X

When your computer restarts, the Ollama server will now be listening on the IP:PORT you specified, in this case 0.0.0.0:11434, or 192.168.254.106:11434 (whatever your local IP address is). Make sure that your router is correctly configured to serve pages from that local IP by forwarding 11434 to your local IP server.

# Ollama Model Configuration

## For the Ollama model configuration, use the following Apache VirtualHost setup

Navigate to the apache sites-available directory:

`cd /etc/apache2/sites-available/`

`nano models.server.city.conf` # match this with your ollama server domain

Add the follwoing virtualhost containing this example (modify as needed):

```


key: chroma:document
string_value:
Add the follwoing virtualhost containing this example (modify as needed):

```

# Assuming you have a website hosting this UI at "models.server.city"
<IfModule mod_ssl.c>
    <VirtualHost 192.168.254.109:443>
        DocumentRoot "/var/www/html/"
        ServerName models.server.city
        <Directory "/var/www/html/">
            Options None
            Require all granted
        </Directory>

        ProxyRequests Off
        ProxyPreserveHost On
        ProxyAddHeaders On
        SSLProxyEngine on

        ProxyPass / http://server.city:1000/ nocanon # or port 11434
        ProxyPassReverse / http://server.city:1000/ # or port 11434

        SSLCertificateFile /etc/letsencrypt/live/models.server.city/fullchain.pem
        SSLCertificateKeyFile /etc/letsencrypt/live/models.server.city/privkey.pem
        Include /etc/letsencrypt/options-ssl-apache.conf
    </VirtualHost>
</IfModule>
```


key: chroma:document
string_value:
You may need to enable the site first (if you haven't done so yet) before you can request SSL:

`a2ensite models.server.city.conf`

#### For the SSL part of Ollama server

Run the following commands:

Navigate to the apache sites-available directory:

`cd /etc/apache2/sites-available/`
`certbot --apache -d server.com`

```
<VirtualHost 192.168.254.109:80>
    DocumentRoot "/var/www/html/"
    ServerName models.server.city
    <Directory "/var/www/html/">
        Options None
        Require all granted
    </Directory>

    ProxyRequests Off
    ProxyPreserveHost On
    ProxyAddHeaders On
    SSLProxyEngine on

    ProxyPass / http://server.city:1000/ nocanon # or port 11434
    ProxyPassReverse / http://server.city:1000/ # or port 11434

    RewriteEngine on
    RewriteCond %{SERVER_NAME} =models.server.city
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

```

Don't forget to restart/reload Apache with `systemctl reload apache2`


key: chroma:document
string_value:
```

Don't forget to restart/reload Apache with `systemctl reload apache2`

Open your site at https://server.com!

**Congratulations**, your _**Open-AI-like Chat-GPT style UI**_ is now serving AI with RAG, RBAC and multimodal features! Download Ollama models if you haven't yet done so!

If you encounter any misconfiguration or errors, please file an issue or engage with our discussion. There are a lot of friendly developers here to assist you.

Let's make this UI much more user friendly for everyone!

Thanks for making open-webui your UI Choice for AI!

This doc is made by **Bob Reyes**, your **Open-WebUI** fan from the Philippines.


key: chroma:document
string_value:
---
sidebar_position: 4000
title: "🪶 Apache Tika Extraction"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

## 🪶 Apache Tika Extraction

This documentation provides a step-by-step guide to integrating Apache Tika with Open WebUI. Apache Tika is a content analysis toolkit that can be used to detect and extract metadata and text content from over a thousand different file types. All of these file types can be parsed through a single interface, making Tika useful for search engine indexing, content analysis, translation, and much more.

Prerequisites
------------

* Open WebUI instance
* Docker installed on your system
* Docker network set up for Open WebUI

Integration Steps
----------------

### Step 1: Create a Docker Compose File or Run the Docker Command for Apache Tika


key: chroma:document
string_value:
### Step 1: Create a Docker Compose File or Run the Docker Command for Apache Tika

You have two options to run Apache Tika:

**Option 1: Using Docker Compose**

Create a new file named `docker-compose.yml` in the same directory as your Open WebUI instance. Add the following configuration to the file:

```yml
services:
  tika:
    image: apache/tika:latest-full
    container_name: tika
    ports:
      - "9998:9998"
    restart: unless-stopped
```

Run the Docker Compose file using the following command:

```bash
docker-compose up -d
```

**Option 2: Using Docker Run Command**

Alternatively, you can run Apache Tika using the following Docker command:

```bash
docker run -d --name tika \
  -p 9998:9998 \
  -restart unless-stopped \
  apache/tika:latest-full
```

Note that if you choose to use the Docker run command, you'll need to specify the `--network` flag if you want to run the container in the same network as your Open WebUI instance.


key: chroma:document
string_value:
### Step 2: Configure Open WebUI to Use Apache Tika

To use Apache Tika as the context extraction engine in Open WebUI, follow these steps:

* Log in to your Open WebUI instance.
* Navigate to the `Admin Panel` settings menu.
* Click on `Settings`.
* Click on the `Documents` tab.
* Change the `Default` content extraction engine dropdown to `Tika`.
* Update the context extraction engine URL to `http://tika:9998`.
* Save the changes.

 Verifying Apache Tika in Docker
=====================================

To verify that Apache Tika is working correctly in a Docker environment, you can follow these steps:

### 1. Start the Apache Tika Docker Container

First, ensure that the Apache Tika Docker container is running. You can start it using the following command:

```bash
docker run -p 9998:9998 apache/tika
```

This command starts the Apache Tika container and maps port 9998 from the container to port 9998 on your local machine.

### 2. Verify the Server is Running


key: chroma:document
string_value:
### 2. Verify the Server is Running

You can verify that the Apache Tika server is running by sending a GET request:

```bash
curl -X GET http://localhost:9998/tika
```

This command should return the following response:

```
This is Tika Server. Please PUT
```

### 3. Verify the Integration

Alternatively, you can also try sending a file for analysis to test the integration. You can test Apache Tika by sending a file for analysis using the `curl` command:

```bash
curl -T test.txt http://localhost:9998/tika
```

Replace `test.txt` with the path to a text file on your local machine.

Apache Tika will respond with the detected metadata and content type of the file.

### Using a Script to Verify Apache Tika


key: chroma:document
string_value:
### Using a Script to Verify Apache Tika

If you want to automate the verification process, this script sends a file to Apache Tika and checks the response for the expected metadata. If the metadata is present, the script will output a success message along with the file's metadata; otherwise, it will output an error message and the response from Apache Tika.

```python
import requests

def verify_tika(file_path, tika_url):
    try:
        # Send the file to Apache Tika and verify the output
        response = requests.put(tika_url, files={'file': open(file_path, 'rb')})


key: chroma:document
string_value:
if response.status_code == 200:
            print("Apache Tika successfully analyzed the file.")
            print("Response from Apache Tika:")
            print(response.text)
        else:
            print("Error analyzing the file:")
            print(f"Status code: {response.status_code}")
            print(f"Response from Apache Tika: {response.text}")
    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    file_path = "test.txt"  # Replace with the path to your file
    tika_url = "http://localhost:9998/tika"

    verify_tika(file_path, tika_url)
```

Instructions to run the script:

### Prerequisites

* Python 3.x must be installed on your system
* `requests` library must be installed (you can install it using pip: `pip install requests`)
* Apache Tika Docker container must be running (use `docker run -p 9998:9998 apache/tika` command)
* Replace `"test.txt"` with the path to the file you want to send to Apache Tika


key: chroma:document
string_value:
### Running the Script

1. Save the script as `verify_tika.py` (e.g., using a text editor like Notepad or Sublime Text)
2. Open a terminal or command prompt
3. Navigate to the directory where you saved the script (using the `cd` command)
4. Run the script using the following command: `python verify_tika.py`
5. The script will output a message indicating whether Apache Tika is working correctly

Note: If you encounter any issues, ensure that the Apache Tika container is running correctly and that the file is being sent to the correct URL.

### Conclusion

By following these steps, you can verify that Apache Tika is working correctly in a Docker environment. You can test the setup by sending a file for analysis, verifying the server is running with a GET request, or use a script to automate the process. If you encounter any issues, ensure that the Apache Tika container is running correctly and that the file is being sent to the correct URL.

Troubleshooting
--------------


key: chroma:document
string_value:
Troubleshooting
--------------

* Make sure the Apache Tika service is running and accessible from the Open WebUI instance.
* Check the Docker logs for any errors or issues related to the Apache Tika service.
* Verify that the context extraction engine URL is correctly configured in Open WebUI.

Benefits of Integration
----------------------

Integrating Apache Tika with Open WebUI provides several benefits, including:

* **Improved Metadata Extraction**: Apache Tika's advanced metadata extraction capabilities can help you extract accurate and relevant data from your files.
* **Support for Multiple File Formats**: Apache Tika supports a wide range of file formats, making it an ideal solution for organizations that work with diverse file types.
* **Enhanced Content Analysis**: Apache Tika's advanced content analysis capabilities can help you extract valuable insights from your files.

Conclusion
----------


key: chroma:document
string_value:
Conclusion
----------

Integrating Apache Tika with Open WebUI is a straightforward process that can improve the metadata extraction capabilities of your Open WebUI instance. By following the steps outlined in this documentation, you can easily set up Apache Tika as a context extraction engine for Open WebUI.


key: chroma:document
string_value:
---
sidebar_position: 400
title: "🔗 API Endpoints"
---

This guide provides essential information on how to interact with the API endpoints effectively to achieve seamless integration and automation using our models. Please note that this is an experimental setup and may undergo future updates for enhancement.

## Authentication

To ensure secure access to the API, authentication is required 🛡️. You can authenticate your API requests using the Bearer Token mechanism. Obtain your API key from **Settings > Account** in the Open WebUI, or alternatively, use a JWT (JSON Web Token) for authentication.

## Notable API Endpoints

### 📜 Retrieve All Models

- **Endpoint**: `GET /api/models`
- **Description**: Fetches all models created or added via Open WebUI.
- **Example**:

  ```bash
  curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:3000/api/models
  ```

### 💬 Chat Completions


key: chroma:document
string_value:
### 💬 Chat Completions

- **Endpoint**: `POST /api/chat/completions`
- **Description**: Serves as an OpenAI API compatible chat completion endpoint for models on Open WebUI including Ollama models, OpenAI models, and Open WebUI Function models.
- **Example**:

  ```bash
  curl -X POST http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "llama3.1",
        "messages": [
          {
            "role": "user",
            "content": "Why is the sky blue?"
          }
        ]
      }'
  ```

### 🧩 Retrieval Augmented Generation (RAG)

The Retrieval Augmented Generation (RAG) feature allows you to enhance responses by incorporating data from external sources. Below, you will find the methods for managing files and knowledge collections via the API, and how to use them in chat completions effectively.

#### Uploading Files


key: chroma:document
string_value:
#### Uploading Files

To utilize external data in RAG responses, you first need to upload the files. The content of the uploaded file is automatically extracted and stored in a vector database.

- **Endpoint**: `POST /api/v1/files/`
- **Curl Example**:

  ```bash
  curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json" \
  -F "file=@/path/to/your/file" http://localhost:3000/api/v1/files/
  ```

- **Python Example**:

  ```python
  import requests
  
  def upload_file(token, file_path):
      url = 'http://localhost:3000/api/v1/files/'
      headers = {
          'Authorization': f'Bearer {token}',
          'Accept': 'application/json'
      }
      files = {'file': open(file_path, 'rb')}
      response = requests.post(url, headers=headers, files=files)
      return response.json()
  ```

#### Adding Files to Knowledge Collections

After uploading, you can group files into a knowledge collection or reference them individually in chats.


key: chroma:document
string_value:
- **Endpoint**: `POST /api/v1/knowledge/{id}/file/add`
- **Curl Example**:

  ```bash
  curl -X POST http://localhost:3000/api/v1/knowledge/{knowledge_id}/file/add \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "your-file-id-here"}'
  ```

- **Python Example**:

  ```python
  import requests

  def add_file_to_knowledge(token, knowledge_id, file_id):
      url = f'http://localhost:3000/api/v1/knowledge/{knowledge_id}/file/add'
      headers = {
          'Authorization': f'Bearer {token}',
          'Content-Type': 'application/json'
      }
      data = {'file_id': file_id}
      response = requests.post(url, headers=headers, json=data)
      return response.json()
  ```

#### Using Files and Collections in Chat Completions

You can reference both individual files or entire collections in your RAG queries for enriched responses.

##### Using an Individual File in Chat Completions


key: chroma:document
string_value:
##### Using an Individual File in Chat Completions

This method is beneficial when you want to focus the chat model's response on the content of a specific file.

- **Endpoint**: `POST /api/chat/completions`
- **Curl Example**:

  ```bash
  curl -X POST http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4-turbo",
        "messages": [
          {"role": "user", "content": "Explain the concepts in this document."}
        ],
        "files": [
          {"type": "file", "id": "your-file-id-here"}
        ]
      }'
  ```

- **Python Example**:

  ```python
  import requests


key: chroma:document
string_value:
- **Python Example**:

  ```python
  import requests

  def chat_with_file(token, model, query, file_id):
      url = 'http://localhost:3000/api/chat/completions'
      headers = {
          'Authorization': f'Bearer {token}',
          'Content-Type': 'application/json'
      }
      payload = {
          'model': model,
          'messages': [{'role': 'user', 'content': query}],
          'files': [{'type': 'file', 'id': file_id}]
      }
      response = requests.post(url, headers=headers, json=payload)
      return response.json()
  ```

##### Using a Knowledge Collection in Chat Completions

Leverage a knowledge collection to enhance the response when the inquiry may benefit from a broader context or multiple documents.

- **Endpoint**: `POST /api/chat/completions`
- **Curl Example**:


key: chroma:document
string_value:
- **Endpoint**: `POST /api/chat/completions`
- **Curl Example**:

  ```bash
  curl -X POST http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4-turbo",
        "messages": [
          {"role": "user", "content": "Provide insights on the historical perspectives covered in the collection."}
        ],
        "files": [
          {"type": "collection", "id": "your-collection-id-here"}
        ]
      }'
  ```

- **Python Example**:


key: chroma:document
string_value:
- **Python Example**:

  ```python
  import requests
  
  def chat_with_collection(token, model, query, collection_id):
      url = 'http://localhost:3000/api/chat/completions'
      headers = {
          'Authorization': f'Bearer {token}',
          'Content-Type': 'application/json'
      }
      payload = {
          'model': model,
          'messages': [{'role': 'user', 'content': query}],
          'files': [{'type': 'collection', 'id': collection_id}]
      }
      response = requests.post(url, headers=headers, json=payload)
      return response.json()
  ```

These methods enable effective utilization of external knowledge via uploaded files and curated knowledge collections, enhancing chat applications' capabilities using the Open WebUI API. Whether using files individually or within collections, you can customize the integration based on your specific needs.

## Advantages of Using Open WebUI as a Unified LLM Provider


key: chroma:document
string_value:
## Advantages of Using Open WebUI as a Unified LLM Provider

Open WebUI offers a myriad of benefits, making it an essential tool for developers and businesses alike:

- **Unified Interface**: Simplify your interactions with different LLMs through a single, integrated platform.
- **Ease of Implementation**: Quick start integration with comprehensive documentation and community support.

## Swagger Documentation Links

:::important
Make sure to set the `ENV` environment variable to `dev` in order to access the Swagger documentation for any of these services. Without this configuration, the documentation will not be available.
:::

Access detailed API documentation for different services provided by Open WebUI:

| Application | Documentation Path      |
|-------------|-------------------------|
| Main        | `/docs`                 |


key: chroma:document
string_value:
By following these guidelines, you can swiftly integrate and begin utilizing the Open WebUI API. Should you encounter any issues or have questions, feel free to reach out through our Discord Community or consult the FAQs. Happy coding! 🌟


key: chroma:document
string_value:
---
sidebar_position: 1
title: "🏺 Artifacts"
---


# What are Artifacts and how do I use them in Open WebUI?

Artifacts in Open WebUI are an innovative feature inspired by Claude.AI's Artifacts, allowing you to interact with significant and standalone content generated by an LLM within a chat. They enable you to view, modify, build upon, or reference substantial pieces of content separately from the main conversation, making it easier to work with complex outputs and ensuring that you can revisit important information later.

## When does Open WebUI use Artifacts?

Open WebUI creates an Artifact when the generated content meets specific criteria tailored to our platform:

1. **Renderable**: To be displayed as an Artifact, the content must be in a format that Open WebUI supports for rendering. This includes:


key: chroma:document
string_value:
* Single-page HTML websites
* Scalable Vector Graphics (SVG) images
* Complete webpages, which include HTML, Javascript, and CSS all in the same Artifact. Do note that HTML is required if generating a complete webpage.
* ThreeJS Visualizations and other JavaScript visualization libraries such as D3.js.

Other content types like Documents (Markdown or Plain Text), Code snippets, and React components are not rendered as Artifacts by Open WebUI.

## How does Open WebUI's model create Artifacts?

To use artifacts in Open WebUI, a model must provide content that triggers the rendering process to create an artifact. This involves generating valid HTML, SVG code, or other supported formats for artifact rendering. When the generated content meets the criteria mentioned above, Open WebUI will display it as an interactive Artifact.

## How do I use Artifacts in Open WebUI?


key: chroma:document
string_value:
## How do I use Artifacts in Open WebUI?

When Open WebUI creates an Artifact, you'll see the content displayed in a dedicated Artifacts window to the right side of the main chat. Here's how to interact with Artifacts:

* **Editing and iterating**: Ask an LLM within the chat to edit or iterate on the content, and these updates will be displayed directly in the Artifact window. You can switch between versions using the version selector at the bottom left of the Artifact. Each edit creates a new version, allowing you to track changes using the version selector.
* **Updates**: Open WebUI may update an existing Artifact based on your messages. The Artifact window will display the latest content.
* **Actions**: Access additional actions for the Artifact, such as copying the content or opening the artifact in full screen, located in the lower right corner of the Artifact.

## Editing Artifacts

1. **Targeted Updates**: Describe what you want changed and where. For example:


key: chroma:document
string_value:
1. **Targeted Updates**: Describe what you want changed and where. For example:

* "Change the color of the bar in the chart from blue to red."
* "Update the title of the SVG image to 'New Title'."

2. **Full Rewrites**: Request major changes affecting most of the content for substantial restructuring or multiple section updates. For example:

* "Rewrite this single-page HTML website to be a landing page instead."
* "Redesign this SVG so that it's animated using ThreeJS."

**Best Practices**:

* Be specific about which part of the Artifact you want to change.
* Reference unique identifying text around your desired change for targeted updates.
* Consider whether a small update or full rewrite is more appropriate for your needs.

## Use Cases

Artifacts in Open WebUI enable various teams to create high-quality work products quickly and efficiently. Here are some examples tailored to our platform:


key: chroma:document
string_value:
* **Designers**:
  * Create interactive SVG graphics for UI/UX design.
  * Design single-page HTML websites or landing pages.
* **Developers**: Create simple HTML prototypes or generate SVG icons for projects.
* **Marketers**:
  * Design campaign landing pages with performance metrics.
  * Create SVG graphics for ad creatives or social media posts.

## Examples of Projects you can create with Open WebUI's Artifacts

Artifacts in Open WebUI enable various teams and individuals to create high-quality work products quickly and efficiently. Here are some examples tailored to our platform, showcasing the versatility of artifacts and inspiring you to explore their potential:

1. **Interactive Visualizations**

* Components used: ThreeJS, D3.js, and SVG
* Benefits: Create immersive data stories with interactive visualizations. Open WebUI's Artifacts enable you to switch between versions, making it easier to test different visualization approaches and track changes.


key: chroma:document
string_value:
Example Project: Build an interactive line chart using ThreeJS to visualize stock prices over time. Update the chart's colors and scales in separate versions to compare different visualization strategies.

2. **Single-Page Web Applications**

* Components used: HTML, CSS, and JavaScript
* Benefits: Develop single-page web applications directly within Open WebUI. Edit and iterate on the content using targeted updates and full rewrites.

Example Project: Design a to-do list app with a user interface built using HTML and CSS. Use JavaScript to add interactive functionality. Update the app's layout and UI/UX using targeted updates and full rewrites.

3. **Animated SVG Graphics**

* Components used: SVG and ThreeJS
* Benefits: Create engaging animated SVG graphics for marketing campaigns, social media, or web design. Open WebUI's Artifacts enable you to edit and iterate on the graphics in a single window.


key: chroma:document
string_value:
Example Project: Design an animated SVG logo for a company brand. Use ThreeJS to add animation effects and Open WebUI's targeted updates to refine the logo's colors and design.

4. **Webpage Prototypes**

* Components used: HTML, CSS, and JavaScript
* Benefits: Build and test webpage prototypes directly within Open WebUI. Switch between versions to compare different design approaches and refine the prototype.

Example Project: Develop a prototype for a new e-commerce website using HTML, CSS, and JavaScript. Use Open WebUI's targeted updates to refines the navigation, layout, and UI/UX.

5. **Interactive Storytelling**

* Components used: HTML, CSS, and JavaScript
* Benefits: Create interactive stories with scrolling effects, animations, and other interactive elements. Open WebUI's Artifacts enable you to refine the story and test different versions.


key: chroma:document
string_value:
Example Project: Build an interactive story about a company's history, using scrolling effects and animations to engage the reader. Use targeted updates to refine the story's narrative and Open WebUI's version selector to test different versions.


key: chroma:document
string_value:
---
sidebar_position: 13
title: "🔰 Customizable Banners"
---

Overview
--------

Open WebUI provides a feature that allows administrators to create customizable banners with persistence in the `config.json` file. These banners can feature options for content, background color (info, warning, error, or success), and dismissibility. Banners are accessible only to logged-in users, ensuring the confidentiality of sensitive information.

Configuring Banners through the Admin Panel
---------------------------------------------

To configure banners through the admin panel, follow these steps:


key: chroma:document
string_value:
To configure banners through the admin panel, follow these steps:

1. Log in to your Open WebUI instance as an administrator.
2. Navigate to the `Admin Panel` -> `Settings` -> `Interface`.
3. Locate the `Banners` option directly above the `Default Prompt Suggestions` option.
4. Click on the `+` icon to add a new banner.
5. Select the banner type and set the banner text as desired.
6. Choose whether the banner is dismissible or not.
7. Set the timestamp for the banner (optional).
8. Press `Save` at the bottom of the page to save the banner.

Configuring Banners through Environment Variables
------------------------------------------------

Alternatively, you can configure banners through environment variables. To do this, you will need to set the `WEBUI_BANNERS` environment variable with a list of dictionaries in the following format:


key: chroma:document
string_value:
```json
[{"id": "string","type": "string [info, success, warning, error]","title": "string","content": "string","dismissible": False,"timestamp": 1000}]
```

For more information on configuring environment variables in Open WebUI, see [Environment Variable Configuration](https://docs.openwebui.com/getting-started/advanced-topics/env-configuration#webui_banners).

Environment Variable Description
---------------------------------

* `WEBUI_BANNERS`:
  * Type: list of dict
  * Default: `[]`
  * Description: List of banners to show to users.

Banner Options
----------------

* `id`: Unique identifier for the banner.
* `type`: Background color of the banner (info, success, warning, error).
* `title`: Title of the banner.
* `content`: Content of the banner.
* `dismissible`: Whether the banner is dismissible or not.
* `timestamp`: Timestamp for the banner (optional).

FAQ
----


key: chroma:document
string_value:
FAQ
----

* Q: Can I configure banners through the admin panel?
A: Yes, you can configure banners through the admin panel by navigating to `Admin Panel` -> `Settings` -> `Interface` and clicking on the `+` icon to add a new banner.
* Q: Can I configure banners through environment variables?
A: Yes, you can configure banners through environment variables by setting the `WEBUI_BANNERS` environment variable with a list of dictionaries.
* Q: What is the format for the `WEBUI_BANNERS` environment variable?
A: The format for the `WEBUI_BANNERS` environment variable is a list of dictionaries with the following keys: `id`, `type`, `title`, `content`, `dismissible`, and `timestamp`.
* Q: Can I make banners dismissible?
A: Yes, you can make banners dismissible by setting the `dismissible` key to `True` in the banner configuration or by toggling dismissibility for a banner within the UI.


key: chroma:document
string_value:
---
sidebar_position: 16
title: "🌐 Browser Search Engine"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# Browser Search Engine Integration

Open WebUI allows you to integrate directly into your web browser. This tutorial will guide you through the process of setting up Open WebUI as a custom search engine, enabling you to execute queries easily from your browser's address bar.

## Setting Up Open WebUI as a Search Engine

### Prerequisites

Before you begin, ensure that:

- You have Chrome or another supported browser installed.
- The `WEBUI_URL` environment variable is set correctly, either using Docker environment variables or in the `.env` file as specified in the [Getting Started](/getting-started/advanced-topics/env-configuration) guide.


key: chroma:document
string_value:
### Step 1: Set the WEBUI_URL Environment Variable

Setting the `WEBUI_URL` environment variable ensures your browser knows where to direct queries.

#### Using Docker Environment Variables

If you are running Open WebUI using Docker, you can set the environment variable in your `docker run` command:

```bash
docker run -d \
  -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  -e WEBUI_URL="https://<your-open-webui-url>" \
  ghcr.io/open-webui/open-webui:main
```

Alternatively, you can add the variable to your `.env` file:

```plaintext
WEBUI_URL=https://<your-open-webui-url>
```

### Step 2: Add Open WebUI as a Custom Search Engine

### For Chrome


key: chroma:document
string_value:
### Step 2: Add Open WebUI as a Custom Search Engine

### For Chrome

1. Open Chrome and navigate to **Settings**.
2. Select **Search engine** from the sidebar, then click on **Manage search engines**.
3. Click **Add** to create a new search engine.
4. Fill in the details as follows:
    - **Search engine**: Open WebUI Search
    - **Keyword**: webui (or any keyword you prefer)
    - **URL with %s in place of query**:

      ```
      https://<your-open-webui-url>/?q=%s
      ```

5. Click **Add** to save the configuration.

### For Firefox

1. Go to Open WebUI in Firefox.
2. Expand the address bar by clicking on it.
3. Click the plus icon that is enclosed in a green circle at the bottom of the expanded address bar. This adds Open WebUI's search to the search engines in your preferences.

Alternatively:

1. Go to Open WebUI in Firefox.
2. Right-click on the address bar.
3. Select "Add Open WebUI" (or similar) from the context menu.

### Optional: Using Specific Models


key: chroma:document
string_value:
### Optional: Using Specific Models

If you wish to utilize a specific model for your search, modify the URL format to include the model ID:

```
https://<your-open-webui-url>/?models=<model_id>&q=%s
```

**Note:** The model ID will need to be URL-encoded. Special characters like spaces or slashes need to be encoded (e.g., `my model` becomes `my%20model`).

## Example Usage

Once the search engine is set up, you can perform searches directly from the address bar. Simply type your chosen keyword followed by your query:

```
webui your search query
```

This command will redirect you to the Open WebUI interface with your search results.

## Troubleshooting

If you encounter any issues, check the following:


key: chroma:document
string_value:
## Troubleshooting

If you encounter any issues, check the following:

- Ensure the `WEBUI_URL` is correctly configured and points to a valid Open WebUI instance.
- Double-check that the search engine URL format is correctly entered in your browser settings.
- Confirm your internet connection is active and that the Open WebUI service is running smoothly.


key: chroma:document
string_value:
---
sidebar_position: 4
title: "⚙️ Chat Parameters"
---

Within Open WebUI, there are three levels to setting a **System Prompt** and **Advanced Parameters**: per-chat basis, per-model basis, and per-account basis. This hierarchical system allows for flexibility while maintaining structured administration and control.

## System Prompt and Advanced Parameters Hierarchy Chart


key: chroma:document
string_value:
## System Prompt and Advanced Parameters Hierarchy Chart

| **Level** | **Definition** | **Modification Permissions** | **Override Capabilities** |
| --- | --- | --- | --- |
| **Per-Chat** | System prompt and advanced parameters for a specific chat instance | Users can modify, but cannot override model-specific settings | Restricted from overriding model-specific settings |
| **Per-Model** | Default system prompt and advanced parameters for a specific model | Administrators can set, Users cannot modify | Admin-specific settings take precedence, User settings can be overridden |
| **Per-Account** | Default system prompt and advanced parameters for a specific user account | Users can set, but may be overridden by model-specific settings | User settings can be overridden by model-specific settings |

### 1. **Per-chat basis:**


key: chroma:document
string_value:
### 1. **Per-chat basis:**

- **Description**: The per-chat basis setting refers to the system prompt and advanced parameters configured for a specific chat instance. These settings are only applicable to the current conversation and do not affect future chats.
- **How to set**: Users can modify the system prompt and advanced parameters for a specific chat instance within the right-hand sidebar's **Chat Controls** section in Open WebUI.
- **Override capabilities**: Users are restricted from overriding the **System Prompt** or specific **Advanced Parameters** already set by an administrator on a per-model basis (**#2**). This ensures consistency and adherence to model-specific settings.


key: chroma:document
string_value:
<details>
<summary>Example Use Case</summary>
:::tip **Per-chat basis**:
Suppose a user wants to set a custom system prompt for a specific conversation. They can do so by accessing the **Chat Controls** section and modifying the **System Prompt** field. These changes will only apply to the current chat session.
:::
</details>

### 2. **Per-model basis:**


key: chroma:document
string_value:
- **Description**: The per-model basis setting refers to the default system prompt and advanced parameters configured for a specific model. These settings are applicable to all chat instances using that model.
- **How to set**: Administrators can set the default system prompt and advanced parameters for a specific model within the **Models** section of the **Workspace** in Open WebUI.
- **Override capabilities**: **User** accounts are restricted from modifying the **System Prompt** or specific **Advanced Parameters** on a per-model basis (**#3**). This restriction prevents users from inappropriately altering default settings.


key: chroma:document
string_value:
- **Context length preservation:** When a model's **System Prompt** or specific **Advanced Parameters** are set manually in the **Workspace** section by an Admin, said **System Prompt** or manually set **Advanced Parameters** cannot be overridden or adjusted on a per-account basis within the **General** settings or **Chat Controls** section by a **User** account. This ensures consistency and prevents excessive reloading of the model whenever a user's context length setting changes.
- **Model precedence:** If a model's **System Prompt** or specific **Advanced Parameters** value is pre-set in the Workspace section by an Admin, any context length changes made by a **User** account in the **General** settings or **Chat Controls** section will be disregarded, maintaining the pre-configured value for that model. Be advised that parameters left untouched by an **Admin** account can still be manually adjusted by a **User** account on a per-account or per-chat basis.


key: chroma:document
string_value:
<details>
<summary>Example Use Case</summary>
:::tip **Per-model basis**:
Suppose an administrator wants to set a default system prompt for a specific model. They can do so by accessing the **Models** section and modifying the **System Prompt** field for the corresponding model. Any chat instances using this model will automatically use the model's system prompt and advanced parameters.
:::
</details>

### 3. **Per-account basis:**


key: chroma:document
string_value:
### 3. **Per-account basis:**

- **Description**: The per-account basis setting refers to the default system prompt and advanced parameters configured for a specific user account. Any user-specific changes can serve as a fallback in situations where lower-level settings aren't defined.
- **How to set**: Users can set their own system prompt and advanced parameters for their account within the **General** section of the **Settings** menu in Open WebUI.
- **Override capabilities**: Users have the ability to set their own system prompt on their account, but they must be aware that such parameters can still be overridden if an administrator has already set the **System Prompt** or specific **Advanced Parameters** on a per-model basis for the particular model being used.


key: chroma:document
string_value:
<details>
<summary>Example Use Case</summary>
:::tip **Per-account basis**:
Suppose a user wants to set their own system prompt for their account. They can do so by accessing the **Settings** menu and modifying the **System Prompt** field.
:::
</details>

## **Optimize System Prompt Settings for Maximum Flexibility**

:::tip **Bonus Tips**
**This tip applies for both administrators and user accounts. To achieve maximum flexibility with your system prompts, we recommend considering the following setup:**

- Assign your primary System Prompt (**i.e., to give an LLM a defining character**) you want to use in your **General** settings **System Prompt** field. This sets it on a per-account level and allows it to work as the system prompt across all your LLMs without requiring adjustments within a model from the **Workspace** section.


key: chroma:document
string_value:
- For your secondary System Prompt (**i.e, to give an LLM a task to perform**), choose whether to place it in the **System Prompt** field within the **Chat Controls** sidebar (on a per-chat basis) or the **Models** section of the **Workspace** section (on a per-model basis) for Admins, allowing you to set them directly. This allows your account-level system prompt to work in conjunction with either the per-chat level system prompt provided by **Chat Controls**, or the per-model level system prompt provided by **Models**.


key: chroma:document
string_value:
- As an administrator, you should assign your LLM parameters on a per-model basis using **Models** section for optimal flexibility. For both of these secondary System Prompts, ensure to set them in a manner that maximizes flexibility and minimizes required adjustments across different per-account or per-chat instances. It is essential for both your Admin account as well as all User accounts to understand the priority order by which system prompts within **Chat Controls** and the **Models** section will be applied to the **LLM**.
:::


key: chroma:document
string_value:
---
sidebar_position: 4
title: "🗨️ Chat Sharing"
---

### Enabling Community Sharing

To enable community sharing, follow these steps:

1. Navigate to the **Admin Panel** page as an **Admin**.
2. Click on the **Settings** tab.
3. Toggle on **Enable Community Sharing** within the **General** settings tab.

:::note
**Note:** Only Admins can toggle the **Enable Community Sharing** option. If this option is toggled off, users and Admins will not see the **Share to Open WebUI Community** option for sharing their chats. Community sharing must be enabled by an Admin for users to share chats to the Open WebUI community.
:::

This will enable community sharing for all users on your Open WebUI instance.

### Sharing Chats

To share a chat:


key: chroma:document
string_value:
### Sharing Chats

To share a chat:

1. Select the chat conversation you want to share.
2. Click on the 3-dots that appear when hovering the mouse pointer above the desired chat.
3. Then click on the **Share** option.
4. Select either **Share to Open WebUI Community** (if **Enable Community Sharing** is toggled on by an **Admin**) or **Copy Link**.

#### Sharing to Open WebUI Community

When you select `Share to Open WebUI Community`:

* A new tab will open, allowing you to upload your chat as a snapshot to the Open WebUI community website (https://openwebui.com/chats/upload).
* You can control who can view your uploaded chat by choosing from the following access settings:
  * **Private**: Only you can access this chat.
  * **Public**: Anyone on the internet can view the messages displayed in the chat snapshot.
  * **Public, Full History**: Anyone on the internet can view the full regeneration history of your chat.


key: chroma:document
string_value:
:::note
Note: You can change the permission level of your shared chats on the community platform at any time from your openwebui.com account.

**Currently, shared chats on the community website cannot be found through search. However, future updates are planned to allow public chats to be discoverable by the public if their permission is set to `Public` or `Public, Full History`.**
:::

Example of a shared chat to the community platform website: https://openwebui.com/c/iamg30/5e3c569f-905e-4d68-a96d-8a99cc65c90f

#### Copying a Share Link

When you select `Copy Link`, a unique share link is generated that can be shared with others.

**Important Considerations:**


key: chroma:document
string_value:
**Important Considerations:**

* The shared chat will only include messages that existed at the time the link was created. Any new messages sent within the chat after the link is generated will not be included, unless the link is deleted and updated with a new link.
* The generated share link acts as a static snapshot of the chat at the time the link was generated.
* To view the shared chat, users must:
  1. Have an account on the Open WebUI instance where the link was generated.
  2. Be signed in to their account on that instance.
* If a user tries to access the shared link without being signed in, they will be redirected to the login page to log in before they can view the shared chat.

### Viewing Shared Chats

To view a shared chat:


key: chroma:document
string_value:
### Viewing Shared Chats

To view a shared chat:

1. Ensure you are signed in to an account on the Open WebUI instance where the chat was shared.
2. Click on the shared link provided to you.
3. The chat will be displayed in a read-only format.
4. If the Admin of the Open WebUI instance from which the shared link was shared has Text-to-Speech set up, there may be an audio button for messages to be read aloud to you (situational).

### Updating Shared Chats

To update a shared chat:

1. Select the chat conversation you want to share.
2. Click on the 3-dots that appear when hovering the mouse pointer above the desired chat.
3. Click on the **Share** option.
4. The **Share Chat** Modal should look different if you've shared a chat before.

The **Share Chat** Modal includes the following options:


key: chroma:document
string_value:
The **Share Chat** Modal includes the following options:

* **before**: Opens a new tab to view the previously shared chat from the share link.
* **delete this link**: Deletes the shared link of the chat and presents the initial share chat modal.
* **Share to Open WebUI Community**: Opens a new tab for https://openwebui.com/chats/upload with the chat ready to be shared as a snapshot.
* **Update and Copy Link**: Updates the snapshot of the chat of the previously shared chat link and copies it to your device's clipboard.

### Deleting Shared Chats

To delete a shared chat link:

1. Select the chat conversation you want to delete the shared link for.
2. Click on the 3-dots that appear when hovering the mouse pointer above the desired chat.
3. Click on the **Share** option.
4. The **Share Chat** Modal should look different if you've shared a chat before.
5. Click on **delete this link**.


key: chroma:document
string_value:
Once deleted, the shared link will no longer be valid, and users will not be able to view the shared chat.

:::note
**Note:** Chats shared to the community platform cannot be deleted. To change the access level of a chat shared to the community platform:
:::

1. Log in to your Open WebUI account on openwebui.com.
2. Click on your account username at the top right of the website.
3. Click on **Chats**.
4. Click on the chat you wish to change permission access for.
5. Scroll to the bottom of the chat and update its permission level.
6. Click the **Update Chat** button.


key: chroma:document
string_value:
# Install with Conda

1. **Create a Conda Environment:**

   ```bash
   conda create -n open-webui python=3.11
   ```

2. **Activate the Environment:**

   ```bash
   conda activate open-webui
   ```

3. **Install Open WebUI:**

   ```bash
   pip install open-webui
   ```

4. **Start the Server:**

   ```bash
   open-webui serve
   ```


key: chroma:document
string_value:
---
sidebar_position: 0
title: "🚧 Server Connectivity Issues"
---

We're here to help you get everything set up and running smoothly. Below, you'll find step-by-step instructions tailored for different scenarios to solve common connection issues with Ollama and external servers like Hugging Face.

## 🌟 Connection to Ollama Server

### 🚀 Accessing Ollama from Open WebUI

Struggling to connect to Ollama from Open WebUI? It could be because Ollama isn't listening on a network interface that allows external connections. Let's sort that out:

1. **Configure Ollama to Listen Broadly** 🎧:
   Set `OLLAMA_HOST` to `0.0.0.0` to make Ollama listen on all network interfaces.

2. **Update Environment Variables**:
   Ensure that the `OLLAMA_HOST` is accurately set within your deployment environment.

3. **Restart Ollama**🔄:
   A restart is needed for the changes to take effect.

💡 After setting up, verify that Ollama is accessible by visiting the WebUI interface.


key: chroma:document
string_value:
💡 After setting up, verify that Ollama is accessible by visiting the WebUI interface.

For more detailed instructions on configuring Ollama, please refer to the [Ollama's Official Documentation](https://github.com/ollama/ollama/blob/main/docs/faq.md#setting-environment-variables-on-linux).

### 🐳 Docker Connection Error

If you're seeing a connection error when trying to access Ollama, it might be because the WebUI docker container can't talk to the Ollama server running on your host. Let's fix that:

1. **Adjust the Network Settings** 🛠️:
   Use the `--network=host` flag in your Docker command. This links your container directly to your host's network.

2. **Change the Port**:
   Remember that the internal port changes from 3000 to 8080.


key: chroma:document
string_value:
2. **Change the Port**:
   Remember that the internal port changes from 3000 to 8080.

**Example Docker Command**:
```bash
docker run -d --network=host -v open-webui:/app/backend/data -e OLLAMA_BASE_URL=http://127.0.0.1:11434 --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```
🔗 After running the above, your WebUI should be available at `http://localhost:8080`.

## 🔒 SSL Connection Issue with Hugging Face

Encountered an SSL error? It could be an issue with the Hugging Face server. Here's what to do:

1. **Check Hugging Face Server Status**:
   Verify if there's a known outage or issue on their end.

2. **Switch Endpoint**:
   If Hugging Face is down, switch the endpoint in your Docker command.


key: chroma:document
string_value:
2. **Switch Endpoint**:
   If Hugging Face is down, switch the endpoint in your Docker command.

**Example Docker Command for Connected Issues**:
```bash
docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```

## 🍏 Podman on MacOS

Running on MacOS with Podman? Here's how to ensure connectivity:

1. **Enable Host Loopback**:
   Use `--network slirp4netns:allow_host_loopback=true` in your command.

2. **Set OLLAMA_BASE_URL**:
   Ensure it points to `http://host.containers.internal:11434`.

**Example Podman Command**:
```bash
podman run -d --network slirp4netns:allow_host_loopback=true -p 3000:8080 -e OLLAMA_BASE_URL=http://host.containers.internal:11434 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```


key: chroma:document
string_value:
---
sidebar_position: 13
title: "⚛️ Continue.dev VSCode Extension with Open WebUI"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# Integrating Continue.dev VSCode Extension with Open WebUI

### Download Extension

You can download the VSCode extension here on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Continue.continue)

Once installed you should now have a 'continue' tab in the side bar.

Open this. Down at the bottom right you should see a settings icon (looks like a cog).

Once you click on the settings icon a `config.json` should open up in the editor.

Here you'll be able to configure continue to use Open WebUI.

---

Currently the 'ollama' provider does not support authentication so we cannot use this provider with Open WebUI.


key: chroma:document
string_value:
However Ollama and Open WebUI both have compatibily with OpenAI API spec. You can see a blog post from Ollama [here](https://ollama.com/blog/openai-compatibility) on this.

We can still setup Continue to use the openai provider which will allow us to use Open WebUI's authentication token.

---

## Config

In `config.json` all you will need to do is add/change the following options.

### Change provider to openai

```json
"provider": "openai"
```

### Add or update apiBase

Set this to your Open Web UI domain + /ollama/v1 on the end.

```json
"apiBase": "http://localhost:3000/ollama/v1" #If you followed Getting Started Docker
```

### Add apiKey

```json
"apiKey": "sk-79970662256d425eb274fc4563d4525b" # Replace with your API key
```

You can find and generate your api key from Open WebUI -> Settings -> Account -> API Keys

You'll want to copy the "API Key" (this starts with sk-)

## Example Config


key: chroma:document
string_value:
You'll want to copy the "API Key" (this starts with sk-)

## Example Config

Here is a base example of config.json using Open WebUI via an openai provider. Using Granite Code as the model.
Make sure you pull the model into your ollama instance/s beforehand.


key: chroma:document
string_value:
```json
{
  "models": [
    {
      "title": "Granite Code",
      "provider": "openai",
      "model": "granite-code:latest",
      "useLegacyCompletionsEndpoint": false,
      "apiBase": "http://YOUROPENWEBUI/ollama/v1",
      "apiKey": "sk-YOUR-API-KEY"
    }
  ],
  "customCommands": [
    {
      "name": "test",
      "prompt": "{{{ input }}}\n\nWrite a comprehensive set of unit tests for the selected code. It should setup, run tests that check for correctness including important edge cases, and teardown. Ensure that the tests are complete and sophisticated. Give the tests just as chat output, don't edit any file.",
      "description": "Write unit tests for highlighted code"
    }
  ],
  "tabAutocompleteModel": {
    "title": "Granite Code",
    "provider": "openai",
    "model": "granite-code:latest",
    "useLegacyCompletionsEndpoint": false,
    "apiBase": "http://localhost:3000/ollama/v1",
    "apiKey": "sk-YOUR-API-KEY"
  }
}
```

Save your `config.json` and thats it!


key: chroma:document
string_value:
Save your `config.json` and thats it!

You should now see your model in the Continue tab model selection.

Select it and you should now be chatting via Open WebUI (and or any [pipelines](/pipelines) you have setup )

You can do this for as many models you would like to use, altough any model should work, you should use a model that is designed for code.

See the continue documentation for additional continue configuration, [Continue Documentation](https://docs.continue.dev/reference/Model%20Providers/openai)


key: chroma:document
string_value:
---
sidebar_position: 1600
title: "🤝 Contributing"
---

import { TopBanners } from "@site/src/components/TopBanners";

<TopBanners />

🚀 **Welcome, Contributors!** 🚀

Your interest in contributing to Open WebUI is greatly appreciated. This document is here to guide you through the process, ensuring your contributions enhance the project effectively. Let's make Open WebUI even better, together!

## 💡 Contributing

Looking to contribute? Great! Here's how you can help:

### 🌟 Code Contribution Guidelines

We welcome pull requests. Before submitting one, please:

1. Open a discussion regarding your ideas [here](https://github.com/open-webui/open-webui/discussions/new/choose).
2. Follow the project's coding standards and include tests for new features.
3. Update documentation as necessary.
4. Write clear, descriptive commit messages.

### 🛠 Code PR Best Practices:


key: chroma:document
string_value:
### 🛠 Code PR Best Practices:

1. **Atomic PRs:** Make sure your PRs are small, focused, and deal with a single objective or task. This helps in easier code review and limits the chances of introducing unrelated issues. If the scope of changes grows too large, consider breaking them into smaller, logically independent PRs.
2. **Follow Existing Code Convention:** Ensure your code aligns with the existing coding standards and practices of the project.
3. **Avoid Additional External Dependencies:** Do not include additional external dependencies without prior discussion.
4. **Framework Agnostic Approach:** We aim to stay framework agnostic. Implement functionalities on our own whenever possible rather than relying on external frameworks or libraries. If you have doubts or suggestions regarding this approach, feel free to discuss it.

Thank you for contributing! 🚀

### 📚 Documentation & Tutorials


key: chroma:document
string_value:
Thank you for contributing! 🚀

### 📚 Documentation & Tutorials

Help us make Open WebUI more accessible by improving documentation, writing tutorials, or creating guides on setting up and optimizing the web UI.

### 🌐 Translations and Internationalization

Help us make Open WebUI available to a wider audience. In this section, we'll guide you through the process of adding new translations to the project.

We use JSON files to store translations. You can find the existing translation files in the `src/lib/i18n/locales` directory. Each directory corresponds to a specific language, for example, `en-US` for English (US), `fr-FR` for French (France) and so on. You can refer to [ISO 639 Language Codes](http://www.lingoes.net/en/translator/langcode.htm) to find the appropriate code for a specific language.

To add a new language:


key: chroma:document
string_value:
To add a new language:

- Create a new directory in the `src/lib/i18n/locales` path with the appropriate language code as its name. For instance, if you're adding translations for Spanish (Spain), create a new directory named `es-ES`.
- Copy the American English translation file(s) (from `en-US` directory in `src/lib/i18n/locale`) to this new directory and update the string values in JSON format according to your language. Make sure to preserve the structure of the JSON object.
- Add the language code and its respective title to languages file at `src/lib/i18n/locales/languages.json`.

### 🤔 Questions & Feedback

Got questions or feedback? Join our [Discord community](https://discord.gg/5rJgQTnV4s) or open an issue. We're here to help!

### 🚨 Reporting Issues


key: chroma:document
string_value:
### 🚨 Reporting Issues

Noticed something off? Have an idea? Check our [Issues tab](https://github.com/open-webui/open-webui/issues) to see if it's already been reported or suggested. If not, feel free to open a new issue. When reporting an issue, please follow our issue templates. These templates are designed to ensure that all necessary details are provided from the start, enabling us to address your concerns more efficiently.

:::important

- **Template Compliance:** Please be aware that failure to follow the provided issue template, or not providing the requested information at all, will likely result in your issue being closed without further consideration. This approach is critical for maintaining the manageability and integrity of issue tracking.


key: chroma:document
string_value:
- **Detail is Key:** To ensure your issue is understood and can be effectively addressed, it's imperative to include comprehensive details. Descriptions should be clear, including steps to reproduce, expected outcomes, and actual results. Lack of sufficient detail may hinder our ability to resolve your issue.

:::

### 🧭 Scope of Support

We've noticed an uptick in issues not directly related to Open WebUI but rather to the environment it's run in, especially Docker setups. While we strive to support Docker deployment, understanding Docker fundamentals is crucial for a smooth experience.

- **Docker Deployment Support**: Open WebUI supports Docker deployment. Familiarity with Docker is assumed. For Docker basics, please refer to the [official Docker documentation](https://docs.docker.com/get-started/overview/).


key: chroma:document
string_value:
- **Advanced Configurations**: Setting up reverse proxies for HTTPS and managing Docker deployments requires foundational knowledge. There are numerous online resources available to learn these skills. Ensuring you have this knowledge will greatly enhance your experience with Open WebUI and similar projects.

## 🙏 Thank You!

Your contributions, big or small, make a significant impact on Open WebUI. We're excited to see what you bring to the project!

Together, let's create an even more powerful tool for the community. 🌟


key: chroma:document
string_value:
---
sidebar_position: 2
title: "🤝 Contributing Tutorials"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# Contributing Tutorials

We appreciate your interest in contributing tutorials to the Open WebUI documentation. Follow the steps below to set up your environment and submit your tutorial.

## Steps

1. **Fork the `openwebui/docs` GitHub Repository**

   - Navigate to the [Open WebUI Docs Repository](https://github.com/open-webui/docs) on GitHub.
   - Click the **Fork** button at the top-right corner to create a copy under your GitHub account.

2. **Enable GitHub Actions**

   - In your forked repository, navigate to the **Actions** tab.
   - If prompted, enable GitHub Actions by following the on-screen instructions.

3. **Enable GitHub Pages**


key: chroma:document
string_value:
3. **Enable GitHub Pages**

   - Go to **Settings** > **Pages** in your forked repository.
   - Under **Source**, select the branch you want to deploy (e.g., `main`) and the folder (e.g.,`/docs`).
   - Click **Save** to enable GitHub Pages.

4. **Configure GitHub Environment Variables**

   - In your forked repository, go to **Settings** > **Secrets and variables** > **Actions** > **Variables**.
   - Add the following environment variables:
     - `BASE_URL` set to `/docs` (or your chosen base URL for the fork).
     - `SITE_URL` set to `https://<your-github-username>.github.io/`.

### 📝 Updating the GitHub Pages Workflow and Config File

If you need to adjust deployment settings to fit your custom setup, here's what to do:

a. **Update `.github/workflows/gh-pages.yml`**

- Add environment variables for `BASE_URL` and `SITE_URL` to the build step if necessary:


key: chroma:document
string_value:
- Add environment variables for `BASE_URL` and `SITE_URL` to the build step if necessary:

     ```yaml
       - name: Build
         env:
           BASE_URL: ${{ vars.BASE_URL }}
           SITE_URL: ${{ vars.SITE_URL }}
         run: npm run build
     ```

b. **Modify `docusaurus.config.ts` to Use Environment Variables**

- Update `docusaurus.config.ts` to use these environment variables, with default values for local or direct deployment:

     ```typescript
     const config: Config = {
       title: "Open WebUI",
       tagline: "ChatGPT-Style WebUI for LLMs (Formerly Ollama WebUI)",
       favicon: "img/favicon.png",
       url: process.env.SITE_URL || "https://openwebui.com",
       baseUrl: process.env.BASE_URL || "/",
       ...
     };
     ```

- This setup ensures consistent deployment behavior for forks and custom setups.

5. **Run the `gh-pages` GitHub Workflow**


key: chroma:document
string_value:
5. **Run the `gh-pages` GitHub Workflow**

   - In the **Actions** tab, locate the `gh-pages` workflow.
   - Trigger the workflow manually if necessary, or it may run automatically based on your setup.

6. **Browse to Your Forked Copy**

   - Visit `https://<your-github-username>.github.io/<BASE_URL>` to view your forked documentation.

7. **Draft Your Changes**

   - In your forked repository, navigate to the appropriate directory (e.g., `docs/tutorial/`).
   - Create a new markdown file for your tutorial or edit existing ones.
   - Ensure that your tutorial includes the unsupported warning banner.

8. **Submit a Pull Request**

   - Once your tutorial is ready, commit your changes to your forked repository.
   - Navigate to the original `open-webui/docs` repository.
   - Click **New Pull Request** and select your fork and branch as the source.
   - Provide a descriptive title and description for your PR.
   - Submit the pull request for review.

## Important


key: chroma:document
string_value:
## Important

Community-contributed tutorials must include the the following:

```
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
```

---

:::tip How to Test Docusaurus Locally  
You can test your Docusaurus site locally with the following commands:

```bash
npm install   # Install dependencies
npm run build # Build the site for production
```

This will help you catch any issues before deploying
:::

---


key: chroma:document
string_value:
---
sidebar_position: 4
title: "🗂️ Organizing Conversations"
---

Open WebUI provides powerful organization features that help users manage their conversations. You can easily categorize and tag conversations, making it easier to find and retrieve them later. The two primary ways to organize conversations are through **Folders** and **Tags**.

## Organizing Conversations with Folders

Folders allow you to group related conversations together for quick access and better organization.

- **Creating a Folder**: You can create a new folder to store specific conversations. This is useful if you want to keep conversations of a similar topic or purpose together.
- **Moving Conversations into Folders**: Conversations can be moved into folders by dragging and dropping them. This allows you to structure your workspace in a way that suits your workflow.

![Folder Demo](/img/folder-demo.gif)

### Example Use Case


key: chroma:document
string_value:
![Folder Demo](/img/folder-demo.gif)

### Example Use Case

:::tip **Organizing by Project**
If you are managing multiple projects, you can create separate folders for each project and move relevant conversations into these folders. This helps keep all project-related discussions in one place.
:::

## Tagging Conversations

Tags provide an additional layer of organization by allowing you to label conversations with keywords or phrases.

- **Adding Tags to Conversations**: Tags can be applied to conversations based on their content or purpose. Tags are flexible and can be added or removed as needed.
![Tag Demo](/img/tag-demo.gif)
- **Using Tags for Searching**: Tags make it easy to locate specific conversations by using the search feature. You can filter conversations by tags to quickly find those related to specific topics.

### Example Use Case


key: chroma:document
string_value:
### Example Use Case

:::tip **Tagging by Topic**
If you frequently discuss certain topics, such as "marketing" or "development," you can tag conversations with these terms. Later, when you search for a specific tag, all relevant conversations will be quickly accessible.
:::


key: chroma:document
string_value:
---
sidebar_position: 14
title: "🛃 Setting up with Custom CA Store"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

If you get an `[SSL: CERTIFICATE_VERIFY_FAILED]` error when trying to run OI, most likely the issue is that you are on a network which intercepts HTTPS traffic (e.g. a corporate network).

To fix this, you will need to add the new cert into OI's truststore.

**For pre-built Docker image**:


key: chroma:document
string_value:
**For pre-built Docker image**:

1. Mount the certificiate store from your host machine into the container by passing `--volume=/etc/ssl/certs/ca-certificiate.crt:/etc/ssl/certs/ca-certificiates.crt:ro` as a command-line option to `docker run`
2. Force python to use the system truststore by setting `REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt` (see https://docs.docker.com/reference/cli/docker/container/run/#env)

If the environment variable `REQUESTS_CA_BUNDLE` does not work try to set `SSL_CERT_FILE` (as per the [httpx documentation](https://www.python-httpx.org/environment_variables/#ssl_cert_file)) instead with the same value.

Example `compose.yaml` from [@KizzyCode](https://github.com/open-webui/open-webui/issues/1398#issuecomment-2258463210):


key: chroma:document
string_value:
```yaml
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - /var/containers/openwebui:/app/backend/data:rw
      - /etc/containers/openwebui/compusrv.crt:/etc/ssl/certs/ca-certificates.crt:ro
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    environment:
      - WEBUI_NAME=compusrv
      - ENABLE_SIGNUP=False
      - ENABLE_COMMUNITY_SHARING=False
      - WEBUI_SESSION_COOKIE_SAME_SITE=strict
      - WEBUI_SESSION_COOKIE_SECURE=True
      - ENABLE_OLLAMA_API=False
      - REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
```

The `ro` flag mounts the CA store as read-only and prevents accidental changes to your host CA store
**For local development**:


key: chroma:document
string_value:
You can also add the certificates in the build process by modifying the `Dockerfile`. This is useful if you want to make changes to the UI, for instance.
Since the build happens in [multiple stages](https://docs.docker.com/build/building/multi-stage/), you have to add the cert into both

1. Frontend (`build` stage):

```dockerfile
COPY package.json package-lock.json <YourRootCert>.crt ./
ENV NODE_EXTRA_CA_CERTS=/app/<YourRootCert>.crt
RUN npm ci
```

2. Backend (`base` stage):

```dockerfile
COPY <CorporateSSL.crt> /usr/local/share/ca-certificates/
RUN update-ca-certificates
ENV PIP_CERT=/etc/ssl/certs/ca-certificates.crt \
    REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
```


key: chroma:document
string_value:
## Data Storage and Bind Mounts

This project uses [Docker named volumes](https://docs.docker.com/storage/volumes/) to **persist data**. If needed, replace the volume name with a host directory:

**Example**:

```bash
-v /path/to/folder:/app/backend/data
```

Ensure the host folder has the correct permissions.


key: chroma:document
string_value:
---
sidebar_position: 5
title: "🛠️ Development Guide"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import { TopBanners } from "@site/src/components/TopBanners";

<TopBanners />

# 🛠️ Development Setup Guide

Welcome to the **Open WebUI Development Setup Guide!** Whether you're a novice or an experienced developer, this guide will help you set up a **local development environment** for both the frontend and backend components. Let's dive in! 🚀

## System Requirements

- **Operating System**: Linux (or WSL on Windows) or macOS  
- **Python Version**: Python 3.11+  
- **Node.js Version**: 20.10+

## Development Methods

<Tabs groupId="dev-setup">

<TabItem value="local" label="Local Setup">

### 🐧 Local Development Setup

1. **Clone the Repository**:

   ```bash
   git clone https://github.com/open-webui/open-webui.git
   cd open-webui
   ```

2. **Frontend Setup**:
   - Create a `.env` file:

     ```bash
     cp -RPp .env.example .env
     ```


key: chroma:document
string_value:
```bash
     cp -RPp .env.example .env
     ```

   - Install dependencies:

     ```bash
     npm install
     ```

   - Start the frontend server:

     ```bash
     npm run dev
     ```

     🌐 Available at: [http://localhost:5173](http://localhost:5173).

3. **Backend Setup**:
   - Navigate to the backend:

     ```bash
     cd backend
     ```

   - Use **Conda** for environment setup:

     ```bash
     conda create --name open-webui python=3.11
     conda activate open-webui
     ```

   - Install dependencies:

     ```bash
     pip install -r requirements.txt -U
     ```

   - Start the backend:

     ```bash
     sh dev.sh
     ```

     📄 API docs available at: [http://localhost:8080/docs](http://localhost:8080/docs).

</TabItem>

<TabItem value="docker" label="Docker Setup">

### 🐳 Docker-Based Development Setup

1. **Create the Docker Compose File**:

   ```yaml
   name: open-webui-dev


key: chroma:document
string_value:
1. **Create the Docker Compose File**:

   ```yaml
   name: open-webui-dev

   services:
     frontend:
       build:
         context: .
         target: build
       command: ["npm", "run", "dev"]
       depends_on:
         - backend
       ports:
         - "3000:5173"
       extra_hosts:
         - host.docker.internal:host-gateway
       volumes:
         - ./src:/app/src

     backend:
       build:
         context: .
         target: base
       command: ["bash", "dev.sh"]
       env_file: ".env"
       environment:
         - ENV=dev
         - WEBUI_AUTH=False
       ports:
         - "8080:8080"
       extra_hosts:
         - host.docker.internal:host-gateway
       volumes:
         - ./backend:/app/backend
         - data:/app/backend/data

   volumes:
     data: {}
   ```

2. **Start the Development Containers**:

   ```bash
   docker compose -f compose-dev.yaml up --watch
   ```

3. **Stop the Containers**:

   ```bash
   docker compose -f compose-dev.yaml down
   ```


key: chroma:document
string_value:
3. **Stop the Containers**:

   ```bash
   docker compose -f compose-dev.yaml down
   ```

</TabItem>
<TabItem value="conda" label="Optional Conda Setup">

### Conda Environment Setup

If you prefer using **Conda** for isolation:

1. **Create and Activate the Environment**:

   ```bash
   conda create --name open-webui-dev python=3.11
   conda activate open-webui-dev
   ```

2. **Install Dependencies**:

   ```bash
   pip install -r requirements.txt
   ```

3. **Run the Servers**:
   - Frontend:

     ```bash
     npm run dev
     ```

   - Backend:

     ```bash
     sh dev.sh
     ```

</TabItem>

<TabItem value="troubleshooting" label="Troubleshooting">

## 🐛 Troubleshooting

### **FATAL ERROR: Reached Heap Limit**

If you encounter memory-related errors during the build, increase the **Node.js heap size**:

1. **Modify Dockerfile**:

   ```dockerfile
   ENV NODE_OPTIONS=--max-old-space-size=4096
   ```

2. **Allocate at least 4 GB of RAM** to Node.js.

---

### **Other Issues**


key: chroma:document
string_value:
2. **Allocate at least 4 GB of RAM** to Node.js.

---

### **Other Issues**

- **Port Conflicts**:  
   Ensure that no other processes are using **ports 8080 or 5173**.

- **Hot Reload Not Working**:  
   Verify that **watch mode** is enabled for both frontend and backend.

</TabItem>

</Tabs>

## Contributing to Open WebUI

### Local Workflow

1. **Commit Changes Regularly** to track progress.
2. **Sync with the Main Branch** to avoid conflicts:

   ```bash
   git pull origin main
   ```

3. **Run Tests Before Pushing**:

   ```bash
   npm run test
   ```

Happy coding! 🎉


key: chroma:document
string_value:
# Docker Compose Setup

Using Docker Compose simplifies the management of multi-container Docker applications.

If you don't have Docker installed, check out our [Docker installation tutorial](docs/tutorials/docker-install.md).

Docker Compose requires an additional package, `docker-compose-v2`.

**Warning:** Older Docker Compose tutorials may reference version 1 syntax, which uses commands like `docker-compose build`. Ensure you use version 2 syntax, which uses commands like `docker compose build` (note the space instead of a hyphen).

## Example `docker-compose.yml`

Here is an example configuration file for setting up Open WebUI with Docker Compose:

```yaml
version: '3'
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:
```

## Starting the Services

To start your services, run the following command:

```bash
docker compose up -d
```

## Helper Script


key: chroma:document
string_value:
```bash
docker compose up -d
```

## Helper Script

A useful helper script called `run-compose.sh` is included with the codebase. This script assists in choosing which Docker Compose files to include in your deployment, streamlining the setup process.

---

**Note:** For Nvidia GPU support, add the following to your service definition in the `docker-compose.yml` file:

```yaml
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]
```

This setup ensures that your application can leverage GPU resources when available.


key: chroma:document
string_value:
---
sidebar_position: 0
title: 🐳 Installing Docker
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# Installing Docker

## For Windows and Mac Users

- Download Docker Desktop from [Docker's official website](https://www.docker.com/products/docker-desktop).  
- Follow the installation instructions on the website.  
- After installation, **open Docker Desktop** to ensure it's running properly.

---

## For Ubuntu Users

1. **Open your terminal.**

2. **Set up Docker's apt repository:**


key: chroma:document
string_value:
---

## For Ubuntu Users

1. **Open your terminal.**

2. **Set up Docker's apt repository:**

   ```bash
   sudo apt-get update
   sudo apt-get install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   echo \
     "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
     $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
     sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   ```

:::note
If using an **Ubuntu derivative** (e.g., Linux Mint), use `UBUNTU_CODENAME` instead of `VERSION_CODENAME`.
:::

3. **Install Docker Engine:**

   ```bash
   sudo apt-get update
   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
   ```

4. **Verify Docker Installation:**

   ```bash
   sudo docker run hello-world
   ```


key: chroma:document
string_value:
4. **Verify Docker Installation:**

   ```bash
   sudo docker run hello-world
   ```

---

## For Other Linux Distributions

For other Linux distributions, refer to the [official Docker documentation](https://docs.docker.com/engine/install/).

---

## Install and Verify Ollama

1. **Download Ollama** from [https://ollama.com/](https://ollama.com/).

2. **Verify Ollama Installation:**
   - Open a browser and navigate to:
     [http://127.0.0.1:11434/](http://127.0.0.1:11434/).
   - Note: The port may vary based on your installation.


key: chroma:document
string_value:
## Docker Swarm

This installation method requires knowledge on Docker Swarms, as it utilizes a stack file to deploy 3 seperate containers as services in a Docker Swarm.

It includes isolated containers of ChromaDB, Ollama, and OpenWebUI.
Additionally, there are pre-filled [Environment Variables](../advanced-topics/env-configuration) to further illustrate the setup.

Choose the appropriate command based on your hardware setup:

- **Before Starting**:

  Directories for your volumes need to be created on the host, or you can specify a custom location or volume.
  
  The current example utilizes an isolated dir `data`, which is within the same dir as the `docker-stack.yaml`.
  
      - **For example**:
  
        ```bash
        mkdir -p data/open-webui data/chromadb data/ollama
        ```

- **With GPU Support**:

  #### Docker-stack.yaml

    ```yaml
    version: '3.9'


key: chroma:document
string_value:
services:
      openWebUI:
        image: ghcr.io/open-webui/open-webui:main
        depends_on:
            - chromadb
            - ollama
        volumes:
          - ./data/open-webui:/app/backend/data
        environment:
          DATA_DIR: /app/backend/data 
          OLLAMA_BASE_URLS: http://ollama:11434
          CHROMA_HTTP_PORT: 8000
          CHROMA_HTTP_HOST: chromadb
          CHROMA_TENANT: default_tenant
          VECTOR_DB: chroma
          WEBUI_NAME: Awesome ChatBot
          CORS_ALLOW_ORIGIN: "*" # This is the current Default, will need to change before going live
          RAG_EMBEDDING_ENGINE: ollama
          RAG_EMBEDDING_MODEL: nomic-embed-text-v1.5
          RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE: "True"
        ports:
          - target: 8080
            published: 8080
            mode: overlay
        deploy:
          replicas: 1
          restart_policy:
            condition: any
            delay: 5s
            max_attempts: 3


key: chroma:document
string_value:
chromadb:
        hostname: chromadb
        image: chromadb/chroma:0.5.15
        volumes:
          - ./data/chromadb:/chroma/chroma
        environment:
          - IS_PERSISTENT=TRUE
          - ALLOW_RESET=TRUE
          - PERSIST_DIRECTORY=/chroma/chroma
        ports: 
          - target: 8000
            published: 8000
            mode: overlay
        deploy:
          replicas: 1
          restart_policy:
            condition: any
            delay: 5s
            max_attempts: 3
        healthcheck: 
          test: ["CMD-SHELL", "curl localhost:8000/api/v1/heartbeat || exit 1"]
          interval: 10s
          retries: 2
          start_period: 5s
          timeout: 10s


key: chroma:document
string_value:
ollama:
        image: ollama/ollama:latest
        hostname: ollama
        ports:
          - target: 11434
            published: 11434
            mode: overlay
        deploy:
          resources:
            reservations:
              generic_resources:
                - discrete_resource_spec:
                    kind: "NVIDIA-GPU"
                    value: 0
          replicas: 1
          restart_policy:
            condition: any
            delay: 5s
            max_attempts: 3
        volumes:
          - ./data/ollama:/root/.ollama

    ```

  - **Additional Requirements**:


key: chroma:document
string_value:
```

  - **Additional Requirements**:

      1. Ensure CUDA is Enabled, follow your OS and GPU instructions for that.
      2. Enable Docker GPU support, see [Nvidia Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html " on Nvidia's site.")
      3. Follow the [Guide here on configuring Docker Swarm to with with your GPU](https://gist.github.com/tomlankhorst/33da3c4b9edbde5c83fc1244f010815c#configuring-docker-to-work-with-your-gpus)
    - Ensure _GPU Resource_ is enabled in `/etc/nvidia-container-runtime/config.toml` and enable GPU resource advertising by uncommenting the `swarm-resource = "DOCKER_RESOURCE_GPU"`. The docker daemon must be restarted after updating these files on each node.

- **With CPU Support**:
  
    Modify the Ollama Service within `docker-stack.yaml` and remove the lines for `generic_resources:`


key: chroma:document
string_value:
```yaml
        ollama:
      image: ollama/ollama:latest
      hostname: ollama
      ports:
        - target: 11434
          published: 11434
          mode: overlay
      deploy:
        replicas: 1
        restart_policy:
          condition: any
          delay: 5s
          max_attempts: 3
      volumes:
        - ./data/ollama:/root/.ollama
    ```

- **Deploy Docker Stack**:
  
  ```bash
  docker stack deploy -c docker-stack.yaml -d super-awesome-ai
  ```


key: chroma:document
string_value:
## Updating

To update your local Docker installation to the latest version, you can either use **Watchtower** or manually update the container.

### Option 1: Using Watchtower

With [Watchtower](https://containrrr.dev/watchtower/), you can automate the update process:

```bash
docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui
```

_(Replace `open-webui` with your container's name if it's different.)_

### Option 2: Manual Update

1. Stop and remove the current container:

   ```bash
   docker rm -f open-webui
   ```

2. Pull the latest version:

   ```bash
   docker pull ghcr.io/open-webui/open-webui:main
   ```

3. Start the container again:

   ```bash
   docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
   ```

Both methods will get your Docker instance updated and running with the latest build.


key: chroma:document
string_value:
---
sidebar_position: 4
title: "🌍 Environment Variable Configuration"
---


## Overview

Open WebUI provides a range of environment variables that allow you to customize and configure
various aspects of the application. This page serves as a comprehensive reference for all available
environment variables, including their types, default values, and descriptions.

:::info
Last updated: v0.3.20
:::

## App/Backend

The following environment variables are used by `backend/config.py` to provide Open WebUI startup
configuration. Please note that some variables may have different default values depending on
whether you're running Open WebUI directly or via Docker. For more information on logging
environment variables, see our [logging documentation](https://docs.openwebui.com/getting-started/advanced-topics/logging)).

### General

#### `ENV`


key: chroma:document
string_value:
### General

#### `ENV`

- Type: `str` (enum: `dev`, `prod`)
- Options:
  - `dev` - Enables the FastAPI API docs on `/docs`
  - `prod` - Automatically configures several environment variables
- Default:
  - **Backend Default**: `dev`
  - **Docker Default**: `prod`
- Description: Environment setting.

#### `WEBUI_AUTH`

- Type: `bool`
- Default Setting: `True`
- Description: This setting enables or disables authentication.

:::danger
If set to `False`, authentication will be disabled for your Open WebUI instance. However, it's
important to note that turning off authentication is only possible for fresh installations without
any existing users. If there are already users registered, you cannot disable authentication
directly. Ensure that no users are present in the database, if you intend to turn off `WEBUI_AUTH`.
:::

#### `WEBUI_NAME`

- Type: `str`
- Default: `Open WebUI`
- Description: Sets the main WebUI name. Appends `(Open WebUI)` if overridden.

#### `WEBUI_URL`


key: chroma:document
string_value:
#### `WEBUI_URL`

- Type: `str`
- Default: `http://localhost:3000`
- Description: Specifies the URL where the Open WebUI is reachable. Currently used for search engine support.

#### `AIOHTTP_CLIENT_TIMEOUT`

- Type: `int`
- Default: `300`
- Description: Specifies the timeout duration in seconds for the aiohttp client.

:::info
This is the maximum amount of time the client will wait for a response before timing out.
If set to an empty string (' '), the timeout will be set to `None`, effectively disabling the timeout and
allowing the client to wait indefinitely.
:::

#### `DATA_DIR`

- Type: `str`
- Default: `./data`
- Description: Specifies the base directory for data storage, including uploads, cache, vector database, etc.

#### `FRONTEND_BUILD_DIR`

- Type: `str`
- Default: `../build`
- Description: Specifies the location of the built frontend files.

#### `STATIC_DIR`

- Type: `str`
- Default: `./static`
- Description: Specifies the directory for static files, such as the favicon.


key: chroma:document
string_value:
#### `CUSTOM_NAME`

- Type: `str`
- Description: Sets `WEBUI_NAME` but polls **api.openwebui.com** for metadata.

#### `ENABLE_SIGNUP`

- Type: `bool`
- Default: `True`
- Description: Toggles user account creation.

#### `ENABLE_LOGIN_FORM`

- Type: `bool`
- Default: `True`
- Description: Toggles email, password, sign in and "or" (only when `ENABLE_OAUTH_SIGNUP` is set to True) elements.

:::danger
This should **only** ever be set to `False` when [ENABLE_OAUTH_SIGNUP](https://docs.openwebui.com/getting-started/advanced-topics/env-configuration/#enable_oauth_signup)
is also being used and set to `True`. Failure to do so will result in the inability to login.
:::

#### `ENABLE_RAG_WEB_LOADER_SSL_VERIFICATION`

- Type: `bool`
- Default: `True`
- Description: Bypass SSL Verification for RAG on Websites.

#### `DEFAULT_MODELS`

- Type: `str`
- Description: Sets a default Language Model.

#### `DEFAULT_USER_ROLE`


key: chroma:document
string_value:
- Type: `str`
- Description: Sets a default Language Model.

#### `DEFAULT_USER_ROLE`

- Type: `str` (enum: `pending`, `user`, `admin`)
- Options:
  - `pending` - New users are pending until their accounts are manually activated by an admin.
  - `user` - New users are automatically activated with regular user permissions.
  - `admin` - New users are automatically activated with administrator permissions.
- Default: `pending`
- Description: Sets the default role assigned to new users.

#### `USER_PERMISSIONS_CHAT_DELETION`

- Type: `bool`
- Default: `True`
- Description: Toggles user permission to delete chats.

#### `USER_PERMISSIONS_CHAT_EDITING`

- Type: `bool`
- Default: `True`
- Description: Toggles user permission to edit chats.

#### `USER_PERMISSIONS_CHAT_TEMPORARY`

- Type: `bool`
- Default: `True`
- Description: Toggles user permission to create temporary chats.

#### `ENABLE_MODEL_FILTER`

- Type: `bool`
- Default: `False`
- Description: Toggles Language Model filtering.


key: chroma:document
string_value:
- Type: `bool`
- Default: `False`
- Description: Toggles Language Model filtering.

#### `MODEL_FILTER_LIST`

- Type: `str`
- Description: Sets the Language Model filter list, semicolon-separated
- Example: `llama3.1:instruct;gemma2:latest`

#### `WEBHOOK_URL`

- Type: `str`
- Description: Sets a webhook for integration with Slack/Microsoft Teams.

#### `ENABLE_ADMIN_EXPORT`

- Type: `bool`
- Default: `True`
- Description: Controls whether admin users can export data.

#### `ENABLE_ADMIN_CHAT_ACCESS`

- Type: `bool`
- Default: `True`
- Description: Enables admin users to access all chats.

#### `ENABLE_COMMUNITY_SHARING`

- Type: `bool`
- Default: `True`
- Description: Controls whether users are shown the share to community button.

#### `ENABLE_MESSAGE_RATING`

- Type: `bool`
- Default: `True`
- Description: Enables message rating feature.

#### `WEBUI_BUILD_HASH`

- Type: `str`
- Default: `dev-build`
- Description: Used for identifying the Git SHA of the build for releases.


key: chroma:document
string_value:
#### `WEBUI_BANNERS`

- Type: `list` of `dict`
- Default: `[]`
- Description: List of banners to show to users. Format of banners are:

```json
[{"id": "string","type": "string [info, success, warning, error]","title": "string","content": "string","dismissible": False,"timestamp": 1000}]
```

#### `WEBUI_AUTH_TRUSTED_EMAIL_HEADER`

- Type: `str`
- Description: Defines the trusted request header for authentication. See [SSO docs](/features/sso).

#### `WEBUI_AUTH_TRUSTED_NAME_HEADER`

- Type: `str`
- Description: Defines the trusted request header for the username of anyone registering with the
`WEBUI_AUTH_TRUSTED_EMAIL_HEADER` header. See [SSO docs](/features/sso).

#### `WEBUI_SECRET_KEY`

- Type: `str`
- Default: `t0p-s3cr3t`
- Docker Default: Randomly generated on first start
- Description: Overrides the randomly generated string used for JSON Web Token.

#### `JWT_EXPIRES_IN`


key: chroma:document
string_value:
#### `JWT_EXPIRES_IN`

- Type: `int`
- Default: `-1`
- Description: Sets the JWT expiration time in seconds. A value of -1 disables expiration.

#### `USE_CUDA_DOCKER`

- Type: `bool`
- Default: `False`
- Description: Builds the Docker image with NVIDIA CUDA support. Enables GPU acceleration
for local Whisper and embeddings.

#### `DATABASE_URL`

- Type: `str`
- Default: `sqlite:///${DATA_DIR}/webui.db`
- Description: Specifies the database URL to connect to.

:::info
Supports SQLite and Postgres. Changing the URL does not migrate data between databases.
Documentation on URL scheme available [here](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls).
:::

#### `DATABASE_POOL_SIZE`

- Type: `int`
- Default: `0`
- Description: Specifies the size of the database pool. A value of `0` disables pooling.

#### `DATABASE_POOL_MAX_OVERFLOW`

- Type: `int`
- Default: `0`
- Description: Specifies the database pool max overflow.


key: chroma:document
string_value:
- Type: `int`
- Default: `0`
- Description: Specifies the database pool max overflow.

:::info
More information about this setting can be found [here](https://docs.sqlalchemy.org/en/20/core/pooling.html#sqlalchemy.pool.QueuePool.params.max_overflow).
:::

#### `DATABASE_POOL_TIMEOUT`

- Type: `int`
- Default: `30`
- Description: Specifies the database pool timeout in seconds to get a connection.

:::info
More information about this setting can be found [here](https://docs.sqlalchemy.org/en/20/core/pooling.html#sqlalchemy.pool.QueuePool.params.timeout).
:::

#### `DATABASE_POOL_RECYCLE`

- Type: `int`
- Default: `3600`
- Description: Specifies the database pool recycle time in seconds.

:::info
More information about this setting can be found [here](https://docs.sqlalchemy.org/en/20/core/pooling.html#setting-pool-recycle).
:::

#### `PORT`

- Type: `int`
- Default: `8080`
- Description: Sets the port to run Open WebUI from.


key: chroma:document
string_value:
#### `PORT`

- Type: `int`
- Default: `8080`
- Description: Sets the port to run Open WebUI from.

:::info
If installed via Python, you must instead pass `--port` as a command line argument.
:::

#### `RESET_CONFIG_ON_START`

- Type: `bool`
- Default: `False`
- Description: Resets the `config.json` file on startup.

#### `DEFAULT_LOCALE`

- Type: `str`
- Default: `en`
- Description: Sets the default locale for the application.

#### `FUNCTIONS_DIR`

- Type: `str`
- Default: `./functions`
- Description: Specifies the directory for custom functions.

#### `SHOW_ADMIN_DETAILS`

- Type: `bool`
- Default: `True`
- Description: Toggles whether to show admin user details in the interface.

#### `ADMIN_EMAIL`

- Type: `str`
- Description: Sets the admin email shown by `SHOW_ADMIN_DETAILS`

#### `SAFE_MODE`

- Type: `bool`
- Default: `False`
- Description: Enables safe mode, which disables potentially unsafe features, deactivating all functions.

#### `ENABLE_FORWARD_USER_INFO_HEADERS`


key: chroma:document
string_value:
#### `ENABLE_FORWARD_USER_INFO_HEADERS`

- type: `bool`
- Default: `False`
- Description: Forwards user information (name, id, email, and role) as X-headers to OpenAI API.
If enabled, the following headers are forwarded:
  - `X-OpenWebUI-User-Name`
  - `X-OpenWebUI-User-Id`
  - `X-OpenWebUI-User-Email`
  - `X-OpenWebUI-User-Role`

#### `WEBUI_SESSION_COOKIE_SAME_SITE`

- Type: `str` (enum: `lax`, `strict`, `none`)
- Options:
  - `lax` - Sets the `SameSite` attribute to lax, allowing session cookies to be sent with
requests initiated by third-party websites.
  - `strict` - Sets the `SameSite` attribute to strict, blocking session cookies from being sent
with requests initiated by third-party websites.
  - `none` - Sets the `SameSite` attribute to none, allowing session cookies to be sent with
requests initiated by third-party websites, but only over HTTPS.
- Default: `lax`
- Description: Sets the `SameSite` attribute for session cookies.

#### `WEBUI_SESSION_COOKIE_SECURE`


key: chroma:document
string_value:
#### `WEBUI_SESSION_COOKIE_SECURE`

- Type: `bool`
- Default: `False`
- Description: Sets the `Secure` attribute for session cookies if set to `True`.

#### `CONTENT_SECURITY_POLICY`

- Type: `str`
- Description: Sets the `content-security-policy` HTTP header
- Example: `default-src 'self' 'unsafe-inline' 'unsafe-eval'; img-src 'self' https://* data:; child-src 'none'; font-src 'self' data:; worker-src 'self';`

#### `AIOHTTP_CLIENT_TIMEOUT`

- Type: `int`
- Description: Sets the timeout in seconds for internal aiohttp connections. This impacts things
such as connections to Ollama and OpenAI endpoints.

#### `AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST`

- Type: `int`
- Description: Sets the timeout in seconds for fetching the OpenAI model list. This can be useful in cases where network latency requires a longer timeout duration to successfully retrieve the model list.

#### `FONTS_DIR`

- Type: `str`
- Description: Specifies the directory for fonts.

### Ollama


key: chroma:document
string_value:
#### `FONTS_DIR`

- Type: `str`
- Description: Specifies the directory for fonts.

### Ollama

#### `ENABLE_OLLAMA_API`

- Type: `bool`
- Default: `True`
- Description: Enables the use of Ollama APIs.

#### `OLLAMA_BASE_URL`

- Type: `str`
- Default: `http://localhost:11434`
- Docker Default:
  - If `K8S_FLAG` is set: `http://ollama-service.open-webui.svc.cluster.local:11434`
  - If `USE_OLLAMA_DOCKER=True`: `http://localhost:11434`
  - Else `http://host.docker.internal:11434`
- Description: Configures the Ollama backend URL.

#### `OLLAMA_BASE_URLS`

- Type: `str`
- Description: Configures load-balanced Ollama backend hosts, separated by `;`. See
[`OLLAMA_BASE_URL`](#ollama_base_url). Takes precedence over[`OLLAMA_BASE_URL`](#ollama_base_url).

#### `USE_OLLAMA_DOCKER`

- Type: `bool`
- Default: `False`
- Description: Builds the Docker image with a bundled Ollama instance.

#### `K8S_FLAG`


key: chroma:document
string_value:
#### `K8S_FLAG`

- Type: `bool`
- Description: If set, assumes Helm chart deployment and sets [`OLLAMA_BASE_URL`](#ollama_base_url) to `http://ollama-service.open-webui.svc.cluster.local:11434`

### OpenAI

#### `ENABLE_OPENAI_API`

- Type: `bool`
- Default: `True`
- Description: Enables the use of OpenAI APIs.

#### `OPENAI_API_BASE_URL`

- Type: `str`
- Default: `https://api.openai.com/v1`
- Description: Configures the OpenAI base API URL.

#### `OPENAI_API_BASE_URLS`

- Type: `str`
- Description: Supports balanced OpenAI base API URLs, semicolon-separated.
- Example: `http://host-one:11434;http://host-two:11434`

#### `OPENAI_API_KEY`

- Type: `str`
- Description: Sets the OpenAI API key.

#### `OPENAI_API_KEYS`

- Type: `str`
- Description: Supports multiple OpenAI API keys, semicolon-separated.
- Example: `sk-124781258123;sk-4389759834759834`

### Tasks

#### `TASK_MODEL`


key: chroma:document
string_value:
### Tasks

#### `TASK_MODEL`

- Type: `str`
- Description: The default model to use for tasks such as title and web search query generation
when using Ollama models.

#### `TASK_MODEL_EXTERNAL`

- Type: `str`
- Description: The default model to use for tasks such as title and web search query generation
when using OpenAI-compatible endpoints.

#### `TITLE_GENERATION_PROMPT_TEMPLATE`

- Type: `str`
- Description: Prompt to use when generating chat titles.
- Default:

```
Create a concise, 3-5 word title with an emoji as a title for the prompt in the given language. Suitable Emojis for the summary can be used to enhance understanding but avoid quotation marks or special formatting. RESPOND ONLY WITH THE TITLE TEXT.

Examples of titles:
📉 Stock Market Trends
🍪 Perfect Chocolate Chip Recipe
Evolution of Music Streaming
Remote Work Productivity Tips
Artificial Intelligence in Healthcare
🎮 Video Game Development Insights

Prompt: {{prompt:middletruncate:8000}}
```


key: chroma:document
string_value:
Prompt: {{prompt:middletruncate:8000}}
```

#### `SEARCH_QUERY_GENERATION_PROMPT_TEMPLATE`

- Type: `str`
- Description: Prompt to use when generating search queries.
- Default:

```
Assess the need for a web search based on the current question and prior interactions, but lean towards suggesting a Google search query if uncertain. Generate a Google search query even when the answer might be straightforward, as additional information may enhance comprehension or provide updated data. If absolutely certain that no further information is required, return an empty string. Default to a search query if unsure or in doubt. Today's date is {{CURRENT_DATE}}.

Current Question:
{{prompt:end:4000}}

Interaction History:
{{MESSAGES:END:6}}
```

#### `TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE`

- Type: `str`
- Description: Prompt to use when calling tools.
- Default:


key: chroma:document
string_value:
- Type: `str`
- Description: Prompt to use when calling tools.
- Default:

```
Available Tools: {{TOOLS}}\nReturn an empty string if no tools match the query. If a function tool matches, construct and return a JSON object in the format {\"name\": \"functionName\", \"parameters\": {\"requiredFunctionParamKey\": \"requiredFunctionParamValue\"}} using the appropriate tool and its parameters. Only return the object and limit the response to the JSON object without additional text.
```

#### `CORS_ALLOW_ORIGIN`

- Type: `str`
- Default: `*`
- Description: Sets the allowed origins for Cross-Origin Resource Sharing (CORS).

### RAG

#### `VECTOR_DB`

- Type: `str`
- Default: `chroma`
- Description: Specifies which vector database system to use, either 'chroma' for ChromaDB or 'milvus' for Milvus. This setting determines which vector storage system will be used for managing embeddings.

#### `CHROMA_TENANT`


key: chroma:document
string_value:
#### `CHROMA_TENANT`

- Type: `str`
- Default: `default_tenant`
- Description: Sets the tenant for ChromaDB to use for RAG embeddings.

#### `CHROMA_DATABASE`

- Type: `str`
- Default: `default_database`
- Description: Sets the database in the ChromaDB tenant to use for RAG embeddings.

#### `CHROMA_HTTP_HOST`

- Type: `str`
- Description: Specifies the hostname of a remote ChromaDB Server. Uses a local ChromaDB instance if not set.

#### `CHROMA_HTTP_PORT`

- Type: `int`
- Default: `8000`
- Description: Specifies the port of a remote ChromaDB Server.

#### `CHROMA_HTTP_HEADERS`

- Type: `str`
- Description: Comma-separated list of HTTP headers to include with every ChromaDB request.
- Example: `Authorization=Bearer heuhagfuahefj,User-Agent=OpenWebUI`.

#### `CHROMA_HTTP_SSL`

- Type: `bool`
- Default: `False`
- Description: Controls whether or not SSL is used for ChromaDB Server connections.

#### `CHROMA_CLIENT_AUTH_PROVIDER`


key: chroma:document
string_value:
#### `CHROMA_CLIENT_AUTH_PROVIDER`

- Type: `str`
- Description: Specifies auth provider for remote ChromaDB Server.
- Example: `chromadb.auth.basic_authn.BasicAuthClientProvider`

#### `CHROMA_CLIENT_AUTH_CREDENTIALS`

- Type: `str`
- Description: Specifies auth credentials for remote ChromaDB Server.
- Example: `username:password`

#### `MILVUS_URI`

- Type: `str`
- Default: `${DATA_DIR}/vector_db/milvus.db`
- Description: Specifies the URI for connecting to the Milvus vector database. This can point to a local or remote Milvus server based on the deployment configuration.

#### `RAG_TOP_K`

- Type: `int`
- Default: `5`
- Description: Sets the default number of results to consider when using RAG.

#### `RAG_RELEVANCE_THRESHOLD`

- Type: `float`
- Default: `0.0`
- Description: Sets the relevance threshold to consider for documents when used with reranking.

#### `ENABLE_RAG_HYBRID_SEARCH`


key: chroma:document
string_value:
#### `ENABLE_RAG_HYBRID_SEARCH`

- Type: `bool`
- Default: `False`
- Description: Enables the use of ensemble search with `BM25` + `ChromaDB`, with reranking using
`sentence_transformers` models.

#### `ENABLE_RAG_WEB_LOADER_SSL_VERIFICATION`

- Type: `bool`
- Default: `True`
- Description: Enables TLS certification verification when browsing web pages for RAG.

#### `RAG_EMBEDDING_ENGINE`

- Type: `str` (enum: `ollama`, `openai`)
- Options:
  - Leave empty for `Default (SentenceTransformers)` - Uses SentenceTransformers for embeddings.
  - `ollama` - Uses the Ollama API for embeddings.
  - `openai` - Uses the OpenAI API for embeddings.
- Description: Selects an embedding engine to use for RAG.

#### `PDF_EXTRACT_IMAGES`

- Type: `bool`
- Default: `False`
- Description: Extracts images from PDFs using OCR when loading documents.

#### `RAG_EMBEDDING_MODEL`


key: chroma:document
string_value:
#### `RAG_EMBEDDING_MODEL`

- Type: `str`
- Default: `sentence-transformers/all-MiniLM-L6-v2`
- Description: Sets a model for embeddings. Locally, a Sentence-Transformer model is used.

#### `RAG_EMBEDDING_MODEL_AUTO_UPDATE`

- Type: `bool`
- Default: `False`
- Description: Toggles automatic update of the Sentence-Transformer model.

#### `RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE`

- Type: `bool`
- Default: `False`
- Description: Determines whether or not to allow custom models defined on the Hub in their own modeling files.

#### `RAG_TEMPLATE`

- Type: `str`
- Default:

```
You are given a user query, some textual context and rules, all inside xml tags. You have to answer the query based on the context while respecting the rules.

<context>
[context]
</context>


key: chroma:document
string_value:
<context>
[context]
</context>

<rules>
- If you don't know, just say so.
- If you are not sure, ask for clarification.
- Answer in the same language as the user query.
- If the context appears unreadable or of poor quality, tell the user then answer as best as you can.
- If the answer is not in the context but you think you know the answer, explain that to the user then answer with your own knowledge.
- Answer directly and without using xml tags.
</rules>

<user_query>
[query]
</user_query>
```

- Description: Template to use when injecting RAG documents into chat completion

#### `RAG_RERANKING_MODEL`

- Type: `str`
- Description: Sets a model for reranking results. Locally, a Sentence-Transformer model is used.

#### `RAG_RERANKING_MODEL_AUTO_UPDATE`

- Type: `bool`
- Default: `False`
- Description: Toggles automatic update of the reranking model.

#### `RAG_RERANKING_MODEL_TRUST_REMOTE_CODE`


key: chroma:document
string_value:
#### `RAG_RERANKING_MODEL_TRUST_REMOTE_CODE`

- Type: `bool`
- Default: `False`
- Description: Determines whether or not to allow custom models defined on the Hub in their own
modeling files for reranking.

#### `RAG_OPENAI_API_BASE_URL`

- Type: `str`
- Default: `${OPENAI_API_BASE_URL}`
- Description: Sets the OpenAI base API URL to use for RAG embeddings.

#### `RAG_OPENAI_API_KEY`

- Type: `str`
- Default: `${OPENAI_API_KEY}`
- Description: Sets the OpenAI API key to use for RAG embeddings.

#### `RAG_EMBEDDING_OPENAI_BATCH_SIZE`

- Type: `int`
- Default: `1`
- Description: Sets the batch size for OpenAI embeddings.

#### `ENABLE_RAG_LOCAL_WEB_FETCH`

- Type: `bool`
- Default: `False`
- Description: Enables local web fetching for RAG. Enabling this allows Server Side Request
Forgery attacks against local network resources.

#### `YOUTUBE_LOADER_LANGUAGE`

- Type: `str`
- Default: `en`
- Description: Sets the language to use for YouTube video loading.

#### `CHUNK_SIZE`


key: chroma:document
string_value:
#### `CHUNK_SIZE`

- Type: `int`
- Default: `1500`
- Description: Sets the document chunk size for embeddings.

#### `CHUNK_OVERLAP`

- Type: `int`
- Default: `100`
- Description: Specifies how much overlap there should be between chunks.

#### `CONTENT_EXTRACTION_ENGINE`

- Type: `str` (`tika`)
- Options:
  - Leave empty to use default
  - `tika` - Use a local Apache Tika server
- Description: Sets the content extraction engine to use for document ingestion.

#### `TIKA_SERVER_URL`

- Type: `str`
- Default: `http://localhost:9998`
- Description: Sets the URL for the Apache Tika server.

#### `RAG_FILE_MAX_COUNT`

- Type: `int`
- Default: `10`
- Description: Sets the maximum number of files that can be uploaded at once for document ingestion.

#### `RAG_FILE_MAX_SIZE`

- Type: `int`
- Default: `100` (100MB)
- Description: Sets the maximum size of a file that can be uploaded for document ingestion.

### Web Search

#### `ENABLE_RAG_WEB_SEARCH`


key: chroma:document
string_value:
### Web Search

#### `ENABLE_RAG_WEB_SEARCH`

- Type: `bool`
- Default: `False`
- Description: Enable web search toggle

#### `ENABLE_SEARCH_QUERY`

- Type: `bool`
- Default: `False`
- Description: Enables the generation of search queries from prompts

#### `RAG_WEB_SEARCH_ENGINE`


key: chroma:document
string_value:
- Type: `str` (enum: `searxng`, `google_pse`, `brave`, `serpstack`, `serper`, `serply`, `searchapi`, `duckduckgo`, `tavily`, `jina`)
- Options:
  - `searxng` - Uses the [SearXNG](https://github.com/searxng/searxng) search engine.
  - `google_pse` - Uses the [Google Programmable Search Engine](https://programmablesearchengine.google.com/about/).
  - `brave` - Uses the [Brave search engine](https://brave.com/search/api/).
  - `serpstack` - Uses the [Serpstack search engine](https://serpstack.com/).
  - `serper` - Uses the [Serper search engine](https://serper.dev/).
  - `serply` - Uses the [Serply search engine](https://serply.io/).
  - `searchapi` - Uses the [SearchAPI search engine](https://www.searchapi.io/).
  - `duckduckgo` - Uses the [DuckDuckGo search engine](https://duckduckgo.com/).
  - `tavily` - Uses the [Tavily search engine](https://tavily.com/).
  - `jina` - Uses the [Jina search engine](https://jina.ai/).
- Description: Select engine for performing searches


key: chroma:document
string_value:
#### `SEARXNG_QUERY_URL`

- Type: `str`
- Description: The [SearXNG search API](https://docs.searxng.org/dev/search_api.html) URL supporting JSON output. `<query>` is replaced with
the search query. Example: `http://searxng.local/search?q=<query>`

#### `GOOGLE_PSE_API_KEY`

- Type: `str`
- Description: The API key for the Google Programmable Search Engine (PSE) service.

#### `GOOGLE_PSE_ENGINE_ID`

- Type: `str`
- Description: The engine ID for the Google Programmable Search Engine (PSE) service.

#### `BRAVE_SEARCH_API_KEY`

- Type: `str`
- Description: The API key for the Brave Search API.

#### `SERPSTACK_API_KEY`

- Type: `str`
- Description: The API key for Serpstack search API.

#### `SERPSTACK_HTTPS`

- Type: `bool`
- Default: `True`
- Description: Configures the use of HTTPS for Serpstack requests. Free tier requests are restricted to HTTP only.

#### `SERPER_API_KEY`

- Type: `str`
- Description: The API key for the Serper search API.

#### `SERPLY_API_KEY`


key: chroma:document
string_value:
- Type: `str`
- Description: The API key for the Serper search API.

#### `SERPLY_API_KEY`

- Type: `str`
- Description: The API key for the Serply search API.

#### `TAVILY_API_KEY`

- Type: `str`
- Description: The API key for the Tavily search API.

#### `RAG_WEB_SEARCH_RESULT_COUNT`

- Type: `int`
- Default: `3`
- Description: Maximum number of search results to crawl.

#### `RAG_WEB_SEARCH_CONCURRENT_REQUESTS`

- Type: `int`
- Default: `10`
- Description: Number of concurrent requests to crawl web pages returned from search results.

#### `SEARCHAPI_API_KEY`

- Type: `str`
- Description: Sets the SearchAPI API key.

#### `SEARCHAPI_ENGINE`

- Type: `str`
- Description: Sets the SearchAPI engine.

### Speech to Text

#### `AUDIO_STT_ENGINE`

- Type: `str` (enum: `openai`)
- Options:
  - Leave empty to use local Whisper engine for Speech-to-Text.
  - `openai` - Uses OpenAI engine for Speech-to-Text.
- Description: Specifies the Speech-to-Text engine to use.


key: chroma:document
string_value:
#### `AUDIO_STT_OPENAI_API_BASE_URL`

- Type: `str`
- Default: `${OPENAI_API_BASE_URL}`
- Description: Sets the OpenAI-compatible base URL to use for Speech-to-Text.

#### `AUDIO_STT_OPENAI_API_KEY`

- Type: `str`
- Default: `${OPENAI_API_KEY}`
- Description: Sets the OpenAI API key to use for Speech-to-Text.

#### `AUDIO_STT_MODEL`

- Type: `str`
- Default: `whisper-1`
- Description: Specifies the Speech-to-Text model to use for OpenAI-compatible endpoints.

#### `WHISPER_MODEL`

- Type: `str`
- Default: `base`
- Description: Sets the Whisper model to use for Speech-to-Text. The backend used is faster_whisper with quantization to `int8`.

#### `WHISPER_MODEL_DIR`

- Type: `str`
- Default: `${DATA_DIR}/cache/whisper/models`
- Description: Specifies the directory to store Whisper model files.

#### `WHISPER_MODEL_AUTO_UPDATE`

- Type: `bool`
- Default: `False`
- Description: Toggles automatic update of the Whisper model.

### Text to Speech

#### `AUDIO_TTS_ENGINE`


key: chroma:document
string_value:
### Text to Speech

#### `AUDIO_TTS_ENGINE`

- Type: `str` (enum: `elevenlabs`, `openai`)
- Options:
  - Leave empty to use built-in WebAPI engine for Text-to-Speech.
  - `elevenlabs` - Uses ElevenLabs engine for Text-to-Speech
  - `openai` - Uses OpenAI engine for Text-to-Speech.
- Description: Specifies the Text-to-Speech engine to use.

#### `AUDIO_TTS_API_KEY`

- Type: `str`
- Description: Sets the API key for Text-to-Speech.

#### `AUDIO_TTS_OPENAI_API_BASE_URL`

- Type: `str`
- Default: `${OPENAI_API_BASE_URL}`
- Description: Sets the OpenAI-compatible base URL to use for text-to-speech.

#### `AUDIO_TTS_OPENAI_API_KEY`

- Type: `str`
- Default: `${OPENAI_API_KEY}`
- Description: Sets the API key to use for text-to-speech.

#### `AUDIO_TTS_MODEL`

- Type: `str`
- Default: `tts-1`
- Description: Specifies the OpenAI text-to-speech model to use.

#### `AUDIO_TTS_VOICE`

- Type: `str`
- Default: `alloy`
- Description: Sets the OpenAI text-to-speech voice to use.


key: chroma:document
string_value:
- Type: `str`
- Default: `alloy`
- Description: Sets the OpenAI text-to-speech voice to use.

#### `AUDIO_TTS_SPLIT_ON`

- Type: `str`
- Default: `punctuation`
- Description: Sets the OpenAI text-to-speech split on to use.

### Image Generation

#### `ENABLE_IMAGE_GENERATION`

- Type: `bool`
- Default: `False`
- Description: Enables or disables image generation features.

#### `IMAGE_GENERATION_ENGINE`

- Type: `str` (enum: `openai`, `comfyui`, `automatic1111`)
- Options:
  - `openai` - Uses OpenAI DALL-E for image generation.
  - `comfyui` - Uses ComfyUI engine for image generation.
  - `automatic1111` - Uses Automatic1111 engine for image generation (default).
- Default: `automatic1111`
- Description: Specifies the engine to use for image generation.

#### `AUTOMATIC1111_BASE_URL`

- Type: `str`
- Description: Specifies the URL to Automatic1111's Stable Diffusion API.

#### `AUTOMATIC1111_API_AUTH`

- Type: `str`
- Description: Sets the Automatic1111 API authentication.


key: chroma:document
string_value:
- Type: `str`
- Description: Sets the Automatic1111 API authentication.

#### `COMFYUI_BASE_URL`

- Type: `str`
- Description: Specifies the URL to the ComfyUI image generation API.

#### `COMFYUI_WORKFLOW`

- Type: `str`
- Description: Sets the ComfyUI workflow.

#### `IMAGES_OPENAI_API_BASE_URL`

- Type: `str`
- Default: `${OPENAI_API_BASE_URL}`
- Description: Sets the OpenAI-compatible base URL to use for DALL-E image generation.

#### `IMAGES_OPENAI_API_KEY`

- Type: `str`
- Default: `${OPENAI_API_KEY}`
- Description: Sets the API key to use for DALL-E image generation.

#### `IMAGE_GENERATION_MODEL`

- Type: `str`
- Description: Default model to use for image generation

#### `IMAGE_SIZE`

- Type: `str`
- Default: `512x512`
- Description: Sets the default image size to generate.

#### `IMAGE_STEPS`

- Type: `int`
- Default: `50`
- Description: Sets the default iteration steps for image generation. Used for ComfyUI and AUTOMATIC1111.

### OAuth

#### `ENABLE_OAUTH_SIGNUP`


key: chroma:document
string_value:
### OAuth

#### `ENABLE_OAUTH_SIGNUP`

- Type: `bool`
- Default: `False`
- Description: Enables user account creation via OAuth.

#### `OAUTH_MERGE_ACCOUNTS_BY_EMAIL`

- Type: `bool`
- Default: `False`
- Description: If enabled, merges OAuth accounts with existing accounts using the same email
address. This is considered unsafe as providers may not verify email addresses and can lead to
account takeovers.

#### `OAUTH_USERNAME_CLAIM`

- Type: `str`
- Default: `name`
- Description: Set username claim for OpenID.

#### `OAUTH_EMAIL_CLAIM`

- Type: `str`
- Default: `email`
- Description: Set email claim for OpenID.

#### `OAUTH_PICTURE_CLAIM`

- Type: `str`
- Default: `picture`
- Description: Set picture (avatar) claim for OpenID.

#### `OAUTH_CLIENT_ID`

- Type: `str`
- Description: Sets the client ID for OIDC

#### `OAUTH_CLIENT_SECRET`

- Type: `str`
- Description: Sets the client secret for OIDC

#### `OAUTH_SCOPES`


key: chroma:document
string_value:
- Type: `str`
- Description: Sets the client secret for OIDC

#### `OAUTH_SCOPES`

- Type: `str`
- Default: `openid email profile`
- Description: Sets the scope for OIDC authentication. `openid` and `email` are required.

#### `OAUTH_PROVIDER_NAME`

- Type: `str`
- Default: `SSO`
- Description: Sets the name for the OIDC provider.

#### `ENABLE_OAUTH_ROLE_MANAGEMENT`

- Type: `bool`
- Default: `False`
- Description: Enables role management to oauth delegation.

#### `OAUTH_ROLES_CLAIM`

- Type: `str`
- Default: `roles`
- Description: Sets the roles claim to look for in the OIDC token.

#### `OAUTH_ALLOWED_ROLES`

- Type: `str`
- Default: `user,admin`
- Description: Sets the roles that are allowed access to the platform.

#### `OAUTH_ADMIN_ROLES`

- Type: `str`
- Default: `admin`
- Description: Sets the roles that are considered administrators.

#### `GOOGLE_CLIENT_ID`

- Type: `str`
- Description: Sets the client ID for Google OAuth

#### `GOOGLE_CLIENT_SECRET`


key: chroma:document
string_value:
- Type: `str`
- Description: Sets the client ID for Google OAuth

#### `GOOGLE_CLIENT_SECRET`

- Type: `str`
- Description: Sets the client secret for Google OAuth

#### `GOOGLE_OAUTH_SCOPE`

- Type: `str`
- Default: `openid email profile`
- Description: Sets the scope for Google OAuth authentication.

#### `GOOGLE_REDIRECT_URI`

- Type: `str`
- Description: Sets the redirect URI for Google OAuth

#### `MICROSOFT_CLIENT_ID`

- Type: `str`
- Description: Sets the client ID for Microsoft OAuth

#### `MICROSOFT_CLIENT_SECRET`

- Type: `str`
- Description: Sets the client secret for Microsoft OAuth

#### `MICROSOFT_CLIENT_TENANT_ID`

- Type: `str`
- Description: Sets the tenant ID for Microsoft OAuth

#### `MICROSOFT_OAUTH_SCOPE`

- Type: `str`
- Default: `openid email profile`
- Description: Sets the scope for Microsoft OAuth authentication.

#### `MICROSOFT_REDIRECT_URI`

- Type: `str`
- Description: Sets the redirect URI for Microsoft OAuth

#### `OPENID_PROVIDER_URL`


key: chroma:document
string_value:
- Type: `str`
- Description: Sets the redirect URI for Microsoft OAuth

#### `OPENID_PROVIDER_URL`

- Type: `str`
- Description: Path to the `.well-known/openid-configuration` endpoint

#### `OPENID_REDIRECT_URI`

- Type: `str`
- Description: Sets the redirect URI for OIDC

### Tools

#### `TOOLS_DIR`

- Type: `str`
- Default: `${DATA_DIR}/tools`
- Description: Specifies the directory for custom tools.

### Redis

#### `ENABLE_WEBSOCKET_SUPPORT`

- Type: `bool`
- Default: `False`
- Description: Enables websocket support in Open WebUI (used with Redis).

#### `WEBSOCKET_MANAGER`

- Type: `str`
- Default: `redis`
- Description: Specifies the websocket manager to use (in this case, Redis).

#### `WEBSOCKET_REDIS_URL`

- Type: `str`
- Default: `redis://localhost:6379/0`
- Description: Specifies the URL of the Redis instance for websocket communication.

## Misc Environment Variables

These variables are not specific to Open WebUI but can still be valuable in certain contexts.


key: chroma:document
string_value:
These variables are not specific to Open WebUI but can still be valuable in certain contexts.

### Proxy Settings

Open WebUI supports using proxies for HTTP and HTTPS retrievals. To specify proxy settings,
Open WebUI uses the following environment variables:

#### `http_proxy`

- Type: `str`
- Description: Sets the URL for the HTTP proxy.

#### `https_proxy`

- Type: `str`
- Description: Sets the URL for the HTTPS proxy.

#### `no_proxy`

- Type: `str`
- Description: Lists domain extensions (or IP addresses) for which the proxy should not be used,
separated by commas. For example, setting no_proxy to '.mit.edu' ensures that the proxy is
bypassed when accessing documents from MIT.


key: chroma:document
string_value:
---
sidebar_position: 7
title: "❓ FAQ"
---

# FAQ

**What's the difference between Functions and Pipelines?**

The main difference between Functions and Pipelines are that Functions are executed directly on the Open WebUI server, while Pipelines are executed on a separate server. Functions are not capable of downloading new packages in Open WebUI, meaning that you are only able to import libraries into Functions that are packaged into Open WebUI. Pipelines, on the other hand, are more extensible, enabling you to install any Python dependencies your filter or pipe could need. Pipelines also execute on a separate server, potentially reducing the load on your Open WebUI instance.


key: chroma:document
string_value:
---
sidebar_position: 1200
title: "📋 FAQ"
---

import { TopBanners } from "@site/src/components/TopBanners";

<TopBanners />

### 💡 Why Docker?
We understand Docker might not be everyone's preference; however, this approach is central to our project's design and operational efficiency. We view the project's commitment to Docker as a fundamental aspect and encourage those looking for different deployment methods to explore community-driven alternatives.

### 📜 Table of Contents


key: chroma:document
string_value:
- [Q: Why am I asked to sign up? Where are my data being sent to?](#q-why-am-i-asked-to-sign-up-where-are-my-data-being-sent-to)
- [Q: Why can't my Docker container connect to services on the host using localhost?](#q-why-cant-my-docker-container-connect-to-services-on-the-host-using-localhost)
- [Q: How do I make my host's services accessible to Docker containers?](#q-how-do-i-make-my-hosts-services-accessible-to-docker-containers)
- [Q: Why isn't my Open WebUI updating? I've re-pulled/restarted the container, and nothing changed.](#q-why-isnt-my-open-webui-updating-ive-re-pulledrestarted-the-container-and-nothing-changed)
- [Q: Wait, why would I delete my container? Won't I lose my data?](#q-wait-why-would-i-delete-my-container-wont-i-lose-my-data)
- [Q: Should I use the distro-packaged Docker or the official Docker package?](#q-should-i-use-the-distro-packaged-docker-or-the-official-docker-package)
- [Q: Is GPU support available in Docker?](#q-is-gpu-support-available-in-docker)


key: chroma:document
string_value:
- [Q: Is GPU support available in Docker?](#q-is-gpu-support-available-in-docker)
- [Q: Why does Open WebUI emphasize the use of Docker?](#q-why-does-open-webui-emphasize-the-use-of-docker)
- [Q: Why doesn't Speech-to-Text (STT) and Text-to-Speech (TTS) work in my deployment?](#q-why-doesnt-speech-to-text-stt-and-text-to-speech-tts-work-in-my-deployment)
- [Q: Why doesn't Open WebUI include built-in HTTPS support?](#q-why-doesnt-open-webui-include-built-in-https-support)
- [Q: I updated/restarted/installed some new software and now Open WebUI isn't working anymore!](#q-i-updatedrestartedinstalled-some-new-software-and-now-open-webui-isnt-working-anymore)
- [Q: I updated/restarted and now my login isn't working anymore, I had to create a new account and all my chats are gone.](#q-i-updatedrestarted-and-now-my-login-isnt-working-anymore-i-had-to-create-a-new-account-and-all-my-chats-are-gone)


key: chroma:document
string_value:
- [Q: I tried to login and couldn't, made a new account and now I'm being told my account needs to be activated by an admin.](#q-i-tried-to-login-and-couldnt-made-a-new-account-and-now-im-being-told-my-account-needs-to-be-activated-by-an-admin)
- [Q: Why can't Open WebUI start with an SSL error?](#q-why-cant-open-webui-start-with-an-ssl-error)


key: chroma:document
string_value:
#### **Q: Why am I asked to sign up? Where are my data being sent to?**

**A:** We require you to sign up to become the admin user for enhanced security. This ensures that if the Open WebUI is ever exposed to external access, your data remains secure. It's important to note that everything is kept local. We do not collect your data. When you sign up, all information stays within your server and never leaves your device. Your privacy and security are our top priorities, ensuring that your data remains under your control at all times.

#### **Q: Why can't my Docker container connect to services on the host using `localhost`?**


key: chroma:document
string_value:
#### **Q: Why can't my Docker container connect to services on the host using `localhost`?**

**A:** Inside a Docker container, `localhost` refers to the container itself, not the host machine. This distinction is crucial for networking. To establish a connection from your container to services running on the host, you should use the DNS name `host.docker.internal` instead of `localhost`. This DNS name is specially recognized by Docker to facilitate such connections, effectively treating the host as a reachable entity from within the container, thus bypassing the usual `localhost` scope limitation.

#### **Q: How do I make my host's services accessible to Docker containers?**


key: chroma:document
string_value:
#### **Q: How do I make my host's services accessible to Docker containers?**

**A:** To make services running on the host accessible to Docker containers, configure these services to listen on all network interfaces, using the IP address `0.0.0.0`, instead of `127.0.0.1` which is limited to `localhost` only. This configuration allows the services to accept connections from any IP address, including Docker containers. It's important to be aware of the security implications of this setup, especially when operating in environments with potential external access. Implementing appropriate security measures, such as firewalls and authentication, can help mitigate risks.

#### **Q: Why isn't my Open WebUI updating? I've re-pulled/restarted the container, and nothing changed.**

**A:** Updating Open WebUI requires more than just pulling the new Docker image. Here's why your updates might not be showing and how to ensure they do:


key: chroma:document
string_value:
1. **Updating the Docker Image**: The command `docker pull ghcr.io/open-webui/open-webui:main` updates the Docker image but not the running container or its data.
2. **Persistent Data in Docker Volumes**: Docker volumes store data independently of container lifecycles, preserving your data (like chat histories) through updates.
3. **Applying the Update**: Ensure your update takes effect by removing the existing container (which doesn't delete the volume) and creating a new one with the updated image and existing volume attached.

This process updates the app while keeping your data safe.

#### **Q: Wait, why would I delete my container? Won't I lose my data?**

**A:** It's a common concern, but deleting a container doesn't mean you'll lose your data, provided you're using Docker volumes correctly. Here's why:


key: chroma:document
string_value:
- **Volumes Preserve Data**: Docker volumes are designed to persist data outside of container lifecycles. As long as your data is stored in a volume, it remains intact, regardless of what happens to the container.
- **Safe Update Process**: When updating Open WebUI, removing the old container and creating a new one with the updated image does not affect the data stored in volumes. The key is not to explicitly delete the volume with commands like `docker volume rm`.

By following the correct update steps—pulling the new image, removing the old container without deleting the volume, and creating a new container with the updated image and the existing volume—your application code is updated while your data remains unchanged and safe.

#### **Q: Should I use the distro-packaged Docker or the official Docker package?**


key: chroma:document
string_value:
#### **Q: Should I use the distro-packaged Docker or the official Docker package?**

**A:** We recommend using the official Docker package over distro-packaged versions for running Open WebUI. The official Docker package is frequently updated with the latest features, bug fixes, and security patches, ensuring optimal performance and security. Additionally, it supports important functionalities like `host.docker.internal`, which may not be available in distro-packaged versions. This feature is essential for proper network configurations and connectivity within Docker containers.

By choosing the official Docker package, you benefit from consistent behavior across different environments, more reliable troubleshooting support, and access to the latest Docker advancements. The broader Docker community and resources are also more aligned with the official package, providing you with a wealth of information and support for any issues you might encounter.


key: chroma:document
string_value:
Everything you need to run Open WebUI, including your data, remains within your control and your server environment, emphasizing our commitment to your privacy and security. For instructions on installing the official Docker package, please refer to the [Install Docker Engine](https://docs.docker.com/engine/install/) guide on Docker's official documentation site.

#### **Q: Is GPU support available in Docker?**

**A:** GPU support in Docker is available but varies depending on the platform. Officially, GPU support is provided in Docker for Windows and Docker Engine on Linux. Other platforms, such as Docker Desktop for Linux and MacOS, do not currently offer GPU support. This limitation is important to consider for applications requiring GPU acceleration. For the best experience and to utilize GPU capabilities, we recommend using Docker on platforms that officially support GPU integration.

#### **Q: Why does Open WebUI emphasize the use of Docker?**


key: chroma:document
string_value:
#### **Q: Why does Open WebUI emphasize the use of Docker?**

**A:** The decision to use Docker stems from its ability to ensure consistency, isolate dependencies, and simplify deployment across different environments. Docker minimizes compatibility issues and streamlines the process of getting the WebUI up and running, regardless of the underlying system. It's a strategic choice by the project maintainers to harness these benefits, acknowledging that while Docker has a learning curve, the advantages for deployment and maintenance are significant. We understand Docker might not be everyone's preference; however, this approach is central to our project's design and operational efficiency. We view the project's commitment to Docker as a fundamental aspect and encourage those looking for different deployment methods to explore community-driven alternatives.

#### **Q: Why doesn't Speech-to-Text (STT) and Text-to-Speech (TTS) work in my deployment?**


key: chroma:document
string_value:
#### **Q: Why doesn't Speech-to-Text (STT) and Text-to-Speech (TTS) work in my deployment?**

**A:** The functionality of Speech-to-Text (STT) and Text-to-Speech (TTS) services in your deployment may require HTTPS to operate correctly. Modern browsers enforce security measures that restrict certain features, including STT and TTS, to only work under secure HTTPS connections. If your deployment is not configured to use HTTPS, these services might not function as expected. Ensuring your deployment is accessible over HTTPS can resolve these issues, enabling full functionality of STT/TTS features.

#### **Q: Why doesn't Open WebUI include built-in HTTPS support?**


key: chroma:document
string_value:
#### **Q: Why doesn't Open WebUI include built-in HTTPS support?**

**A:** While we understand the desire for an all-in-one solution that includes HTTPS support, we believe such an approach wouldn't adequately serve the diverse needs of our user base. Implementing HTTPS directly within the project could limit flexibility and may not align with the specific requirements or preferences of all users. To ensure that everyone can tailor their setup to their unique environment, we leave the implementation of HTTPS termination to the users for their production deployments. This decision allows for greater adaptability and customization. Though we don't offer official documentation on setting up HTTPS, community members may provide guidance upon request, sharing insights and suggestions based on their experiences.

#### **Q: I updated/restarted/installed some new software and now Open WebUI isn't working anymore!**


key: chroma:document
string_value:
**A:** If your Open WebUI isn't launching post-update or installation of new software, it's likely related to a direct installation approach, especially if you didn't use a virtual environment for your backend dependencies. Direct installations can be sensitive to changes in the system's environment, such as updates or new installations that alter existing dependencies. To avoid conflicts and ensure stability, we recommend using a virtual environment for managing the `requirements.txt` dependencies of your backend. This isolates your Open WebUI dependencies from other system packages, minimizing the risk of such issues.

#### **Q: I updated/restarted and now my login isn't working anymore, I had to create a new account and all my chats are gone.**


key: chroma:document
string_value:
**A:** This issue typically arises when a Docker container is created without mounting a volume for `/app/backend/data` or if the designated Open WebUI volume (usually named `open-webui` in our examples) was unintentionally deleted. Docker volumes are crucial for persisting your data across container lifecycles. If you find yourself needing to create a new account after a restart, it's likely you've initiated a new container without attaching the existing volume where your data resides. Ensure that your Docker run command includes a volume mount pointing to the correct data location to prevent data loss.

#### **Q: I tried to login and couldn't, made a new account and now I'm being told my account needs to be activated by an admin.**


key: chroma:document
string_value:
**A:** This situation occurs when you forget the password for the initial admin account created during the first setup. The first account is automatically designated as the admin account. Creating a new account without access to the admin account will result in the need for admin activation. Avoiding the loss of the initial admin account credentials is crucial for seamless access and management of Open WebUI. See the [Resetting the Admin Password](troubleshooting/password-reset) guide for instructions on recovering the admin account.

#### **Q: Why can't Open WebUI start with an SSL error?**


key: chroma:document
string_value:
#### **Q: Why can't Open WebUI start with an SSL error?**

**A:** The SSL error you're encountering when starting Open WebUI is likely due to the absence of SSL certificates or incorrect configuration of [huggingface.co](https://huggingface.co/). To resolve this issue, you could set up a mirror for HuggingFace, such as [hf-mirror.com](https://hf-mirror.com/), and specify it as the endpoint when starting the Docker container. Use the `-e HF_ENDPOINT=https://hf-mirror.com/` parameter to define the HuggingFace mirror address in the Docker run command. For example, you can modify the Docker run command as follows:

```bash
docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```

#### **Need Further Assistance?**


key: chroma:document
string_value:
#### **Need Further Assistance?**

If you have any further questions or concerns, please reach out to our [GitHub Issues page](https://github.com/open-webui/open-webui/issues) or our [Discord channel](https://discord.gg/5rJgQTnV4s) for more help and information.


key: chroma:document
string_value:
---
sidebar_position: 1
title: "🚰 Filters"
---

# Filters

Filters are used to perform actions against incoming user messages and outgoing assistant (LLM) messages. Potential actions that can be taken in a filter include sending messages to monitoring platforms (such as Langfuse or DataDog), modifying message contents, blocking toxic messages, translating messages to another language, or rate limiting messages from certain users. A list of examples is maintained in the [Pipelines repo](https://github.com/open-webui/pipelines/tree/main/examples/filters). Filters can be executed as a Function or on a Pipelines server. The general workflow can be seen in the image below.

<p align="center">
  <a href="#">
    <img src="/img/pipelines/filters.png" alt="Filter Workflow" />
  </a>
</p>


key: chroma:document
string_value:
When a filter pipeline is enabled on a model or pipe, the incoming message from the user (or "inlet") is passed to the filter for processing. The filter performs the desired action against the message before requesting the chat completion from the LLM model. Finally, the filter performs post-processing on the outgoing LLM message (or "outlet") before it is sent to the user.


key: chroma:document
string_value:
# Helm Setup for Kubernetes

Helm helps you manage Kubernetes applications.

## Prerequisites

- Kubernetes cluster is set up.
- Helm is installed.

## Steps

1. **Add Open WebUI Helm Repository:**

   ```bash
   helm repo add open-webui https://open-webui.github.io/helm-charts
   helm repo update
   ```

2. **Install Open WebUI Chart:**

   ```bash
   helm install openwebui open-webui/open-webui
   ```

3. **Verify Installation:**

   ```bash
   kubectl get pods
   ```

## Access the WebUI

Set up port forwarding or load balancing to access Open WebUI from outside the cluster.


key: chroma:document
string_value:
---
sidebar_position: 6
title: "🔒HTTPS Encryption"
---

## Overview

While HTTPS encryption is **not required** to operate Open WebUI in most cases, certain features—such as **Voice Calls**—will be blocked by modern web browsers unless HTTPS is enabled. If you do not plan to use these features, you can skip this section.

## Importance of HTTPS

For deployments at high risk of traffic interception, such as those hosted on the internet, it is recommended to implement HTTPS encryption. This ensures that the username/password signup and authentication process remains secure, protecting sensitive user data from potential threats.

## Choosing Your HTTPS Solution

The choice of HTTPS encryption solution is up to the user and should align with the existing infrastructure. Here are some common scenarios:


key: chroma:document
string_value:
- **AWS Environments**: Utilizing an AWS Elastic Load Balancer is often a practical choice for managing HTTPS.
- **Docker Container Environments**: Popular solutions include Nginx, Traefik, and Caddy.
- **Cloudflare**: Offers easy HTTPS setup with minimal server-side configuration, suitable for a wide range of applications.
- **Ngrok**: Provides a quick way to set up HTTPS for local development environments, particularly useful for testing and demos.

## Further Guidance

For detailed instructions and community-submitted tutorials on actual HTTPS encryption deployments, please refer to the [Deployment Tutorials](../../tutorials/deployment/).

This documentation provides a starting point for understanding the options available for enabling HTTPS encryption in your environment.


key: chroma:document
string_value:
---
title: "🔒 HTTPS using Nginx"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# HTTPS using Nginx

Ensuring secure communication between your users and the Open WebUI is paramount. HTTPS (HyperText Transfer Protocol Secure) encrypts the data transmitted, protecting it from eavesdroppers and tampering. By configuring Nginx as a reverse proxy, you can seamlessly add HTTPS to your Open WebUI deployment, enhancing both security and trustworthiness.

This guide provides two methods to set up HTTPS:

- **Self-Signed Certificates**: Ideal for development and internal use.
- **Let's Encrypt**: Perfect for production environments requiring trusted SSL certificates.

Choose the method that best fits your deployment needs.


key: chroma:document
string_value:
Choose the method that best fits your deployment needs.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

import SelfSigned from './tab-nginx/SelfSigned.md';
import LetsEncrypt from './tab-nginx/LetsEncrypt.md';

<Tabs>
  <TabItem value="self-signed" label="Self-Signed Certificate">
    <SelfSigned />
  </TabItem>

  <TabItem value="letsencrypt" label="Let's Encrypt">
    <LetsEncrypt />
  </TabItem>
</Tabs>

## Next Steps

After setting up HTTPS, access Open WebUI securely at:

- [https://localhost](https://localhost)

Ensure that your DNS records are correctly configured if you're using a domain name. For production environments, it's recommended to use Let's Encrypt for trusted SSL certificates.

---


key: chroma:document
string_value:
---
sidebar_position: 6
title: "🎨 Image Generation"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# 🎨 Image Generation

Open WebUI supports image generation through three backends: **AUTOMATIC1111**, **ComfyUI**, and **OpenAI DALL·E**. This guide will help you set up and use either of these options.

## AUTOMATIC1111

Open WebUI supports image generation through the **AUTOMATIC1111** [API](https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/API). Here are the steps to get started:

### Initial Setup

1. Ensure that you have [AUTOMATIC1111](https://github.com/AUTOMATIC1111/stable-diffusion-webui) installed.
2. Launch AUTOMATIC1111 with additional flags to enable API access:

   ```
   ./webui.sh --api --listen
   ```


key: chroma:document
string_value:
```
   ./webui.sh --api --listen
   ```

3. For Docker installation of WebUI with the environment variables preset, use the following command:

   ```
   docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -e AUTOMATIC1111_BASE_URL=http://host.docker.internal:7860/ -e ENABLE_IMAGE_GENERATION=True -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
   ```

### Setting Up Open WebUI with AUTOMATIC1111

1. In Open WebUI, navigate to the **Admin Panel** > **Settings** > **Images** menu.
2. Set the `Image Generation Engine` field to `Default (Automatic1111)`.
3. In the API URL field, enter the address where AUTOMATIC1111's API is accessible:

   ```
   http://<your_automatic1111_address>:7860/
   ```

   If you're running a Docker installation of Open WebUI and AUTOMATIC1111 on the same host, use `http://host.docker.internal:7860/` as your address.

## ComfyUI


key: chroma:document
string_value:
## ComfyUI

ComfyUI provides an alternative interface for managing and interacting with image generation models. Learn more or download it from its [GitHub page](https://github.com/comfyanonymous/ComfyUI). Below are the setup instructions to get ComfyUI running alongside your other tools.

### Initial Setup

1. Download and extract the ComfyUI software package from [GitHub](https://github.com/comfyanonymous/ComfyUI) to your desired directory.
2. To start ComfyUI, run the following command:

   ```
   python main.py
   ```

   For systems with low VRAM, launch ComfyUI with additional flags to reduce memory usage:

   ```
   python main.py --lowvram
   ```

3. For Docker installation of WebUI with the environment variables preset, use the following command:


key: chroma:document
string_value:
```
   docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -e COMFYUI_BASE_URL=http://host.docker.internal:7860/ -e ENABLE_IMAGE_GENERATION=True -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
   ```

### Setting Up Open WebUI with ComfyUI

#### Setting Up FLUX.1 Models

1. **Model Checkpoints**:

* Download either the `FLUX.1-schnell` or `FLUX.1-dev` model from the [black-forest-labs HuggingFace page](https://huggingface.co/black-forest-labs).
* Place the model checkpoint(s) in both the `models/checkpoints` and `models/unet` directories of ComfyUI. Alternatively, you can create a symbolic link between `models/checkpoints` and `models/unet` to ensure both directories contain the same model checkpoints.

2. **VAE Model**:

* Download `ae.safetensors` VAE from [here](https://huggingface.co/black-forest-labs/FLUX.1-schnell/blob/main/ae.safetensors).
* Place it in the `models/vae` ComfyUI directory.


key: chroma:document
string_value:
3. **CLIP Model**:

* Download `clip_l.safetensors` from [here](https://huggingface.co/comfyanonymous/flux_text_encoders/tree/main).
* Place it in the `models/clip` ComfyUI directory.

4. **T5XXL Model**:

* Download either the `t5xxl_fp16.safetensors` or `t5xxl_fp8_e4m3fn.safetensors` model from [here](https://huggingface.co/comfyanonymous/flux_text_encoders/tree/main).
* Place it in the `models/clip` ComfyUI directory.

To integrate ComfyUI into Open WebUI, follow these steps:

#### Step 1: Configure Open WebUI Settings

1. Navigate to the **Admin Panel** in Open WebUI.
2. Click on **Settings** and then select the **Images** tab.
3. In the `Image Generation Engine` field, choose `ComfyUI`.
4. In the **API URL** field, enter the address where ComfyUI's API is accessible, following this format: `http://<your_comfyui_address>:8188/`.
   * Set the environment variable `COMFYUI_BASE_URL` to this address to ensure it persists within the WebUI.


key: chroma:document
string_value:
#### Step 2: Verify the Connection and Enable Image Generation

1. Ensure ComfyUI is running and that you've successfully verified the connection to Open WebUI. You won't be able to proceed without a successful connection.
2. Once the connection is verified, toggle on **Image Generation (Experimental)**. More options will be presented to you.
3. Continue to step 3 for the final configuration steps.

#### Step 3: Configure ComfyUI Settings and Import Workflow


key: chroma:document
string_value:
#### Step 3: Configure ComfyUI Settings and Import Workflow

1. Enable developer mode within ComfyUI. To do this, look for the gear icon above the **Queue Prompt** button within ComfyUI and enable the `Dev Mode` toggle.
2. Export the desired workflow from ComfyUI in `API format` using the `Save (API Format)` button. The file will be downloaded as `workflow_api.json` if done correctly.
3. Return to Open WebUI and click the **Click here to upload a workflow.json file** button.
4. Select the `workflow_api.json` file to import the exported workflow from ComfyUI into Open WebUI.
5. After importing the workflow, you must map the `ComfyUI Workflow Nodes` according to the imported workflow node IDs.
6. Set `Set Default Model` to the name of the model file being used, such as `flux1-dev.safetensors`


key: chroma:document
string_value:
:::info
You may need to adjust an `Input Key` or two within Open WebUI's `ComfyUI Workflow Nodes` section to match a node within your workflow.
For example, `seed` may need to be renamed to `noise_seed` to match a node ID within your imported workflow.
:::
:::tip
Some workflows, such as ones that use any of the Flux models, may utilize multiple nodes IDs that is necessary to fill in for their node entry fields within Open WebUI. If a node entry field requires multiple IDs, the node IDs should be comma separated (e.g. `1` or `1, 2`).
:::

6. Click `Save` to apply the settings and enjoy image generation with ComfyUI integrated into Open WebUI!

After completing these steps, your ComfyUI setup should be integrated with Open WebUI, and you can use the Flux.1 models for image generation.

### Configuring with SwarmUI


key: chroma:document
string_value:
### Configuring with SwarmUI

SwarmUI utilizes ComfyUI as its backend. In order to get Open WebUI to work with SwarmUI you will have to append `ComfyBackendDirect` to the `ComfyUI Base URL`. Additionally, you will want to setup SwarmUI with LAN access. After aforementioned adjustments, setting up SwarmUI to work with Open WebUI will be the same as [Step one: Configure Open WebUI Settings](https://github.com/open-webui/docs/edit/main/docs/features/images.md#step-1-configure-open-webui-settings) as outlined above.
![Install SwarmUI with LAN Access](https://github.com/user-attachments/assets/a6567e13-1ced-4743-8d8e-be526207f9f6)

#### SwarmUI API URL

The address you will input as the ComfyUI Base URL will look like: `http://<your_swarmui_address>:7801/ComfyBackendDirect`

## OpenAI DALL·E

Open WebUI also supports image generation through the **OpenAI DALL·E APIs**. This option includes a selector for choosing between DALL·E 2 and DALL·E 3, each supporting different image sizes.


key: chroma:document
string_value:
### Initial Setup

1. Obtain an [API key](https://platform.openai.com/api-keys) from OpenAI.

### Configuring Open WebUI

1. In Open WebUI, navigate to the **Admin Panel** > **Settings** > **Images** menu.
2. Set the `Image Generation Engine` field to `Open AI (Dall-E)`.
3. Enter your OpenAI API key.
4. Choose the DALL·E model you wish to use. Note that image size options will depend on the selected model:
   * **DALL·E 2**: Supports `256x256`, `512x512`, or `1024x1024` images.
   * **DALL·E 3**: Supports `1024x1024`, `1792x1024`, or `1024x1792` images.

### Azure OpenAI

Using Azure OpenAI Dall-E directly is unsupported, but you can [set up a LiteLLM proxy](https://litellm.vercel.app/docs/image_generation) which is compatible with the `Open AI (Dall-E)` Image Generation Engine.

## Using Image Generation

![Image Generation Tutorial](/img/tutorial_image_generation.png)


key: chroma:document
string_value:
## Using Image Generation

![Image Generation Tutorial](/img/tutorial_image_generation.png)

1. First, use a text generation model to write a prompt for image generation.
2. After the response has finished, you can click the Picture icon to generate an image.
3. After the image has finished generating, it will be returned automatically in chat.

:::tip
    You can also edit the LLM's response and enter your image generation prompt as the message
    to send off for image generation instead of using the actual response provided by the
    LLM.
:::


key: chroma:document
string_value:
---
sidebar_position: 0
slug: /
title: 🏡 Home
hide_title: true
---

import { TopBanners } from "@site/src/components/TopBanners";
import { SponsorList } from "@site/src/components/SponsorList";

# Open WebUI

<TopBanners />

**Open WebUI is an [extensible](https://docs.openwebui.com/features/plugin/), feature-rich, and user-friendly self-hosted AI interface designed to operate entirely offline.** It supports various LLM runners, including Ollama and OpenAI-compatible APIs.


key: chroma:document
string_value:
![GitHub stars](https://img.shields.io/github/stars/open-webui/open-webui?style=social)
![GitHub forks](https://img.shields.io/github/forks/open-webui/open-webui?style=social)
![GitHub watchers](https://img.shields.io/github/watchers/open-webui/open-webui?style=social)
![GitHub repo size](https://img.shields.io/github/repo-size/open-webui/open-webui)
![GitHub language count](https://img.shields.io/github/languages/count/open-webui/open-webui)
![GitHub top language](https://img.shields.io/github/languages/top/open-webui/open-webui)
![GitHub last commit](https://img.shields.io/github/last-commit/open-webui/open-webui?color=red)
![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2Follama-webui%2Follama-wbui&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false)
[![Discord](https://img.shields.io/badge/Discord-Open_WebUI-blue?logo=discord&logoColor=white)](https://discord.gg/5rJgQTnV4s)


key: chroma:document
string_value:
[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/tjbck)


key: chroma:document
string_value:
![Open WebUI Demo](/img/demo.gif)

:::info **Important Note on User Roles and Privacy:**

- **Admin Creation:** The first account created on Open WebUI gains **Administrator privileges**, controlling user management and system settings.

- **User Registrations:** Subsequent sign-ups start with **Pending** status, requiring Administrator approval for access.

- **Privacy and Data Security:** **All your data**, including login details, is **locally stored** on your device. Open WebUI ensures **strict confidentiality** and **no external requests** for enhanced privacy and security.

:::

## Quick Start with Docker 🐳 (Recommended)

:::tip

#### Disabling Login for Single User

If you want to disable login for a single-user setup, set [`WEBUI_AUTH`](./getting-started/advanced-topics/env-configuration) to `False`. This will bypass the login page.

:::warning
You cannot switch between single-user mode and multi-account mode after this change.
:::


key: chroma:document
string_value:
:::danger
When using Docker to install Open WebUI, make sure to include the `-v open-webui:/app/backend/data` in your Docker command. This step is crucial as it ensures your database is properly mounted and prevents any loss of data.
:::

<details> 
<summary>Data Storage in Docker</summary>

This tutorial uses [Docker named volumes](https://docs.docker.com/storage/volumes/) to guarantee the **persistance of your data**. This might make it difficult to know exactly where your data is stored in your machine if this is your first time using Docker. Alternatively, you can replace the volume name with a absolute path on your host machine to link your container data to a folder in your computer using a [bind mount](https://docs.docker.com/storage/bind-mounts/).

**Example**: change `-v open-webui:/app/backend/data` to `-v /path/to/folder:/app/backend/data`

Ensure you have the proper access rights to the folder on your host machine.


key: chroma:document
string_value:
Ensure you have the proper access rights to the folder on your host machine.

Visit the [Docker documentation](https://docs.docker.com/storage/) to understand more about volumes and bind mounts.
</details>

### Installation with Default Configuration

- **If Ollama is on your computer**, use this command:

  ```bash
  docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
  ```

- **If Ollama is on a Different Server**, use this command:

  To connect to Ollama on another server, change the `OLLAMA_BASE_URL` to the server's URL:

  ```bash
  docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
  ```

  - **To run Open WebUI with Nvidia GPU support**, use this command:


key: chroma:document
string_value:
- **To run Open WebUI with Nvidia GPU support**, use this command:

  ```bash
  docker run -d -p 3000:8080 --gpus all --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:cuda
  ```

### Installation for OpenAI API Usage Only

- **If you're only using OpenAI API**, use this command:

  ```bash
  docker run -d -p 3000:8080 -e OPENAI_API_KEY=your_secret_key -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
  ```

### Installing Open WebUI with Bundled Ollama Support

This installation method uses a single container image that bundles Open WebUI with Ollama, allowing for a streamlined setup via a single command. Choose the appropriate command based on your hardware setup:

- **With GPU Support**:
  Utilize GPU resources by running the following command:


key: chroma:document
string_value:
- **With GPU Support**:
  Utilize GPU resources by running the following command:

  ```bash
  docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama
  ```

- **For CPU Only**:
  If you're not using a GPU, use this command instead:

  ```bash
  docker run -d -p 3000:8080 -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama
  ```

Both commands facilitate a built-in, hassle-free installation of both Open WebUI and Ollama, ensuring that you can get everything up and running swiftly.

After installation, you can access Open WebUI at [http://localhost:3000](http://localhost:3000). Enjoy! 😄

### Using the Dev Branch 🌙

:::warning
The `:dev` branch contains the latest unstable features and changes. Use it at your own risk as it may have bugs or incomplete features.
:::


key: chroma:document
string_value:
If you want to try out the latest bleeding-edge features and are okay with occasional instability, you can use the `:dev` tag like this:

```bash
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev
```

## Manual Installation

### Installation with `pip` (Beta)

For users who prefer to use Python's package manager `pip`, Open WebUI offers a installation method. Python 3.11 is required for this method.

1. **Install Open WebUI**:
   Open your terminal and run the following command:

   ```bash
   pip install open-webui
   ```

2. **Start Open WebUI**:
   Once installed, start the server using:

   ```bash
   open-webui serve
   ```

This method installs all necessary dependencies and starts Open WebUI, allowing for a simple and efficient setup. After installation, you can access Open WebUI at [http://localhost:8080](http://localhost:8080). Enjoy! 😄

## Other Installation Methods


key: chroma:document
string_value:
## Other Installation Methods

We offer various installation alternatives, including non-Docker native installation methods, Docker Compose, Kustomize, and Helm. Visit our [Open WebUI Documentation](https://docs.openwebui.com/getting-started/) or join our [Discord community](https://discord.gg/5rJgQTnV4s) for comprehensive guidance.

## Troubleshooting

If you're facing various issues like "Open WebUI: Server Connection Error", see [TROUBLESHOOTING](troubleshooting) for information on how to troubleshoot and/or join our [Open WebUI Discord community](https://discord.gg/5rJgQTnV4s).

## Updating

Check out how to update Docker in the [Quick Start guide](./getting-started/quick-start).

In case you want to update your local Docker installation to the latest version, you can do it with [Watchtower](https://containrrr.dev/watchtower/):

```bash
docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui
```


key: chroma:document
string_value:
In the last part of the command, replace `open-webui` with your container name if it is different.

Continue with the full [getting started guide](/getting-started).

## Sponsors 🙌

We are incredibly grateful for the generous support of our sponsors. Their contributions help us to maintain and improve our project, ensuring we can continue to deliver quality work to our community. Thank you!

<SponsorList />


key: chroma:document
string_value:
---
sidebar_position: 11
title: "🖥️ Local LLM Setup with IPEX-LLM on Intel GPU"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

:::note
This guide is verified with Open WebUI setup through [Manual Installation](/getting-started/index.md).
:::

# Local LLM Setup with IPEX-LLM on Intel GPU

:::info
[**IPEX-LLM**](https://github.com/intel-analytics/ipex-llm) is a PyTorch library for running LLM on Intel CPU and GPU (e.g., local PC with iGPU, discrete GPU such as Arc A-Series, Flex and Max) with very low latency.
:::

This tutorial demonstrates how to setup Open WebUI with **IPEX-LLM accelerated Ollama backend hosted on Intel GPU**. By following this guide, you will be able to setup Open WebUI even on a low-cost PC (i.e. only with integrated GPU) with a smooth experience.


key: chroma:document
string_value:
## Start Ollama Serve on Intel GPU

Refer to [this guide](https://ipex-llm.readthedocs.io/en/latest/doc/LLM/Quickstart/ollama_quickstart.html) from IPEX-LLM official documentation about how to install and run Ollama serve accelerated by IPEX-LLM on Intel GPU.

:::tip
If you would like to reach the Ollama service from another machine, make sure you set or export the environment variable `OLLAMA_HOST=0.0.0.0` before executing the command `ollama serve`.
:::

## Configure Open WebUI

Access the Ollama settings through **Settings -> Connections** in the menu. By default, the **Ollama Base URL** is preset to https://localhost:11434, as illustrated in the snapshot below. To verify the status of the Ollama service connection, click the **Refresh button** located next to the textbox. If the WebUI is unable to establish a connection with the Ollama server, you will see an error message stating, `WebUI could not connect to Ollama`.


key: chroma:document
string_value:
![Open WebUI Ollama Setting Failure](https://llm-assets.readthedocs.io/en/latest/_images/open_webui_settings_0.png)

If the connection is successful, you will see a message stating `Service Connection Verified`, as illustrated below.

![Open WebUI Ollama Setting Success](https://llm-assets.readthedocs.io/en/latest/_images/open_webui_settings.png)

:::tip
If you want to use an Ollama server hosted at a different URL, simply update the **Ollama Base URL** to the new URL and press the **Refresh** button to re-confirm the connection to Ollama.
:::


key: chroma:document
string_value:
---
sidebar_position: 16
title: "📎 JWT Expiration"
---

Overview
--------

Open WebUI provides a feature that allows administrators to configure the expiration time of their JWT (JSON Web Token) token. This setting is crucial for ensuring secure access to the API, as it determines how long a JWT token remains valid for.

Configuring JWT Expiration
---------------------------

To configure the JWT expiration time, follow these steps:

### Option 1: Configure through the Admin Panel

1. Log in to your Open WebUI instance as an administrator.
2. Navigate to the `Admin Panel` -> `Settings` -> `General`.
3. Locate the `JWT Expiration` option.
4. Enter the desired expiration time value.
5. Save the changes.

### Option 2: Configure through Environment Variables

Alternatively, you can configure the JWT expiration time by setting the `JWT_EXPIRES_IN` environment variable.


key: chroma:document
string_value:
For more information on configuring environment variables in Open WebUI, see [Environment Variable Configuration](https://docs.openwebui.com/getting-started/advanced-topics/env-configuration#jwt_expires_in).

Generating a Secret Key for JWT Tokens
--------------------------------------

Open WebUI uses a secret key to generate JWT tokens. By default, this secret key is randomly generated on the first start of the container. However, you can override this secret key by setting the `WEBUI_SECRET_KEY` environment variable.

Environment Variable Descriptions
---------------------------------

* `JWT_EXPIRES_IN`:
  * Type: int
  * Default: -1
  * Description: Sets the JWT expiration time in seconds. A value of -1 disables expiration.
* `WEBUI_SECRET_KEY`:
  * Type: str
  * Default: t0p-s3cr3t
  * Docker Default: Randomly generated on first start
  * Description: Overrides the randomly generated string used for JSON Web Token.

Valid Time Units
-----------------


key: chroma:document
string_value:
Valid Time Units
-----------------

* `s`: seconds
* `m`: minutes
* `h`: hours
* `d`: days
* `w`: weeks
* `-1`: no expiration

Authentication with JWT Tokens
---------------------------------

To authenticate your API requests using your JWT token, obtain your API key from `Settings > Account > API Keys > API Key` in Open WebUI. Alternatively, you can obtain a `JWT token` from the same location.

Note: The JWT token is used for authentication purposes only and should be kept secure to prevent unauthorized access to the API.

FAQ
----


key: chroma:document
string_value:
FAQ
----

* Q: What is the default expiration time for JWT tokens in Open WebUI?
A: The default expiration time for JWT tokens in Open WebUI is -1, which disables expiration.
* Q: Can I configure the JWT expiration time using environment variables?
A: Yes, you can configure the JWT expiration time by setting the `JWT_EXPIRES_IN` environment variable.
* Q: What are the valid time units for configuring JWT expiration in Open WebUI?
A: The valid time units are `s`, `m`, `h`, `d`, `w`, or `-1` for no expiration.
* Q: How do I obtain a JWT token for authentication purposes?
A: You can obtain a JWT token from the Open WebUI API or by navigating to `Settings > Account` in the Open WebUI admin panel.
* Q: Can I override the default secret key used for JWT tokens?
A: Yes, you can override the default secret key by setting the `WEBUI_SECRET_KEY` environment variable.


key: chroma:document
string_value:
---
sidebar_position: 1
title: "🧠 Knowledge"
---

 Knowledge part of Open WebUI is like a memory bank that makes your interactions even more powerful and context-aware. Let's break down what "Knowledge" really means in Open WebUI, how it works, and why it's incredibly helpful for enhancing your experience.

## TL;DR

- **Knowledge** is a section in Open WebUI where you can store structured information that the system can refer to during your interactions.
- It's like a memory system for Open WebUI that allows it to pull from saved data, making responses more personalized and contextually aware.
- You can use Knowledge directly in your chats with Open WebUI to access the stored data whenever you need it.

Setting up Knowledge is straightforward! Simply head to the Knowledge section inside work space and start adding details or data. You don't need coding expertise or technical setup; it's built into the core system!

## What is the "Knowledge" Section?


key: chroma:document
string_value:
## What is the "Knowledge" Section?

The **Knowledge section** is a storage area within Open WebUI where you can save specific pieces of information or data points. Think of it as a **reference library** that Open WebUI can use to make its responses more accurate and relevant to your needs.

### Why is Knowledge Useful?

Imagine you're working on a long-term project and want the system to remember certain parameters, settings, or even key notes about the project without having to remind it every time. Or perhaps, you want it to remember specific personal preferences for chats and responses. The Knowledge section is where you can store this kind of **persistent information** so that Open WebUI can reference it in future conversations, creating a more **coherent, personalized experience**.

Some examples of what you might store in Knowledge:


key: chroma:document
string_value:
Some examples of what you might store in Knowledge:

- Important project parameters or specific data points you'll frequently reference.
- Custom commands, workflows, or settings you want to apply.
- Personal preferences, guidelines, or rules that Open WebUI can follow in every chat.

### How to Use Knowledge in Chats

Accessing stored Knowledge in your chats is easy! By simply referencing what's saved(using '#' before the name), Open WebUI can pull in data or follow specific guidelines that you've set up in the Knowledge section.

For example:

- When discussing a project, Open WebUI can automatically recall your specified project details.
- It can apply custom preferences to responses, like formality levels or preferred phrasing.

To reference Knowledge in your chats, just ensure it's saved in the Knowledge section, and Open WebUI will know when and where to bring in the relevant information!


key: chroma:document
string_value:
Admins can add knowledge to the workspace, which users can access and use; however, users do not have direct access to the workspace itself.

### Setting Up Your Knowledge Base

1. **Navigate to the Knowledge Section**: This area is designed to be user-friendly and intuitive.
2. **Add Entries**: Input information you want Open WebUI to remember. It can be as specific or broad as you like.
3. **Save and Apply**: Once saved, the Knowledge is accessible and ready to enhance your chat interactions.

## Summary

- The Knowledge section is like Open WebUI's "memory bank," where you can store data that you want it to remember and use.
- **Use Knowledge to keep the system aware** of important details, ensuring a personalized chat experience.
- You can **directly reference Knowledge in chats** to bring in stored data whenever you need it using '#' + name of the knowlege.

🌟 Remember, there's always more to discover, so dive in and make Open WebUI truly your own!


key: chroma:document
string_value:
# Kustomize Setup for Kubernetes

Kustomize allows you to customize Kubernetes YAML configurations.

## Prerequisites

- Kubernetes cluster is set up.
- Kustomize is installed.

## Steps

1. **Clone the Open WebUI Manifests:**

   ```bash
   git clone https://github.com/open-webui/k8s-manifests.git
   cd k8s-manifests
   ```

2. **Apply the Manifests:**

   ```bash
   kubectl apply -k .
   ```

3. **Verify Installation:**

   ```bash
   kubectl get pods
   ```

## Access the WebUI

Set up port forwarding or load balancing to access Open WebUI from outside the cluster.


key: chroma:document
string_value:
---
sidebar_position: 20
title: "💥 Monitoring and Debugging with Langfuse"
---

# Langfuse Integration with OpenWebUI

[Langfuse](https://langfuse.com/) ([GitHub](https://github.com/langfuse/langfuse)) offers open source observability and evaluations for OpenWebUI. By enabling the Langfuse integration, you can trace your application data with Langfuse to develop, monitor, and improve the use of OpenWebUI, including:

- Application [traces](https://langfuse.com/docs/tracing)
- Usage patterns
- Cost data by user and model
- Replay sessions to debug issues
- [Evaluations](https://langfuse.com/docs/scores/overview)

## How to integrate Langfuse with OpenWebUI

![Langfuse Integration](https://langfuse.com/images/docs/openwebui-integration.gif)
_Langfuse integration steps_


key: chroma:document
string_value:
[Pipelines](https://github.com/open-webui/pipelines/) in OpenWebUi is an UI-agnostic framework for OpenAI API plugins. It enables the injection of plugins that intercept, process, and forward user prompts to the final LLM, allowing for enhanced control and customization of prompt handling.

To trace your application data with Langfuse, you can use the [Langfuse pipeline](https://github.com/open-webui/pipelines/blob/d4fca4c37c4b8603be7797245e749e9086f35130/examples/filters/langfuse_filter_pipeline.py), which enables real-time monitoring and analysis of message interactions.

## Quick Start Guide

### Step 1: Setup OpenWebUI

Make sure to have OpenWebUI running. To do so, have a look at the [OpenWebUI documentation](https://docs.openwebui.com/).

### Step 2: Set Up Pipelines

Launch [Pipelines](https://github.com/open-webui/pipelines/) by using Docker. Use the following command to start Pipelines:


key: chroma:document
string_value:
```bash
docker run -p 9099:9099 --add-host=host.docker.internal:host-gateway -v pipelines:/app/pipelines --name pipelines --restart always ghcr.io/open-webui/pipelines:main
```

### Step 3: Connecting OpenWebUI with Pipelines

In the _Admin Settings_, create and save a new connection of type OpenAI API with the following details:

- **URL:** http://host.docker.internal:9099 (this is where the previously launched Docker container is running).
- **Password:** 0p3n-w3bu! (standard password)

![OpenWebUI Settings](https://langfuse.com/images/docs/openwebui-setup-settings.png)

### Step 4: Adding the Langfuse Filter Pipeline


key: chroma:document
string_value:
### Step 4: Adding the Langfuse Filter Pipeline

Next, navigate to _Admin Settings_ -> _Pipelines_ and add the Langfuse Filter Pipeline. Specify that Pipelines is listening on http://host.docker.internal:9099 (as configured earlier) and install the [Langfuse Filter Pipeline](https://github.com/open-webui/pipelines/blob/main/examples/filters/langfuse_filter_pipeline.py) by using the _Install from Github URL_ option with the following URL:

```
https://github.com/open-webui/pipelines/blob/main/examples/filters/langfuse_filter_pipeline.py
```

Now, add your Langfuse API keys below. If you haven't signed up to Langfuse yet, you can get your API keys by creating an account [here](https://cloud.langfuse.com).

![OpenWebUI add Langfuse Pipeline](https://langfuse.com//images/docs/openwebui-add-pipeline.png)


key: chroma:document
string_value:
![OpenWebUI add Langfuse Pipeline](https://langfuse.com//images/docs/openwebui-add-pipeline.png)

_**Note:** Capture usage (token counts) for OpenAi models while streaming is enabled, you have to navigate to the model settings in OpenWebUI and check the "Usage" [box](https://github.com/open-webui/open-webui/discussions/5770#discussioncomment-10778586) below _Capabilities_._

### Step 5: See your traces in Langfuse

You can now interact with your OpenWebUI application and see the traces in Langfuse.

[Example trace](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/904a8c1f-4974-4f8f-8a2f-129ae78d99c5?observation=fe5b127b-e71c-45ab-8ee5-439d4c0edc28) in the Langfuse UI:

![OpenWebUI Example Trace in Langfuse](https://langfuse.com/images/docs/openwebui-example-trace.png)

## Learn more

For a comprehensive guide on OpenWebUI Pipelines, visit [this post](https://ikasten.io/2024/06/03/getting-started-with-openwebui-pipelines/).


key: chroma:document
string_value:
### Let's Encrypt

Let's Encrypt provides free SSL certificates trusted by most browsers, ideal for production environments.

#### Prerequisites

- **Certbot** installed on your system.
- DNS records properly configured to point to your server.

#### Steps

1. **Create Directories for Nginx Files:**

    ```bash
    mkdir -p conf.d ssl
    ```

2. **Create Nginx Configuration File:**

    **`conf.d/open-webui.conf`:**

    ```nginx
    server {
        listen 80;
        server_name your_domain_or_IP;

        location / {
            proxy_pass http://host.docker.internal:3000;
            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;

            # (Optional) Disable proxy buffering for better streaming response from models
            proxy_buffering off;
        }
    }
    ```

3. **Simplified Let's Encrypt Script:**


key: chroma:document
string_value:
3. **Simplified Let's Encrypt Script:**

    **`enable_letsencrypt.sh`:**

    ```bash
    #!/bin/bash

    # Description: Simplified script to obtain and install Let's Encrypt SSL certificates using Certbot.

    DOMAIN="your_domain_or_IP"
    EMAIL="your_email@example.com"

    # Install Certbot if not installed
    if ! command -v certbot &> /dev/null; then
        echo "Certbot not found. Installing..."
        sudo apt-get update
        sudo apt-get install -y certbot python3-certbot-nginx
    fi

    # Obtain SSL certificate
    sudo certbot --nginx -d "$DOMAIN" --non-interactive --agree-tos -m "$EMAIL"

    # Reload Nginx to apply changes
    sudo systemctl reload nginx

    echo "Let's Encrypt SSL certificate has been installed and Nginx reloaded."
    ```

    **Make the script executable:**

    ```bash
    chmod +x enable_letsencrypt.sh
    ```

4. **Update Docker Compose Configuration:**

    Add the Nginx service to your `docker-compose.yml`:


key: chroma:document
string_value:
Add the Nginx service to your `docker-compose.yml`:

    ```yaml
    services:
      nginx:
        image: nginx:alpine
        ports:
          - "80:80"
          - "443:443"
        volumes:
          - ./conf.d:/etc/nginx/conf.d
          - ./ssl:/etc/nginx/ssl
        depends_on:
          - open-webui
    ```

5. **Start Nginx Service:**

    ```bash
    docker compose up -d nginx
    ```

6. **Run the Let's Encrypt Script:**

    Execute the script to obtain and install the SSL certificate:

    ```bash
    ./enable_letsencrypt.sh
    ```

#### Access the WebUI

Access Open WebUI via HTTPS at:

[https://your_domain_or_IP](https://your_domain_or_IP)


key: chroma:document
string_value:
---
sidebar_position: 5
title: "📜 Open WebUI Logging"
---

## Browser Client Logging ##

Client logging generally occurs via [JavaScript](https://developer.mozilla.org/en-US/docs/Web/API/console/log_static) `console.log()` and can be accessed using the built-in browser-specific developer tools:

* Blink
  * [Chrome/Chromium](https://developer.chrome.com/docs/devtools/)
  * [Edge](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/overview)
* Gecko
  * [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/)
* WebKit
  * [Safari](https://developer.apple.com/safari/tools/)

## Application Server/Backend Logging ##

Logging is an ongoing work-in-progress but some level of control is available using environment variables. [Python Logging](https://docs.python.org/3/howto/logging.html) `log()` and `print()` statements send information to the console. The default level is `INFO`. Ideally, sensitive data will only be exposed with `DEBUG` level.


key: chroma:document
string_value:
### Logging Levels ###

The following [logging levels](https://docs.python.org/3/howto/logging.html#logging-levels) values are supported:

| Level      | Numeric value |
| ---------- | ------------- |
| `CRITICAL` | 50            |
| `ERROR`    | 40            |
| `WARNING`  | 30            |
| `INFO`     | 20            |
| `DEBUG`    | 10            |
| `NOTSET`   | 0             |

### Global ###

The default global log level of `INFO` can be overridden with the `GLOBAL_LOG_LEVEL` environment variable. When set, this executes a [basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig) statement with the `force` argument set to *True* within `config.py`. This results in reconfiguration of all attached loggers:
> *If this keyword argument is specified as true, any existing handlers attached to the root logger are removed and closed, before carrying out the configuration as specified by the other arguments.*


key: chroma:document
string_value:
The stream uses standard output (`sys.stdout`). In addition to all Open-WebUI `log()` statements, this also affects any imported Python modules that use the Python Logging module `basicConfig` mechanism including [urllib](https://docs.python.org/3/library/urllib.html).

For example, to set `DEBUG` logging level as a Docker parameter use:

```
--env GLOBAL_LOG_LEVEL="DEBUG"
```

### App/Backend ###

Some level of granularity is possible using any of the following combination of variables. Note that `basicConfig` `force` isn't presently used so these statements may only affect Open-WebUI logging and not 3rd party modules.


key: chroma:document
string_value:
| Environment Variable | App/Backend                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `AUDIO_LOG_LEVEL`    | Audio transcription using faster-whisper, TTS etc.                |
| `COMFYUI_LOG_LEVEL`  | ComfyUI integration handling                                      |
| `CONFIG_LOG_LEVEL`   | Configuration handling                                            |
| `DB_LOG_LEVEL`       | Internal Peewee Database                                          |
| `IMAGES_LOG_LEVEL`   | AUTOMATIC1111 stable diffusion image generation                   |
| `LITELLM_LOG_LEVEL`  | LiteLLM proxy                                                     |
| `MAIN_LOG_LEVEL`     | Main (root) execution                                             |
| `MODELS_LOG_LEVEL`   | LLM model interaction, authentication, etc.                       |


key: chroma:document
string_value:
| `MODELS_LOG_LEVEL`   | LLM model interaction, authentication, etc.                       |
| `OLLAMA_LOG_LEVEL`   | Ollama backend interaction                                        |
| `OPENAI_LOG_LEVEL`   | OpenAI interaction                                                |
| `RAG_LOG_LEVEL`      | Retrieval-Augmented Generation using Chroma/Sentence-Transformers |
| `WEBHOOK_LOG_LEVEL`  | Authentication webhook extended logging                           |


key: chroma:document
string_value:
# Manual Docker Setup

If you prefer to set up Docker manually, follow these steps for Open WebUI.

## Step 1: Pull the Open WebUI Image

Start by pulling the latest Open WebUI Docker image from the GitHub Container Registry.

```bash
docker pull ghcr.io/open-webui/open-webui:main
```

## Step 2: Run the Container

Run the container with default settings. This command includes a volume mapping to ensure persistent data storage.

```bash
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
```

### Important Flags

- **Volume Mapping (`-v open-webui:/app/backend/data`)**: Ensures persistent storage of your data. This prevents data loss between container restarts.
- **Port Mapping (`-p 3000:8080`)**: Exposes the WebUI on port 3000 of your local machine.

### Using GPU Support

For Nvidia GPU support, add `--gpus all` to the `docker run` command:


key: chroma:document
string_value:
### Using GPU Support

For Nvidia GPU support, add `--gpus all` to the `docker run` command:

```bash
docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:cuda
```

## User Roles and Privacy

:::info **Important Note on User Roles and Privacy:**

- **Admin Creation**: The first account created on Open WebUI will have **Administrator privileges**, managing user access and system settings.
- **User Registrations**: Additional accounts start with a **Pending** status, requiring Administrator approval for access.
- **Data Security**: **All your data** is stored locally on your device, ensuring **privacy** and **no external requests**. Open WebUI does not transmit data externally by default.

:::

## Single-User Mode (Disabling Login)

To bypass the login page for a single-user setup, set the `WEBUI_AUTH` environment variable to `False`:


key: chroma:document
string_value:
```bash
docker run -d -p 3000:8080 -e WEBUI_AUTH=False -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
```

:::warning
You cannot switch between single-user mode and multi-account mode after this change.
:::

## Quick Start with Docker 🐳

### Essential Docker Command Options

For Docker installation, consider the following options:

- **Persistent Storage**: Use the `-v open-webui:/app/backend/data` option to ensure all application data remains available across sessions.
- **Exposing Ports**: Use the `-p` flag to map internal container ports to your system.

For example, if you're installing Open WebUI with data persistence and local-only port exposure, the command would be:

```bash
docker run -d -p 127.0.0.1:3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```

### Advanced Configuration: Connecting to Ollama on a Different Server


key: chroma:document
string_value:
### Advanced Configuration: Connecting to Ollama on a Different Server

To connect Open WebUI to an Ollama server located on another host, add the `OLLAMA_BASE_URL` environment variable:

```bash
docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```

### GPU Support with Nvidia

For running Open WebUI with Nvidia GPU support, use:

```bash
docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:cuda
```

## Access the WebUI

After the container is running, access Open WebUI at:

[http://localhost:3000](http://localhost:3000)

For detailed help on each Docker flag, see [Docker's documentation](https://docs.docker.com/engine/reference/commandline/run/).


key: chroma:document
string_value:
---
sidebar_position: 8
title: "🧠 Memory (Experimental)"
---

COMING SOON!

🧠 Memory Feature: Manually add information you want your LLMs to remember via the Settings > Personalization > Memory menu. Memories can be added, edited, and deleted.


key: chroma:document
string_value:
---
sidebar_position: 3
title: "🌊 MermaidJS Rendering"
---

# 🌊 MermaidJS Rendering Support in Open WebUI

## Overview

Open WebUI supports rendering of visually appealing MermaidJS diagrams, flowcharts, pie charts and more, directly within the chat interface. MermaidJS is a powerful tool for visualizing complex information and ideas, and when paired with the capabilities of a large language model (LLM), it can be a powerful tool for generating and exploring new ideas.

## Using MermaidJS in Open WebUI

To generate a MermaidJS diagram, simply ask an LLM within any chat to create a diagram or chart using MermaidJS. For example, you can ask the LLM to:

* "Create a flowchart for a simple decision-making process for me using Mermaid. Explain how the flowchart works."
* "Use Mermaid to visualize a decision tree to determine whether it's suitable to go for a walk outside."


key: chroma:document
string_value:
Note that for the LLM's response to be rendered correctly, it must begin with the word `mermaid` followed by the MermaidJS code. You can reference the [MermaidJS documentation](https://mermaid.js.org/intro/) to ensure the syntax is correct and provide structured prompts to the LLM to guide it towards generating better MermaidJS syntax.

## Visualizing MermaidJS Code Directly in the Chat

When you request a MermaidJS visualization, the Large Language Model (LLM) will generate the necessary code. Open WebUI will automatically render the visualization directly within the chat interface, as long as the code uses valid MermaidJS syntax.


key: chroma:document
string_value:
If the model generates MermaidJS syntax, but the visualization does not render, it usually indicates a syntax error in the code. Don't worry – you'll be notified of any errors once the response has been fully generated. If this happens, try referencing the [MermaidJS documentation](https://mermaid.js.org/intro/) to identify the issue and revise the prompt accordingly.

## Interacting with Your Visualization

Once your visualization is displayed, you can:

* Zoom in and out to examine it more closely.
* Copy the original MermaidJS code used to generate the visualization by clicking the copy button at the top-right corner of the display area.

### Example

```mermaid
graph TD;
  A-->B;
  B-->C{Decision};
  C--Yes-->D;
  C--No-->E;
  D-->F;
  E-->F;
```

This will generate a flowchart like the following:

```markdown
 startAncestor [ start ]
A[A] --> B[B]
B --> C[Decision]
C -->| Yes | D[D]
C -->| No  | E[E]
D --> F[F]
E --> F[F]
```


key: chroma:document
string_value:
Experimenting with different types of diagrams and charts can help you develop a more nuanced understanding of how to effectively leverage MermaidJS within Open WebUI. For smaller models, consider referencing the [MermaidJS documentation](https://mermaid.js.org/intro/) to provide guidance for the LLM, or have it summarize the documentation into comprehensive notes or a system prompt. By following these guidelines and exploring the capabilities of MermaidJS, you can unlock the full potential of this powerful tool in Open WebUI.


key: chroma:document
string_value:
---
sidebar_position: 2
title: "🎙️ Troubleshooting Microphone Access"
---

Ensuring your application has the proper microphone access is crucial for functionality that depends on audio input. This guide covers how to manage and troubleshoot microphone permissions, particularly under secure contexts.

## Understanding Secure Contexts 🔒

For security reasons, accessing the microphone is restricted to pages served over HTTPS or locally from `localhost`. This requirement is meant to safeguard your data by ensuring it is transmitted over secure channels.

## Common Permission Issues 🚫

Browsers like Chrome, Brave, Microsoft Edge, Opera, and Vivaldi, as well as Firefox, restrict microphone access on non-HTTPS URLs. This typically becomes an issue when accessing a site from another device within the same network (e.g., using a mobile phone to access a desktop server). Here's how you can manage these issues:

### Solutions for Non-HTTPS Connections


key: chroma:document
string_value:
### Solutions for Non-HTTPS Connections

1. **Set Up HTTPS:**
   - It is highly recommended to configure your server to support HTTPS. This not only resolves permission issues but also enhances the security of your data transmissions.

2. **Temporary Browser Flags (Use with caution):**
   - These settings force your browser to treat certain insecure URLs as secure. This is useful for development purposes but poses significant security risks. Here's how to adjust these settings for major browsers:

   #### Chromium-based Browsers (e.g., Chrome, Brave)
   - Open `chrome://flags/#unsafely-treat-insecure-origin-as-secure`.
   - Enter your non-HTTPS address (e.g., `http://192.168.1.35:3000`).
   - Restart the browser to apply the changes.

   #### Firefox-based Browsers
   - Open `about:config`.
   - Search and modify (or create) the string value `dom.securecontext.allowlist`.
   - Add your IP addresses separated by commas (e.g., `http://127.0.0.1:8080`).

### Considerations and Risks 🚨


key: chroma:document
string_value:
### Considerations and Risks 🚨

While browser flags offer a quick fix, they bypass important security checks which can expose your device and data to vulnerabilities. Always prioritize proper security measures, especially when planning for a production environment.

By following these best practices, you can ensure that your application properly accesses the microphone while maintaining the security and integrity of your data.


key: chroma:document
string_value:
---
sidebar_position: 2000
title: "🎯 Our Mission"
---

import { TopBanners } from "@site/src/components/TopBanners";

<TopBanners />

Hello there! 👋

Imagine a world where local, open models that can run on any machine, united as one, outperform proprietary giants like GPT-4. Even better, imagine us all having the capability to train and reproduce state-of-the-art models like GPT-4 or GPT-5 from scratch, using high-quality, curated data.

Here's the thing, though: one of the biggest challenges in creating these foundation and fine-tune models is the substantial need for **[high-quality data](https://arxiv.org/abs/2305.11206)**, which is both costly and time-consuming to gather and curate. This is where Open WebUI's mission comes into play. Our mission is to contribute to this vision by building the best AI interface and crowdsourcing curated datasets from our community of users.

— [Tim](https://github.com/tjbck)

---


key: chroma:document
string_value:
— [Tim](https://github.com/tjbck)

---

Our mission is founded on the belief that AI technologies hold transformative potential for society, yet their benefits have been narrowly confined due to complex setup requirements. Recognizing this, we are dedicated to democratizing AI by developing an easy-to-install, feature-rich local WebUI that is designed to operate locally without internet access. Enabling anyone with basic technical skills to tap into the power of AI, effectively bringing its capabilities to communities far and wide.

At the heart of our efforts is the creation of an open-sourced ecosystem of AI tools. Our commitment lies in making AI not only accessible but also beneficial for everyone. We envision a future where AI acts as a lever for societal advancement, driving progress, and technological breakthroughs across all communities.


key: chroma:document
string_value:
By eliminating technological barriers and making AI's advantages universally accessible, we aim to foster a positive impact worldwide. Our ultimate goal is to ensure that AI serves as a catalyst for positive change, helping to bridge gaps and create a more equitable society where everyone can benefit from the advancements in technology.

### Our Vision: Shaping the Future Together


key: chroma:document
string_value:
### Our Vision: Shaping the Future Together

At the heart of our mission lies a profound commitment not just to envision a future where advanced AI technology is universally accessible, but to actively build towards it. Our efforts extend beyond the development of our WebUI; We are at the forefront of creating an ecosystem that embodies the democratization of AI technology. This ecosystem, envisioned as a vibrant, community-driven platform, will be a repository of shared knowledge—ranging from model presets and custom prompts to valuable chat logs. A space where the collective intelligence of our community acts as the driving force for the continuous evolution and refinement of AIs, ensuring these advancements serve us, the actual users of these technologies.


key: chroma:document
string_value:
Our strategy aims to tackle the complex challenges of AI, such as model fine-tuning and dataset curation, head-on. Leveraging the collective skills and insights of our community, we'll forge innovative pathways that not only enhance the precision and relevance of AI models but also guarantee these improvements are shared openly. Our objective is unequivocal: to democratize access to refined, user-curated datasets, thereby eliminating barriers to advancing AI for all.

As we navigate this journey, our vision serves as our north star, guiding our efforts to turn bold ambitions into reality. We extend an invitation for you to join us in this endeavor, as we work diligently to ensure AI technology becomes an empowering resource for individuals and communities across the globe.


key: chroma:document
string_value:
---
sidebar_position: 0
title: "🤖 Models"
---

The `Models` section of the `Workspace` within Open WebUI is a powerful tool that allows you to create and manage custom models tailored to specific purposes. This section serves as a central hub for all your modelfiles, providing a range of features to edit, clone, share, export, and hide your models.

### Modelfile Management

From the `Models` section, you can perform the following actions on your modelfiles:


key: chroma:document
string_value:
From the `Models` section, you can perform the following actions on your modelfiles:

* **Edit**: Dive into the details of your modelfile and make changes to its character and more.
* **Clone**: Create a copy of a modelfile, which will be appended with `-clone` to the cloned `Model ID`. Note that you cannot clone a base model; you must create a model first before cloning it.
* **Share**: Share your modelfile with the Open WebUI community by clicking the `Share` button, which will redirect you to [https://openwebui.com/models/create](https://openwebui.com/models/create).
* **Export**: Download the modelfile's `.json` export to your PC.
* **Hide**: Hide the modelfile from the model selector dropdown within chats.

### Modelfile Editing

When editing a modelfile, you can customize the following settings:


key: chroma:document
string_value:
### Modelfile Editing

When editing a modelfile, you can customize the following settings:

* **Avatar Photo**: Upload an avatar photo to represent your modelfile.
* **Model Name**: Change the name of your modelfile.
* **System Prompt**: Provide an optional system prompt for your modelfile.
* **Model Parameters**: Adjust the parameters of your modelfile.
* **Prompt Suggestions**: Add prompts that will be displayed on a fresh new chat page.
* **Documents**: Add documents to the modelfile (always RAG [Retrieval Augmented Generation]).
* **Tools, Filters, and Actions**: Select the tools, filters, and actions that will be available to the modelfile.
* **Vision**: Toggle to enable `Vision` for multi-modals.
* **Tags**: Add tags to the modelfile that will be displayed beside the model name in the model selector dropdown.

### Model Discovery and Import/Export

The `Models` section also includes features for importing and exporting models:


key: chroma:document
string_value:
The `Models` section also includes features for importing and exporting models:

* **Import Models**: Use this button to import models from a .json file or other sources.
* **Export Models**: Use this button to export all your modelfiles in a single .json file.

To download models, navigate to the **Ollama Settings** in the Connections tab.
Alternatively, you can also download models directly by typing a command like `ollama run hf.co/[model creator]/[model name]` in the model selection dropdown.
This action will create a button labeled "Pull [Model Name]" for downloading.

### Model Switching

   **Example**: Switching between **Mistral**, **LLaVA**, and **GPT-3.5** in a Multi-Stage Task


key: chroma:document
string_value:
**Example**: Switching between **Mistral**, **LLaVA**, and **GPT-3.5** in a Multi-Stage Task

* **Scenario**: A multi-stage conversation involves different task types, such as starting with a simple FAQ, interpreting an image, and then generating a creative response.
* **Reason for Switching**: The user can leverage each model's specific strengths for each stage:
  * **Mistral** for general questions to reduce computation time and costs.
  * **LLaVA** for visual tasks to gain insights from image-based data.
  * **GPT-3.5** for generating more sophisticated and nuanced language output.
* **Process**: The user switches between models, depending on the task type, to maximize efficiency and response quality.


key: chroma:document
string_value:
**How To**:
    1. **Select the Model**: Within the chat interface, select the desired models from the model switcher dropdown. You can select up to two models simultaneously, and both responses will be generated. You can then navigate between them by using the back and forth arrows.
    2. **Context Preservation**: Open WebUI retains the conversation context across model switches, allowing smooth transitions.


key: chroma:document
string_value:
---
sidebar_position: 3
title: "🕸️ Network Diagrams"
---

Here, we provide clear and structured diagrams to help you understand how various components of the network interact within different setups. This documentation is designed to assist both macOS/Windows and Linux users. Each scenario is illustrated using Mermaid diagrams to show how the interactions are set up depending on the different system configurations and deployment strategies.

## Mac OS/Windows Setup Options 🖥️

### Ollama on Host, Open WebUI in Container

In this scenario, `Ollama` runs directly on the host machine while `Open WebUI` operates within a Docker container.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Mac OS/Windows") {
   Person(user, "User")
   Boundary(b1, "Docker Desktop's Linux VM") {
      Component(openwebui, "Open WebUI", "Listening on port 8080")
   }
   Component(ollama, "Ollama", "Listening on port 11434")
}
Rel(openwebui, ollama, "Makes API calls via Docker proxy", "http://host.docker.internal:11434")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

### Ollama and Open WebUI in Compose Stack

Both `Ollama` and `Open WebUI` are configured within the same Docker Compose stack, simplifying network communications.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Mac OS/Windows") {
   Person(user, "User")
   Boundary(b1, "Docker Desktop's Linux VM") {
      Boundary(b2, "Compose Stack") {
         Component(openwebui, "Open WebUI", "Listening on port 8080")
         Component(ollama, "Ollama", "Listening on port 11434")
      }
   }
}
Rel(openwebui, ollama, "Makes API calls via inter-container networking", "http://ollama:11434")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

### Ollama and Open WebUI, Separate Networks

Here, `Ollama` and `Open WebUI` are deployed in separate Docker networks, potentially leading to connectivity issues.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Mac OS/Windows") {
   Person(user, "User")
   Boundary(b1, "Docker Desktop's Linux VM") {
      Boundary(b2, "Network A") {
         Component(openwebui, "Open WebUI", "Listening on port 8080")
      }
      Boundary(b3, "Network B") {
         Component(ollama, "Ollama", "Listening on port 11434")
      }
   }
}
Rel(openwebui, ollama, "Unable to connect")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

### Open WebUI in Host Network

In this configuration, `Open WebUI` utilizes the host network, which impacts its ability to connect in certain environments.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Mac OS/Windows") {
   Person(user, "User")
   Boundary(b1, "Docker Desktop's Linux VM") {
      Component(openwebui, "Open WebUI", "Listening on port 8080")
   }
}
Rel(user, openwebui, "Unable to connect, host network is the VM's network")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```


## Linux Setup Options 🐧

### Ollama on Host, Open WebUI in Container (Linux)

This diagram is specific to the Linux platform, with `Ollama` running on the host and `Open WebUI` deployed inside a Docker container.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Linux") {
   Person(user, "User")
   Boundary(b1, "Container Network") {
      Component(openwebui, "Open WebUI", "Listening on port 8080")
   }
   Component(ollama, "Ollama", "Listening on port 11434")
}
Rel(openwebui, ollama, "Makes API calls via Docker proxy", "http://host.docker.internal:11434")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

### Ollama and Open WebUI in Compose Stack (Linux)

A set-up where both `Ollama` and `Open WebUI` reside within the same Docker Compose stack, allowing for straightforward networking on Linux.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Linux") {
   Person(user, "User")
   Boundary(b1, "Container Network") {
      Boundary(b2, "Compose Stack") {
         Component(openwebui, "Open WebUI", "Listening on port 8080")
         Component(ollama, "Ollama", "Listening on port 11434")
      }
   }
}
Rel(openwebui, ollama, "Makes API calls via inter-container networking", "http://ollama:11434")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

### Ollama and Open WebUI, Separate Networks (Linux)

A scenario in which `Ollama` and `Open WebUI` are in different Docker networks under a Linux environment, which could hinder connectivity.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Linux") {
   Person(user, "User")
   Boundary(b2, "Container Network A") {
      Component(openwebui, "Open WebUI", "Listening on port 8080")
   }
   Boundary(b3, "Container Network B") {
      Component(ollama, "Ollama", "Listening on port 11434")
   }
}
Rel(openwebui, ollama, "Unable to connect")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

### Open WebUI in Host Network, Ollama on Host (Linux)

An optimal layout where both `Open WebUI` and `Ollama` use the host's network, facilitating seamless interaction on Linux systems.


key: chroma:document
string_value:
```mermaid
C4Context
Boundary(b0, "Hosting Machine - Linux") {
   Person(user, "User")
   Component(openwebui, "Open WebUI", "Listening on port 8080")
   Component(ollama, "Ollama", "Listening on port 11434")
}
Rel(openwebui, ollama, "Makes API calls via localhost", "http://localhost:11434")
Rel(user, openwebui, "Makes requests via listening port", "http://localhost:8080")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

Each setup addresses different deployment strategies and networking configurations to help you choose the best layout for your requirements.


key: chroma:document
string_value:
---
sidebar_position: 14
title: "⚖️ Ollama Load Balancing"
---

# ⚖️ Ollama Load Balancing Setup

This guide demonstrates how to configure Open WebUI to connect to multiple Ollama instances for load balancing within your deployment. This approach enables you to distribute processing loads across several nodes, enhancing both performance and reliability. The configuration leverages environment variables to manage connections between container updates, rebuilds, or redeployments seamlessly.

## Docker Run

To connect to multiple Ollama instances with Docker, use the following example command:

```bash
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URLS="http://ollama-one:11434;http://ollama-two:11434" \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main
```

This command configures your Docker container with these key environment variables:


key: chroma:document
string_value:
This command configures your Docker container with these key environment variables:

- `OLLAMA_BASE_URLS`: Specifies the base URLs for each Ollama instance, separated by semicolons (`;`). This example uses two instances, but you can adjust this to fit your setup.

Ensure both Ollama instances are of the same version and have matching tags for each model they share. Discrepancies in model versions or tags across instances can lead to errors due to how WebUI de-duplicates and merges model lists.

## Docker Compose

For those preferring `docker-compose`, here's an abridged version of a `docker-compose.yaml` file:

```yaml
services:
  open-webui:
    environment:
      - OLLAMA_BASE_URLS=http://ollama-one:11434;http://ollama-two:11434
```

To further streamline this setup, you can define `OLLAMA_BASE_URLS` in an `.env` file located in the same directory as your `docker-compose.yaml`. Your `.env` file might look like this:


key: chroma:document
string_value:
```ini
OLLAMA_BASE_URLS="http://ollama-one:11434;http://ollama-two:11434"
```

## Ensuring Model Consistency

Both Ollama instances must run identical versions and tags for each shared model to prevent issues. The system allows for models to be present on one server and not the other, smartly routing requests to the server containing the requested model. However, having different versions or hashes for the same model tag across instances can cause inconsistencies.

Utilize the `Update All Models` button beside the server selector drop-down within the **Settings > Models** screen to keep models synchronized across instances.

By following these steps, you can effectively distribute the computational load across multiple Ollama instances, ensuring a robust and efficient deployment with Open WebUI.


key: chroma:document
string_value:
---
sidebar_position: 1
title: "🗨️ Openai-edge-tts Using Docker"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# Integrating `openai-edge-tts` 🗣️ with Open WebUI

## What is `openai-edge-tts`, and how is it different from `openedai-speech`?

Similar to [openedai-speech](https://github.com/matatonic/openedai-speech), [openai-edge-tts](https://github.com/travisvn/openai-edge-tts) is a text-to-speech API endpoint that mimics the OpenAI API endpoint, allowing for a direct substitute in scenarios where the OpenAI Speech endpoint is callable and the server endpoint URL can be configured.

`openedai-speech` is a more comprehensive option that allows for entirely offline generation of speech with many modalities to choose from.


key: chroma:document
string_value:
`openai-edge-tts` is a simpler option that uses a Python package called `edge-tts` to generate the audio.

`edge-tts` ([repo](https://github.com/rany2/edge-tts)) leverages the Edge browser's free "Read Aloud" feature to emulate a request to Microsoft / Azure in order to receive very high quality text-to-speech for free.

## Requirements

- Docker installed on your system
- Open WebUI running
- ffmpeg (Optional - Only required if opting to not use `mp3` format)

## ⚡️ Quick start

The simplest way to get started without having to configure anything is to run the command below

```bash
docker run -d -p 5050:5050 travisvn/openai-edge-tts:latest
```

This will run the service at port 5050 with all the default configs

## Setting up Open WebUI to use `openai-edge-tts`

- Open the Admin Panel and go to Settings -> Audio
- Set your TTS Settings to match the screenshot below
- _Note: you can specify the TTS Voice here_


key: chroma:document
string_value:
![Screenshot of Open WebUI Admin Settings for Audio adding the correct endpoints for this project](https://utfs.io/f/MMMHiQ1TQaBo9GgL4WcUbjSRlqi86sV3TXh47KYBJCkdQ20M)

:::info
The default API key is the string `your_api_key_here`. You do not have to change that value if you do not need the added security.
:::

**And that's it! You can end here**

See the [Usage](#usage) section for request examples.

# Please ⭐️ star the repo on GitHub if you find [OpenAI Edge TTS](https://github.com/travisvn/openai-edge-tts) useful

:::tip
You can define the environment variables directly in the `docker run` command. See [Quick Config for Docker](#-quick-config-for-docker) below.
:::

## Alternative Options

### 🐍 Running with Python

If you prefer to run this project directly with Python, follow these steps to set up a virtual environment, install dependencies, and start the server.

#### 1. Clone the Repository


key: chroma:document
string_value:
#### 1. Clone the Repository

```bash
git clone https://github.com/travisvn/openai-edge-tts.git
cd openai-edge-tts
```

#### 2. Set Up a Virtual Environment

Create and activate a virtual environment to isolate dependencies:

```bash
# For macOS/Linux
python3 -m venv venv
source venv/bin/activate

# For Windows
python -m venv venv
venv\Scripts\activate
```

#### 3. Install Dependencies

Use `pip` to install the required packages listed in `requirements.txt`:

```bash
pip install -r requirements.txt
```

#### 4. Configure Environment Variables

Create a `.env` file in the root directory and set the following variables:

```plaintext
API_KEY=your_api_key_here
PORT=5050

DEFAULT_VOICE=en-US-AndrewNeural
DEFAULT_RESPONSE_FORMAT=mp3
DEFAULT_SPEED=1.2

DEFAULT_LANGUAGE=en-US

REQUIRE_API_KEY=True
```

#### 5. Run the Server

Once configured, start the server with:

```bash
python app/server.py
```

The server will start running at `http://localhost:5050`.

#### 6. Test the API


key: chroma:document
string_value:
The server will start running at `http://localhost:5050`.

#### 6. Test the API

You can now interact with the API at `http://localhost:5050/v1/audio/speech` and other available endpoints. See the [Usage](#usage) section for request examples.

#### Usage

##### Endpoint: `/v1/audio/speech`

Generates audio from the input text. Available parameters:

**Required Parameter:**

- **input** (string): The text to be converted to audio (up to 4096 characters).

**Optional Parameters:**

- **model** (string): Set to "tts-1" or "tts-1-hd" (default: `"tts-1"`).
- **voice** (string): One of the OpenAI-compatible voices (alloy, echo, fable, onyx, nova, shimmer) or any valid `edge-tts` voice (default: `"en-US-AndrewNeural"`).
- **response_format** (string): Audio format. Options: `mp3`, `opus`, `aac`, `flac`, `wav`, `pcm` (default: `mp3`).
- **speed** (number): Playback speed (0.25 to 4.0). Default is `1.2`.


key: chroma:document
string_value:
:::tip
You can browse available voices and listen to sample previews at [tts.travisvn.com](https://tts.travisvn.com)
:::

Example request with `curl` and saving the output to an mp3 file:

```bash
curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "input": "Hello, I am your AI assistant! Just let me know how I can help bring your ideas to life.",
    "voice": "echo",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3
```

Or, to be in line with the OpenAI API endpoint parameters:

```bash
curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "model": "tts-1",
    "input": "Hello, I am your AI assistant! Just let me know how I can help bring your ideas to life.",
    "voice": "alloy"
  }' \
  --output speech.mp3
```


key: chroma:document
string_value:
And an example of a language other than English:

```bash
curl -X POST http://localhost:5050/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
    "model": "tts-1",
    "input": "じゃあ、行く。電車の時間、調べておくよ。",
    "voice": "ja-JP-KeitaNeural"
  }' \
  --output speech.mp3
```

##### Additional Endpoints

- **POST/GET /v1/models**: Lists available TTS models.
- **POST/GET /v1/voices**: Lists `edge-tts` voices for a given language / locale.
- **POST/GET /v1/voices/all**: Lists all `edge-tts` voices, with language support information.

## 🐳 Quick Config for Docker

You can configure the environment variables in the command used to run the project

```bash
docker run -d -p 5050:5050 \
  -e API_KEY=your_api_key_here \
  -e PORT=5050 \
  -e DEFAULT_VOICE=en-US-AndrewNeural \
  -e DEFAULT_RESPONSE_FORMAT=mp3 \
  -e DEFAULT_SPEED=1.2 \
  -e DEFAULT_LANGUAGE=en-US \
  -e REQUIRE_API_KEY=True \
  travisvn/openai-edge-tts:latest
```


key: chroma:document
string_value:
## Additional Resources

For more information on `openai-edge-tts`, you can visit the [GitHub repo](https://github.com/travisvn/openai-edge-tts)

For direct support, you can visit the [Voice AI & TTS Discord](https://discord.gg/GkFbBCBqJ6)

## 🎙️ Voice Samples

[Play voice samples and see all available Edge TTS voices](https://tts.travisvn.com/)


key: chroma:document
string_value:
---
sidebar_position: 2
title: "🗨️ Openedai-speech Using Docker"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

**Integrating `openedai-speech` into Open WebUI using Docker**
==============================================================

**What is `openedai-speech`?**
-----------------------------

:::info
[openedai-speech](https://github.com/matatonic/openedai-speech) is an OpenAI audio/speech API compatible text-to-speech server.

It serves the `/v1/audio/speech` endpoint and provides a free, private text-to-speech experience with custom voice cloning capabilities. This service is in no way affiliated with OpenAI and does not require an OpenAI API key.
:::

**Requirements**
-----------------


key: chroma:document
string_value:
**Requirements**
-----------------

* Docker installed on your system
* Open WebUI running in a Docker container
* Basic understanding of Docker and Docker Compose

**Option 1: Using Docker Compose**
----------------------------------

**Step 1: Create a new folder for the `openedai-speech` service**
-----------------------------------------------------------------

Create a new folder, for example, `openedai-speech-service`, to store the `docker-compose.yml` and `speech.env` files.

**Step 2: Clone the `openedai-speech` repository from GitHub**
--------------------------------------------------------------

```bash
git clone https://github.com/matatonic/openedai-speech.git
```

This will download the `openedai-speech` repository to your local machine, which includes the Docker Compose files (`docker-compose.yml`, `docker-compose.min.yml`, and `docker-compose.rocm.yml`) and other necessary files.


key: chroma:document
string_value:
**Step 3: Rename the `sample.env` file to `speech.env` (Customize if needed)**
------------------------------------------------------------------------------

In the `openedai-speech` repository folder, create a new file named `speech.env` with the following contents:

```yaml
TTS_HOME=voices
HF_HOME=voices
#PRELOAD_MODEL=xtts
#PRELOAD_MODEL=xtts_v2.0.2
#PRELOAD_MODEL=parler-tts/parler_tts_mini_v0.1
#EXTRA_ARGS=--log-level DEBUG --unload-timer 300
#USE_ROCM=1
```

**Step 4: Choose a Docker Compose file**
----------------------------------------

You can use any of the following Docker Compose files:


key: chroma:document
string_value:
You can use any of the following Docker Compose files:

* [docker-compose.yml](https://github.com/matatonic/openedai-speech/blob/main/docker-compose.yml): This file uses the `ghcr.io/matatonic/openedai-speech` image and builds from [Dockerfile](https://github.com/matatonic/openedai-speech/blob/main/Dockerfile).
* [docker-compose.min.yml](https://github.com/matatonic/openedai-speech/blob/main/docker-compose.min.yml): This file uses the `ghcr.io/matatonic/openedai-speech-min` image and builds from [Dockerfile.min](https://github.com/matatonic/openedai-speech/blob/main/Dockerfile.min).
  This image is a minimal version that only includes Piper support and does not require a GPU.
* [docker-compose.rocm.yml](https://github.com/matatonic/openedai-speech/blob/main/docker-compose.rocm.yml): This file uses the `ghcr.io/matatonic/openedai-speech-rocm` image and builds from [Dockerfile](https://github.com/matatonic/openedai-speech/blob/main/Dockerfile) with ROCm support.


key: chroma:document
string_value:
**Step 4: Build the Chosen Docker Image**
-----------------------------------------

Before running the Docker Compose file, you need to build the Docker image:

* **Nvidia GPU (CUDA support)**:

```bash
docker build -t ghcr.io/matatonic/openedai-speech .
```

* **AMD GPU (ROCm support)**:

```bash
docker build -f Dockerfile --build-arg USE_ROCM=1 -t ghcr.io/matatonic/openedai-speech-rocm .
```

* **CPU only, No GPU (Piper only)**:

```bash
docker build -f Dockerfile.min -t ghcr.io/matatonic/openedai-speech-min .
```

**Step 5: Run the correct `docker compose up -d` command**
----------------------------------------------------------

* **Nvidia GPU (CUDA support)**: Run the following command to start the `openedai-speech` service in detached mode:

```bash
docker compose up -d
```

* **AMD GPU (ROCm support)**: Run the following command to start the `openedai-speech` service in detached mode:

```bash
docker compose -f docker-compose.rocm.yml up -d
```


key: chroma:document
string_value:
```bash
docker compose -f docker-compose.rocm.yml up -d
```

* **ARM64 (Apple M-series, Raspberry Pi)**: XTTS only has CPU support here and will be very slow. You can use the Nvidia image for XTTS with CPU (slow), or use the Piper only image (recommended):

```bash
docker compose -f docker-compose.min.yml up -d
```

* **CPU only, No GPU (Piper only)**: For a minimal docker image with only Piper support (< 1GB vs. 8GB):

```bash
docker compose -f docker-compose.min.yml up -d
```

This will start the `openedai-speech` service in detached mode.

**Option 2: Using Docker Run Commands**
---------------------------------------

You can also use the following Docker run commands to start the `openedai-speech` service in detached mode:

* **Nvidia GPU (CUDA)**: Run the following command to build and start the `openedai-speech` service:


key: chroma:document
string_value:
```bash
docker build -t ghcr.io/matatonic/openedai-speech .
docker run -d --gpus=all -p 8000:8000 -v voices:/app/voices -v config:/app/config --name openedai-speech ghcr.io/matatonic/openedai-speech
```

* **ROCm (AMD GPU)**: Run the following command to build and start the `openedai-speech` service:

> To enable ROCm support, uncomment the `#USE_ROCM=1` line in the `speech.env` file.

```bash
docker build -f Dockerfile --build-arg USE_ROCM=1 -t ghcr.io/matatonic/openedai-speech-rocm .
docker run -d --privileged --init --name openedai-speech -p 8000:8000 -v voices:/app/voices -v config:/app/config ghcr.io/matatonic/openedai-speech-rocm
```

* **CPU only, No GPU (Piper only)**: Run the following command to build and start the `openedai-speech` service:

```bash
docker build -f Dockerfile.min -t ghcr.io/matatonic/openedai-speech-min .
docker run -d -p 8000:8000 -v voices:/app/voices -v config:/app/config --name openedai-speech ghcr.io/matatonic/openedai-speech-min
```


key: chroma:document
string_value:
**Step 6: Configuring Open WebUI to use `openedai-speech` for TTS**
---------------------------------------------------------

![openedai-tts](https://github.com/silentoplayz/docs/assets/50341825/ea08494f-2ebf-41a2-bb0f-9b48dd3ace79)

Open the Open WebUI settings and navigate to the TTS Settings under **Admin Panel > Settings > Audio**. Add the following configuration:

* **API Base URL**: `http://host.docker.internal:8000/v1`
* **API Key**: `sk-111111111` (Note that this is a dummy API key, as `openedai-speech` doesn't require an API key. You can use whatever you'd like for this field, as long as it is filled.)

**Step 7: Choose a voice**
--------------------------

Under `TTS Voice` within the same audio settings menu in the admin panel, you can set the `TTS Model` to use from the following choices below that `openedai-speech` supports. The voices of these models are optimized for the English language.


key: chroma:document
string_value:
* `tts-1` or `tts-1-hd`: `alloy`, `echo`, `echo-alt`, `fable`, `onyx`, `nova`, and `shimmer` (`tts-1-hd` is configurable; uses OpenAI samples by default)

**Step 8: Press `Save` to apply the changes and start enjoying naturally sounding voices**
--------------------------------------------------------------------------------------------

Press the `Save` button to apply the changes to your Open WebUI settings. Refresh the page for the change to fully take effect and enjoy using `openedai-speech` integration within Open WebUI to read aloud text responses with text-to-speech in a natural sounding voice.

**Model Details:**
------------------

`openedai-speech` supports multiple text-to-speech models, each with its own strengths and requirements. The following models are available:


key: chroma:document
string_value:
* **Piper TTS** (very fast, runs on CPU): Use your own [Piper voices](https://rhasspy.github.io/piper-samples/) via the `voice_to_speaker.yaml` configuration file. This model is great for applications that require low latency and high performance. Piper TTS also supports [multilingual](https://github.com/matatonic/openedai-speech#multilingual) voices.
* **Coqui AI/TTS XTTS v2** (fast, but requires around 4GB GPU VRAM & Nvidia GPU with CUDA): This model uses Coqui AI's XTTS v2 voice cloning technology to generate high-quality voices. While it requires a more powerful GPU, it provides excellent performance and high-quality audio. Coqui also supports [multilingual](https://github.com/matatonic/openedai-speech#multilingual) voices.


key: chroma:document
string_value:
* **Beta Parler-TTS Support** (experimental, slower): This model uses the Parler-TTS framework to generate voices. While it's currently in beta, it allows you to describe very basic features of the speaker voice. The exact voice will be slightly different with each generation, but should be similar to the speaker description provided. For inspiration on how to describe voices, see [Text Description to Speech](https://www.text-description-to-speech.com/).


key: chroma:document
string_value:
**Troubleshooting**
-------------------

If you encounter any problems integrating `openedai-speech` with Open WebUI, follow these troubleshooting steps:


key: chroma:document
string_value:
* **Verify `openedai-speech` service**: Ensure that the `openedai-speech` service is running and the port you specified in the docker-compose.yml file is exposed.
* **Check access to host.docker.internal**: Verify that the hostname `host.docker.internal` is resolvable from within the Open WebUI container. This is necessary because `openedai-speech` is exposed via `localhost` on your PC, but `open-webui` cannot normally access it from inside its container. You can add a volume to the `docker-compose.yml` file to mount a file from the host to the container, for example, to a directory that will be served by openedai-speech.
* **Review API key configuration**: Make sure the API key is set to a dummy value or effectively left unchecked because `openedai-speech` doesn't require an API key.


key: chroma:document
string_value:
* **Check voice configuration**: Verify that the voice you are trying to use for TTS exists in your `voice_to_speaker.yaml` file and the corresponding files (e.g., voice XML files) are present in the correct directory.
* **Verify voice model paths**: If you're experiencing issues with voice model loading, double-check that the paths in your `voice_to_speaker.yaml` file match the actual locations of your voice models.


key: chroma:document
string_value:
**Additional Troubleshooting Tips**
------------------------------------

* Check the openedai-speech logs for errors or warnings that might indicate where the issue lies.
* Verify that the `docker-compose.yml` file is correctly configured for your environment.
* If you're still experiencing issues, try restarting the `openedai-speech` service or the entire Docker environment.
* If the problem persists, consult the `openedai-speech` GitHub repository or seek help on a relevant community forum.

**FAQ**
-------

**How can I control the emotional range of the generated audio?**

There is no direct mechanism to control the emotional output of the generated audio. Certain factors such as capitalization or grammar may affect the output audio, but internal testing has yielded mixed results.

**Where are the voice files stored? What about the configuration file?**.


key: chroma:document
string_value:
**Where are the voice files stored? What about the configuration file?**.

The configuration files, which define the available voices and their properties, are stored in the config volume. Specifically, the default voices are defined in voice_to_speaker.default.yaml.

**Additional Resources**
------------------------

For more information on configuring Open WebUI to use `openedai-speech`, including setting environment variables, see the [Open WebUI documentation](https://docs.openwebui.com/getting-started/advanced-topics/env-configuration#text-to-speech).

For more information about `openedai-speech`, please visit the [GitHub repository](https://github.com/matatonic/openedai-speech).

**How to add more voices to openedai-speech:**
[Custom-Voices-HowTo](https://github.com/matatonic/openedai-speech?tab=readme-ov-file#custom-voices-howto)


key: chroma:document
string_value:
:::note
You can change the port number in the `docker-compose.yml` file to any open and usable port, but be sure to update the **API Base URL** in Open WebUI Admin Audio settings accordingly.
:::


key: chroma:document
string_value:
---
sidebar_position: 1
title: "🔑 Reset Admin Password"
---

# Resetting Your Admin Password 🗝️

If you've forgotten your admin password, don't worry! Below you'll find step-by-step guides to reset your admin password for Docker 🐳 deployments and local installations of Open WebUI.

## For Docker Deployments 🐳

Follow these steps to reset the admin password for Open WebUI when deployed using Docker.

### Step 1: Generate a New Password Hash 🔐

First, you need to create a bcrypt hash of your new password. Run the following command on your local machine, replacing `your-new-password` with the password you wish to use:

```bash
htpasswd -bnBC 10 "" your-new-password | tr -d ':\n'
```

**Note:** The output will include a bcrypt hash with special characters that need to be handled carefully. Any `$` characters in the hash will need to be triple-escaped (replaced with `\\\`) to be used correctly in the next step.

### Step 2: Update the Password in Docker 🔄


key: chroma:document
string_value:
### Step 2: Update the Password in Docker 🔄

Next, you'll update the password in your Docker deployment. Replace `HASH` in the command below with the bcrypt hash generated in Step 1, making sure to triple-escape any `$` characters. Also, replace `admin@example.com` with the email address linked to your admin account.

**Important:** The following command may not work in all cases. If it doesn't work for you, try the alternative command below it.

```bash
docker run --rm -v open-webui:/data alpine/socat EXEC:"bash -c 'apk add sqlite && echo UPDATE auth SET password='\''HASH'\'' WHERE email='\''admin@example.com'\''; | sqlite3 /data/webui.db'", STDIO
```

## For Local Installations 💻

If you have a local installation of Open WebUI, here's how you can reset your admin password directly on your system.

### Step 1: Generate a New Password Hash 🔐


key: chroma:document
string_value:
### Step 1: Generate a New Password Hash 🔐

Just as with the Docker method, start by generating a bcrypt hash of your new password using the following command. Remember to replace `your-new-password` with your new password:

```bash
htpasswd -bnBC 10 "" your-new-password | tr -d ':\n'
```

### Step 2: Update the Password Locally 🔄

Now, navigate to the `open-webui` directory on your local machine. Update your password by replacing `HASH` with the bcrypt hash from Step 1 and `admin@example.com` with your admin account email, and execute:

```bash
sqlite3 backend/data/webui.db "UPDATE auth SET password='HASH' WHERE email='admin@example.com';"
```

---

📖 By following these straightforward steps, you'll regain access to your Open WebUI admin account in no time. If you encounter any issues during the process, please consider searching for your issue on forums or community platforms.
```


key: chroma:document
string_value:
---
sidebar_position: 2
title: "🔧 Pipes"
---

# Pipes
Pipes are functions that can be used to perform actions prior to returning LLM messages to the user. Examples of potential actions you can take with Pipes are Retrieval Augmented Generation (RAG), sending requests to non-OpenAI LLM providers (such as Anthropic, Azure OpenAI, or Google), or executing functions right in your web UI. Pipes can be hosted as a Function or on a Pipelines server. A list of examples is maintained in the [Pipelines repo](https://github.com/open-webui/pipelines/tree/main/examples/pipelines). The general workflow can be seen in the image below.

<p align="center">
  <a href="#">
    <img src="/img/pipelines/pipes.png" alt="Pipe Workflow" />
  </a>
</p>

Pipes that are defined in your WebUI show up as a new model with an "External" designation attached to them. An example of two Pipe models, `Database RAG Pipeline` and `DOOM`, can be seen below next to two self-hosted models:


key: chroma:document
string_value:
<p align="center">
  <a href="#">
    <img src="/img/pipelines/pipe-model-example.png" alt="Pipe Models in WebUI" />
  </a>
</p>


key: chroma:document
string_value:
# Using Podman

Podman is a daemonless container engine for developing, managing, and running OCI Containers.

## Basic Commands

- **Run a Container:**

  ```bash
  podman run -d --name openwebui -p 3000:8080 ghcr.io/open-webui/open-webui:main
  ```

- **List Running Containers:**

  ```bash
  podman ps
  ```

## Networking with Podman

If networking issues arise, you may need to adjust your network settings:

```bash
--network=slirp4netns:allow_host_loopback=true
```

Refer to the Podman [documentation](https://podman.io/) for advanced configurations.


key: chroma:document
string_value:
---
sidebar_position: 18
title: "📱 Progressive Web App"
---

COMING SOON!

📱 Progressive Web App for Mobile: Enjoy a native progressive web application experience on your mobile device with offline access on localhost or a personal domain, and a smooth user interface. In order for our PWA to be installable on your device, it must be delivered in a secure context. This usually means that it must be served over HTTPS.

    To set up a PWA, you'll need some understanding of technologies like Linux, Docker, and reverse proxies such as Nginx, Caddy, or Traefik. Using these tools can help streamline the process of building and deploying a PWA tailored to your needs. While there's no "one-click install" option available, and your available option to securely deploy your Open WebUI instance over HTTPS requires user experience, using these resources can make it easier to create and deploy a PWA tailored to your needs.


key: chroma:document
string_value:
---
sidebar_position: 2
title: "🐍 Python Code Execution"
---

# 🐍 Python Code Execution

## Overview

Open WebUI allows for the client-side execution of Python code in the browser, utilizing Pyodide to run scripts within a code block in a chat. This feature enables Large Language Models (LLMs) to generate Python scripts that can be executed directly in the browser, leveraging a range of libraries supported by Pyodide.

To maintain user privacy and flexibility, Open WebUI mirrors PyPI packages, avoiding direct external network requests. This approach also enables the use of Pyodide in environments without internet access.

The Open WebUI frontend includes a self-contained WASM (WebAssembly) Python environment, powered by Pyodide, which can execute basic Python scripts generated by LLMs. This environment is designed for ease of use, requiring no additional setup or installation.

## Supported Libraries


key: chroma:document
string_value:
## Supported Libraries

Pyodide code execution is configured to load only packages configured in scripts/prepare-pyodide.js and then added to "CodeBlock.svelte". The following Pyodide packages are currently supported in Open WebUI:

* micropip
* packaging
* requests
* beautifulsoup4
* numpy
* pandas
* matplotlib
* scikit-learn
* scipy
* regex

These libraries can be used to perform various tasks, such as data manipulation, machine learning, and web scraping. If the package you're wanting to run is not compiled inside of the Pyodide we ship with Open WebUIm, the package will not be able to be used.

## Invoking Python Code Execution


key: chroma:document
string_value:
## Invoking Python Code Execution

To execute Python code, ask an LLM within a chat to write a Python script for you. Once the LLM has generated the code, a `Run` button will appear at the top right-hand side of the code block. Clicking this button will execute the code using Pyodide. To display the result at the bottom of a code block, ensure there is at least a single print statement within the code to display a result.

## Tips for Using Python Code Execution

* When writing Python code, keep in mind that the code would be running in a Pyodide environment when executed. You can inform the LLM of this by mentioning "Pyodide environment" when asking for code.
* Research the Pyodide documentation to understand the capabilities and limitations of the environment.
* Experiment with different libraries and scripts to explore the possibilities of Python code execution in Open WebUI.

## Pyodide Documentation

* [Pyodide Documentation](https://pyodide.org/en/stable/)

## Code Example


key: chroma:document
string_value:
* [Pyodide Documentation](https://pyodide.org/en/stable/)

## Code Example

Here is an example of a simple Python script that can be executed using Pyodide:

```python
import pandas as pd

# Create a sample DataFrame
data = {'Name': ['John', 'Anna', 'Peter'], 
        'Age': [28, 24, 35]}
df = pd.DataFrame(data)

# Print the DataFrame
print(df)
```

This script will create a sample DataFrame using pandas and print it below the code block within your chat.

## Extending the List of Supported Libraries

Want to push the boundaries of what's possible? To extend the list of supported libraries, follow these steps:

1. **Fork the Pyodide repository** to create your own version.
2. **Choose new packages** from the existing list of packages within Pyodide or explore high-quality packages that Open WebUI currently lacks.
3. **Integrate the new packages** into your forked repository to unlock even more possibilities.


key: chroma:document
string_value:
# Updating with Python

To update your locally installed **Open-WebUI** package to the latest version using `pip`, follow these simple steps:

```bash
pip install -U open-webui
```

The `-U` (or `--upgrade`) flag ensures that `pip` upgrades the package to the latest available version.

That's it! Your **Open-WebUI** package is now updated and ready to use.


key: chroma:document
string_value:
---
sidebar_position: 11
title: "🔎 Retrieval Augmented Generation (RAG)"
---

Retrieval Augmented Generation (RAG) is a cutting-edge technology that enhances the conversational capabilities of chatbots by incorporating context from diverse sources. It works by retrieving relevant information from a wide range of sources such as local and remote documents, web content, and even multimedia sources like YouTube videos. The retrieved text is then combined with a predefined RAG template and prefixed to the user's prompt, providing a more informed and contextually relevant response.


key: chroma:document
string_value:
One of the key advantages of RAG is its ability to access and integrate information from a variety of sources, making it an ideal solution for complex conversational scenarios. For instance, when a user asks a question related to a specific document or web page, RAG can retrieve and incorporate the relevant information from that source into the chat response. RAG can also retrieve and incorporate information from multimedia sources like YouTube videos. By analyzing the transcripts or captions of these videos, RAG can extract relevant information and incorporate it into the chat response.

## Local and Remote RAG Integration

Local documents must first be uploaded via the Documents section of the Workspace area to access them using the `#` symbol before a query. Click on the formatted URL in the that appears above the chat box. Once selected, a document icon appears above `Send a message`, indicating successful retrieval.


key: chroma:document
string_value:
You can also load documents into the workspace area with their access by starting a prompt with `#`, followed by a URL. This can help incorporate web content directly into your conversations.

## Web Search for RAG

For web content integration, start a query in a chat with `#`, followed by the target URL. Click on the formatted URL in the box that appears above the chat box. Once selected, a document icon appears above `Send a message`, indicating successful retrieval. Open WebUI fetches and parses information from the URL if it can.

:::tip
Web pages often contain extraneous information such as navigation and footer. For better results, link to a raw or reader-friendly version of the page.
:::

## RAG Template Customization

Customize the RAG template from the `Admin Panel` > `Settings` > `Documents` menu.

## RAG Embedding Support


key: chroma:document
string_value:
## RAG Embedding Support

Change the RAG embedding model directly in the `Admin Panel` > `Settings` > `Documents` menu. This feature supports Ollama and OpenAI models, enabling you to enhance document processing according to your requirements.

## Citations in RAG Feature

The RAG feature allows users to easily track the context of documents fed to LLMs with added citations for reference points. This ensures transparency and accountability in the use of external sources within your chats.

## Enhanced RAG Pipeline

The togglable hybrid search sub-feature for our RAG embedding feature enhances RAG functionality via `BM25`, with re-ranking powered by `CrossEncoder`, and configurable relevance score thresholds. This provides a more precise and tailored RAG experience for your specific use case.

## YouTube RAG Pipeline


key: chroma:document
string_value:
## YouTube RAG Pipeline

The dedicated RAG pipeline for summarizing YouTube videos via video URLs enables smooth interaction with video transcriptions directly. This innovative feature allows you to incorporate video content into your chats, further enriching your conversation experience.

## Document Parsing

A variety of parsers extract content from local and remote documents. For more, see the [`get_loader`](https://github.com/open-webui/open-webui/blob/2fa94956f4e500bf5c42263124c758d8613ee05e/backend/apps/rag/main.py#L328) function.


key: chroma:document
string_value:
---
sidebar_position: 3
title: "🔎 Open WebUI RAG Tutorial"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# Tutorial: Configuring RAG with OpenWebUI Documentation

In this tutorial, you will learn how to use **Retrieval-Augmented Generation (RAG)** with OpenWebUI to load real-world documentation as a knowledge base. We will walk through how to use the latest **OpenWebUI Documentation** as an example for this setup.

---

## Overview

### What is RAG?

Retrieval-Augmented Generation (RAG) combines **LLMs** with **retrieved knowledge** from external sources. The system retrieves relevant data from uploaded documents or knowledge bases, enhancing the quality and accuracy of responses.

This tutorial demonstrates how to:


key: chroma:document
string_value:
This tutorial demonstrates how to:

- Upload the latest OpenWebUI Documentation as a knowledge base.
- Connect it to a custom model.
- Query the knowledge base for enhanced assistance.

---

## Setup

### Step-by-Step Setup: OpenWebUI Documentation as Knowledge Base

Follow these steps to set up RAG with **OpenWebUI Documentation**:

1. **Download the Documentation**:
   - Download the latest documentation:
     [https://github.com/open-webui/docs/archive/refs/heads/main.zip](https://github.com/open-webui/docs/archive/refs/heads/main.zip)

2. **Extract the Files**:
   - Extract the `main.zip` file to get all documentation files.

3. **Locate the Markdown Files**:
   - In the extracted folder, locate all files with `.md` and `.mdx`extensions (tip: search for `*.md*`).

4. **Create a Knowledge Base**:
   - Navigate to **Workspace** > **Knowledge** > **+ Create a Knowledge Base**.
   - Name it: `OpenWebUI Documentation`
   - Purpose: **Assistance**

   > Click **Create Knowledge**.


key: chroma:document
string_value:
> Click **Create Knowledge**.

5. **Upload the Files**:
   - Drag and drop the `.md` and `.mdx` files from the extracted folder into the **OpenWebUI Documentation** knowledge base.

---

## Create and Configure the Model

### Create a Custom Model with the Knowledge Base

1. **Navigate to Models**:
   - Go to **Workspace** > **Models** > **+ Add New Model**.

2. **Configure the Model**:
   - **Name**: `OpenWebUI`
   - **Base Model**: *(Select the appropriate Llama or other available model)*
   - **Knowledge Source**: Select **OpenWebUI Documentation** from the dropdown.

3. **Save the Model**.

---

## Examples and Usage

### Query the OpenWebUI Documentation Model

1. **Start a New Chat**:
   - Navigate to **New Chat** and select the `OpenWebUI` model.

2. **Example Queries**:

   ```
   User: "How do I configure environment variables?"
   System: "Refer to Section 3.2: Use the `.env` file to manage configurations."
   ```


key: chroma:document
string_value:
```
   User: "How do I update OpenWebUI using Docker?"
   System: "Refer to `docker/updating.md`: Use `docker pull` and restart the container."
   ```

   With the RAG-enabled model, the system retrieves the most relevant sections from the documentation to answer your query.

---

## Next Steps

### Next Steps

- **Add More Knowledge**: Continue expanding your knowledge base by adding more documents.

---

With this setup, you can effectively use the **OpenWebUI Documentation** to assist users by retrieving relevant information for their queries. Enjoy building and querying your custom knowledge-enhanced models!


key: chroma:document
string_value:
# Website

This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

## Installation

```sh
npm ci
```

## Local Development

```sh
npm start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

## Build

```sh
npm run build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

## Deployment

Using SSH:

```sh
USE_SSH=true npm run deploy
```

Not using SSH:

```sh
GIT_USER=<Your GitHub username> npm run deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.


key: chroma:document
string_value:
---
sidebar_position: 30
title: "🔗 Redis Websocket Support"
---

:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::

# 🔗 Redis Websocket Support

## Overview

This documentation page outlines the steps required to integrate Redis with Open WebUI for websocket support. By following these steps, you will be able to enable websocket functionality in your Open WebUI instance, allowing for real-time communication and updates between clients and your application.

### Prerequisites

* A valid Open WebUI instance (running version 1.0 or higher)
* A Redis container (we will use `docker.io/valkey/valkey:8.0.1-alpine` in this example, which is based on the latest Redis 7.x release)
* Docker Composer (version 2.0 or higher) installed on your system

## Setting up Redis


key: chroma:document
string_value:
## Setting up Redis

To set up Redis for websocket support, you will need to create a `docker-compose.yml` file with the following contents:

```yml
version: '3.9'
services:
  redis:
    image: docker.io/valkey/valkey:8.0.1-alpine
    container_name: redis-valkey
    volumes:
      - redis-data:/data
    command: "valkey-server --save 30 1"
    healthcheck:
      test: "[ $$(valkey-cli ping) = 'PONG' ]"
      start_period: 5s
      interval: 1s
      timeout: 3s
      retries: 5
    restart: unless-stopped
    cap_drop:
      - ALL
    cap_add:
      - SETGID
      - SETUID
      - DAC_OVERRIDE
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"

volumes:
  redis-data:
```

This configuration sets up a Redis container named `redis-valkey` and mounts a volume for data persistence. The `healthcheck` directive ensures that the container is restarted if it fails to respond to the `ping` command.

## Configuring Open WebUI


key: chroma:document
string_value:
## Configuring Open WebUI

To enable websocket support in Open WebUI, you will need to set the following environment variables for your Open WebUI instance:

```bash
ENABLE_WEBSOCKET_SUPPORT="true"
WEBSOCKET_MANAGER="redis"
WEBSOCKET_REDIS_URL="redis://redis:6379/1"
```

These environment variables enable websocket support, specify Redis as the websocket manager, and define the Redis URL. Make sure to replace the `WEBSOCKET_REDIS_URL` value with the actual URL of your Redis instance.

## Verification

If you have properly set up Redis and configured Open WebUI, you should see the following log message when starting your Open WebUI instance:

`DEBUG:open_webui.socket.main:Using Redis to manage websockets.`

This confirms that Open WebUI is using Redis for websocket management. You can also use the `docker exec` command using Command Prompt to verify that the Redis instance is running and accepting connections:

```bash
docker exec -it redis-valkey redis-cli -p 6379 ping
```


key: chroma:document
string_value:
```bash
docker exec -it redis-valkey redis-cli -p 6379 ping
```

This command should output `PONG` if the Redis instance is running correctly. If this command fails, you could try this command instead:

```bash
docker exec -it redis-valkey valkey-cli -p 6379 ping
```

## Troubleshooting

If you encounter issues with Redis or websocket support in Open WebUI, you can refer to the following resources for troubleshooting:

* [Redis Documentation](https://redis.io/docs)
* [Open WebUI Documentation](https://open-webui.github.io/docs)
* [Docker Composer Documentation](https://docs.docker.com/compose/overview/)

By following these steps and troubleshooting tips, you should be able to set up Redis with Open WebUI for websocket support and enable real-time communication and updates between clients and your application.


key: chroma:document
string_value:
---
sidebar_position: 10
title: "✂️ Reduce RAM Usage"
---

# Reduce RAM Usage

If you are deploying this image in a RAM-constrained environment, there are a few things you can do to slim down the image.

On a Raspberry Pi 4 (arm64) with version v0.3.10, this was able to reduce idle memory consumption from >1GB to ~200MB (as observed with `docker container stats`).

## TLDR

Set the following environment variables (or the respective UI settings for an existing deployment): `RAG_EMBEDDING_ENGINE: ollama`, `AUDIO_STT_ENGINE: openai`.

## Longer explanation

Much of the memory consumption is due to loaded ML models. Even if you are using an external language model (OpenAI or unbundled ollama), many models may be loaded for additional purposes.

As of v0.3.10 this includes:

* Speech-to-text (whisper by default)
* RAG embedding engine (defaults to local SentenceTransformers model)
* Image generation engine (disabled by default)


key: chroma:document
string_value:
The first 2 are enabled and set to local models by default. You can change the models in the admin panel (RAG: Documents category, set it to Ollama or OpenAI, Speech-to-text: Audio section, work with OpenAI or WebAPI).
If you are deploying a fresh Docker image, you can also set them with the following environment variables: `RAG_EMBEDDING_ENGINE: ollama`, `AUDIO_STT_ENGINE: openai`. Note that these environment variables have no effect if a `config.json` already exists.


key: chroma:document
string_value:
---
sidebar_position: 1400
title: "🛣️ Roadmap"
---

import { TopBanners } from "@site/src/components/TopBanners";

<TopBanners />

# Open WebUI Roadmap! 🌟

At Open WebUI, we're committed to continually enhancing our platform to provide the best experience for our users. Below, you'll find the structured roadmap for our ongoing and future developments, categorized into Interface, Information Retrieval, and Community.

## Interface 🖥️

Our roadmap for interface innovations aims to create a highly intuitive and accessible platform. These will not only improves user satisfaction but also enhance productivity by reducing the cognitive load on users.


key: chroma:document
string_value:
- 🔧 **Streamlined Fine-tune Support**: Open WebUI will offer a seamless fine-tuning process by allowing users to automatically build a fine-tune dataset simply by using the interface and rating the responses. We will provide Python notebooks to help preprocess your dataset, making it ready for fine-tuning directly from the notebook. This approach will be super simple and elegantly integrates fine-tuning into user workflows.

- 📈 **Advanced User Tracking and Cost Management Tools**: Users will gain access to comprehensive tools designed for tracking application performance and user activities, as well as managing costs effectively. These tools will empower users with the data they need to make informed decisions, improve user experiences, and maintain budget control, optimizing the use of resources across their AI applications.


key: chroma:document
string_value:
- 💬 **"Channels" Feature**: Channels will function like Discord/Slack chat rooms, facilitating real-time collaboration among users and AIs. These dedicated communication spaces can host human-to-human interactions or AI-assisted discussions, fostering dynamic and context-driven collaboration. As we transition towards multi-agent and proactive agent workflows, true asynchronous communication will be essential, and Open WebUI will provide a Bot SDK tutorial to empower users in building proactive AI agents that can initiate conversations and integrate seamlessly into the platform.

- 👤 **User Page**: A personal User Page feature where users can create posts. The functionality will also include features like followers, likes, and comments. This allows users to effectively share their model configurations, prompts, and files with a broader community, creating a richer, more connected ecosystem around the platform.


key: chroma:document
string_value:
- 📝 **AI Powered Notes**: Inspired by tools like Notion and Obsidian, we plan to introduce a robust note-taking feature that includes AI integration. From simple note-taking to full-fledged document creation, this tool will offer a seamless experience, all locally integrated within the platform.

- 🧠 **AI Workflow Tool**: A node-based tool to orchestrate and compose multiple aspects of AI systems. This tool will allow users to visually connect different AI modules and services, creating complex workflows with ease. It's designed to empower users to harness the full potential of AI without needing deep technical knowledge in AI programming.


key: chroma:document
string_value:
- 🔊 **Local Text-to-Speech Integration**: This feature will allow natural language processing to convert text into lifelike spoken audio, thus making the platform more accessible, especially for visually impaired users. This integration helps in consuming information without screen interaction, facilitating multitasking and improving user engagement.

- 📣 **Wakeword Detection**: Incorporating hands-free operation through voice commands will not only enhance accessibility but also align with emerging trends in IoT and smart environments, making our platform future-ready.

- 💻 **Better Code Execution**: Enhancing coding functionalities within the platform supports a broad range of development activities, making it a one-stop solution for developers, thereby attracting a wider tech audience and fostering a robust developer community.


key: chroma:document
string_value:
- 🤖 **Code Interpreter Function**: A flexible code interpreter embedded into the platform can support multiple programming languages, which reduces the dependency on external tools and streamlines the development process, increasing efficiency.

- 📦 **Packaged Single Binary Executable**: Simplifying deployment and ensuring compatibility across different platforms, we aim to offer our interface as a single binary executable. This approach will facilitate effortless installation and updates, significantly enhancing usability for all users, especially those with limited technical expertise.

## Information Retrieval (RAG) 📚


key: chroma:document
string_value:
## Information Retrieval (RAG) 📚

Open WebUI currently provides an interface that enables the use of existing information retrieval (IR) models efficiency. However, we believe there is vast potential for improvement. We fully recognize the limitations of our current RAG (Retrieval-Augmented Generation) implementation in our WebUI, understanding that a one-size-fits-all approach does not effectively meet all users' needs. 

To address this, we are committed to transforming our framework to be highly modular and extensively configurable. This new direction will enable users to tailor the information retrieval process to their specific requirements with ease, using a straightforward, interactive interface that allows for simple drag-and-drop customization. This refinement aims to significantly enhance user experience by providing a more adaptable and personalized IR setup.

Here's our focused plan for advancing our information retrieval capabilities:


key: chroma:document
string_value:
Here's our focused plan for advancing our information retrieval capabilities:

- 🌐 **Customizable RAG Framework**: Envision a future where you can effortlessly tailor your IR setup via a user-friendly interface. This will include modular components that users can drag, drop, and configure without needing deep technical knowledge.

- 🔄 **Advanced Integration with SoTA Methods**: We aim to incorporate the latest developments in retrieval methods, enhancing accuracy and efficiency with advanced techniques and architectures.

- 🔍 **Dedicated R&D**: We're scaling up our research and development to discover and integrate novel retrieval methods that push the boundaries of current methods, in collaboration with leading research entities.

## Community 🤝

We aim to create a vibrant community where everyone can contribute to and benefit from shared knowledge and developments:


key: chroma:document
string_value:
- 🏆 **LLM Leaderboard**: A community-driven approach to evaluate and rank models ensures transparency and continuous improvement, leveraging real-world applications to benchmark performance instead of relying on standard datasets that might not reflect practical utility.

- 👥 **Sub-Communities**: Encouraging niche communities to curate datasets and optimize prompts can lead to better-tuned models, as these communities have specific insights and detailed feedback that typically go unnoticed in broader datasets.

🔗 **Community Whitepaper**: Explore our detailed strategy and join us in shaping the future of AI-driven platforms in our [whitepaper](https://openwebui.com/assets/files/whitepaper.pdf).


# Vision for the Future 🔭

Our relentless effort stems from a clear vision we hold dearly: enhancing your daily life, saving time and allowing for more focus on what truly matters.


key: chroma:document
string_value:
Imagine a world where you think, and it happens. You desire a cup of coffee made exactly the way you love, and it's brewed for you. A world where you, simply think of a comprehensive data analysis report in a particular format, and it's done at the speed of your thought. The core idea is to turn the time-consuming, routine tasks over to our AI interface, freeing up your time and attention.

This isn't a sci-fi future; together, we are working towards it right now. As our AI models gradually become more capable and intuitively understand your specific needs, your most mundane responsibilities become automated. Through this profound shift, our collective time allowance can be redistributed towards grand endeavours. Think space exploration, longevity research or simply extra moments with loved ones.


key: chroma:document
string_value:
Creating this imagined future won't be a walk in the park, but with your help, we believe it's within our reach. Open WebUI is more than just tech - it's there to enhance your day, giving you more space for what's really important. Together, we're working on a brighter tomorrow. Thanks for joining us in this extraordinary journey.

---

Join us as we push the boundaries of technology with these ambitious and transformative features in our roadmap! 💡🚀 Your participation and feedback are crucial as we strive to make Open WebUI a pioneering tool in technology advancement.


key: chroma:document
string_value:
### Self-Signed Certificate


Using self-signed certificates is suitable for development or internal use where trust is not a critical concern.

#### Steps

1. **Create Directories for Nginx Files:**

    ```bash
    mkdir -p conf.d ssl
    ```

2. **Create Nginx Configuration File:**

    **`conf.d/open-webui.conf`:**

    ```nginx
    server {
        listen 443 ssl;
        server_name your_domain_or_IP;

        ssl_certificate /etc/nginx/ssl/nginx.crt;
        ssl_certificate_key /etc/nginx/ssl/nginx.key;
        ssl_protocols TLSv1.2 TLSv1.3;

        location / {
            proxy_pass http://host.docker.internal:3000;
            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;


key: chroma:document
string_value:
# (Optional) Disable proxy buffering for better streaming response from models
            proxy_buffering off;
        }
    }
    ```

3. **Generate Self-Signed SSL Certificates:**

    ```bash
    openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout ssl/nginx.key \
    -out ssl/nginx.crt \
    -subj "/CN=your_domain_or_IP"
    ```

4. **Update Docker Compose Configuration:**

    Add the Nginx service to your `docker-compose.yml`:

    ```yaml
    services:
      nginx:
        image: nginx:alpine
        ports:
          - "443:443"
        volumes:
          - ./conf.d:/etc/nginx/conf.d
          - ./ssl:/etc/nginx/ssl
        depends_on:
          - open-webui
    ```

5. **Start Nginx Service:**

    ```bash
    docker compose up -d nginx
    ```

#### Access the WebUI

Access Open WebUI via HTTPS at:

[https://your_domain_or_IP](https://your_domain_or_IP)

---


key: chroma:document
string_value:
---
sidebar_position: 1800
title: "🌐 Sponsorships"
---

[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/tjbck)

## The Impact of Your Support

As Open WebUI grows, the tasks and challenges we face expand as well. [Tim](/team) is at the heart of this project, tirelessly working to ensure all aspects of Open WebUI not only function but thrive. Yet, imagine the additional improvements we could make with a little extra support.

Consider the practical benefits your organization gains from Open WebUI. A modest contribution from users like you allows us to focus more on refining features and less on managing resources. Each helping hand makes a meaningful difference, aligning our daily realities with our ambitious goals.


key: chroma:document
string_value:
We're incredibly thankful to our current sponsors. Your commitment has brought us closer to realizing the full potential of Open WebUI. Every contribution, big or small, strengthens the project and lays the groundwork for its continued success.

Thank you for considering joining us in this practical yet visionary endeavor. Here, every bit of support is not only appreciated—it's crucial for keeping our project vibrant, dynamic, and responsive to users' needs.

## Sponsorship Policies

At Open WebUI, our community always comes first. Sponsors are welcome, but they must respect our community-first approach. This philosophy guides all our sponsorship policies.

### Hard Rules

These are the non-negotiable rules for sponsors:

- Sponsors will always be clearly identified as sponsors.
- Aggressive sales tactics directed at our community members are strictly prohibited.
- We don't sell personal information about our community members to sponsors (e.g., to add to their mailing list).


key: chroma:document
string_value:
### Soft Rules

Our community members should not be treated as sales leads.

We expect sponsors to be exemplary community members. It's acceptable to subtly promote job openings at your company and showcase your product, but hard selling is not allowed. Additionally, do not ask community members to join your mailing list.


key: chroma:document
string_value:
---
sidebar_position: 19
title: "🔒 SSO: Federated Authentication Support"
---

# Federated Authentication Support

Open WebUI supports several forms of federated authentication:

1. OAuth2
    1. Google
    1. Microsoft
    1. OIDC
1. Trusted Header

## OAuth

There are several global configuration options for OAuth:

1. `ENABLE_OAUTH_SIGNUP` - if `true`, allows accounts to be created when logging in with OAuth. Distinct from `ENABLE_SIGNUP`.
1. `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` - allows logging into an account that matches the email address provided by the OAuth provider.
    - This is considered insecure as not all OAuth providers verify email addresses, and may allow accounts to be hijacked.

### Google

To configure a Google OAuth client, please refer to [Google's documentation](https://support.google.com/cloud/answer/6158849) on how to create a Google OAuth client for a **web application**.
The allowed redirect URI should include `<open-webui>/oauth/google/callback`.


key: chroma:document
string_value:
The following environment variables are required:

1. `GOOGLE_CLIENT_ID` - Google OAuth client ID
1. `GOOGLE_CLIENT_SECRET` - Google OAuth client secret

### Microsoft

To configure a Microsoft OAuth client, please refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) on how to create a Microsoft OAuth client for a **web application**.
The allowed redirect URI should include `<open-webui>/oauth/microsoft/callback`.

Support for Microsoft OAuth is currently limited to a single tenant, that is a single Entra organization or personal Microsoft accounts.

The following environment variables are required:

1. `MICROSOFT_CLIENT_ID` - Microsoft OAuth client ID
1. `MICROSOFT_CLIENT_SECRET` - Microsoft OAuth client secret
1. `MICROSOFT_CLIENT_TENANT_ID` - Microsoft tenant ID - use `9188040d-6c67-4c5b-b112-36a304b66dad` for personal accounts

### OIDC


key: chroma:document
string_value:
### OIDC

Any authentication provider that supports OIDC can be configured.
The `email` claim is required.
`name` and `picture` claims are used if available.
The allowed redirect URI should include `<open-webui>/oauth/oidc/callback`.

The following environment variables are used:

1. `OAUTH_CLIENT_ID` - OIDC client ID
1. `OAUTH_CLIENT_SECRET` - OIDC client secret
1. `OPENID_PROVIDER_URL` - OIDC well known URL, for example `https://accounts.google.com/.well-known/openid-configuration`
1. `OAUTH_PROVIDER_NAME` - Name of the provider to show on the UI, defaults to SSO
1. `OAUTH_SCOPES` - Scopes to request. Defaults to `openid email profile`

### OAuth Role Management

Any OAuth provider that can be configured to return roles in the access token can be used to manage roles in Open WebUI.
To use this feature set `ENABLE_OAUTH_ROLE_MANAGEMENT` to `true`.
You can configure the following environment variables to match the roles returned by the OAuth provider:


key: chroma:document
string_value:
1. `OAUTH_ROLES_CLAIM` - The claim that contains the roles. Defaults to `roles`. Can also be nested, for example `user.roles`.
1. `OAUTH_ALLOWED_ROLES` - A comma-separated list of roles that are allowed to log in (receive open webui role `user`).
1. `OAUTH_ADMIN_ROLES` - A comma-separated list of roles that are allowed to log in as an admin (receive open webui role `admin`).

:::info

If changing the role of a logged in user, they will need to log out and log back in to receive the new role.

:::

## Trusted Header

Open WebUI is able to delegate authentication to an authenticating reverse proxy that passes in the user's details in HTTP headers.
There are several example configurations that are provided in this page.

:::danger

Incorrect configuration can allow users to authenticate as any user on your Open WebUI instance.
Make sure to allow only the authenticating proxy access to Open WebUI, such as setting `HOST=127.0.0.1` to only listen on the loopback interface.

:::


key: chroma:document
string_value:
:::

### Generic Configuration

When the `WEBUI_AUTH_TRUSTED_EMAIL_HEADER` environment variable is set, Open WebUI will use the value of the header specified as the email address of the user, handling automatic registration and login.

For example, setting `WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email` and passing a HTTP header of `X-User-Email: example@example.com` would authenticate the request with the email `example@example.com`.

Optionally, you can also define the `WEBUI_AUTH_TRUSTED_NAME_HEADER` to determine the name of any user being created using trusted headers. This has no effect if the user already exists.

### Tailscale Serve

[Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) allows you to share a service within your tailnet, and Tailscale will set the header `Tailscale-User-Login` with the email address of the requester.


key: chroma:document
string_value:
Below is an example serve config with a corresponding Docker Compose file that starts a Tailscale sidecar, exposing Open WebUI to the tailnet with the tag `open-webui` and hostname `open-webui`, and can be reachable at `https://open-webui.TAILNET_NAME.ts.net`.
You will need to create an OAuth client with device write permission to pass into the Tailscale container as `TS_AUTHKEY`.

```json title="tailscale/serve.json"
{
    "TCP": {
        "443": {
            "HTTPS": true
        }
    },
    "Web": {
        "${TS_CERT_DOMAIN}:443": {
            "Handlers": {
                "/": {
                    "Proxy": "http://open-webui:8080"
                }
            }
        }
    }
}

```


key: chroma:document
string_value:
```

```yaml title="docker-compose.yaml"
---
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - HOST=127.0.0.1
      - WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
      - WEBUI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name
    restart: unless-stopped
  tailscale:
    image: tailscale/tailscale:latest
    environment:
      - TS_AUTH_ONCE=true
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_EXTRA_ARGS=--advertise-tags=tag:open-webui
      - TS_SERVE_CONFIG=/config/serve.json
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_HOSTNAME=open-webui
    volumes:
      - tailscale:/var/lib/tailscale
      - ./tailscale:/config
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

volumes:
  open-webui: {}
  tailscale: {}
```

:::warning


key: chroma:document
string_value:
volumes:
  open-webui: {}
  tailscale: {}
```

:::warning

If you run Tailscale in the same network context as Open WebUI, then by default users will be able to directly reach out to Open WebUI without going through the Serve proxy.
You will need use Tailscale's ACLs to restrict access to only port 443.

:::

### Cloudflare Tunnel with Cloudflare Access

[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/) can be used with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) to protect Open WebUI with SSO.
This is barely documented by Cloudflare, but `Cf-Access-Authenticated-User-Email` is set with the email address of the authenticated user.


key: chroma:document
string_value:
Below is an example Docker Compose file that sets up a Cloudflare sidecar.
Configuration is done via the dashboard.
From the dashboard, get a tunnel token, set the tunnel backend to `http://open-webui:8080`, and ensure that "Protect with Access" is checked and configured.

```yaml title="docker-compose.yaml"
---
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - HOST=127.0.0.1
      - WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Cf-Access-Authenticated-User-Email
    restart: unless-stopped
  cloudflared:
    image: cloudflare/cloudflared:latest
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    command: tunnel run
    restart: unless-stopped

volumes:
  open-webui: {}

```

### oauth2-proxy

[oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) is an authenticating reverse proxy that implements social OAuth providers and OIDC support.


key: chroma:document
string_value:
Given the large number of potential configurations, below is an example of a potential setup with Google OAuth.
Please refer to `oauth2-proxy`'s documentation for detailed setup and any potential security gotchas.


key: chroma:document
string_value:
```yaml title="docker-compose.yaml"
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - 'HOST=127.0.0.1'
      - 'WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-Forwarded-Email'
      - 'WEBUI_AUTH_TRUSTED_NAME_HEADER=X-Forwarded-User'
    restart: unless-stopped
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
    environment:
      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
      OAUTH2_PROXY_UPSTREAMS: http://open-webui:8080/
      OAUTH2_PROXY_PROVIDER: google
      OAUTH2_PROXY_CLIENT_ID: REPLACEME_OAUTH_CLIENT_ID
      OAUTH2_PROXY_CLIENT_SECRET: REPLACEME_OAUTH_CLIENT_ID
      OAUTH2_PROXY_EMAIL_DOMAINS: REPLACEME_ALLOWED_EMAIL_DOMAINS
      OAUTH2_PROXY_REDIRECT_URL: REPLACEME_OAUTH_CALLBACK_URL
      OAUTH2_PROXY_COOKIE_SECRET: REPLACEME_COOKIE_SECRET
      OAUTH2_PROXY_COOKIE_SECURE: "false"
    restart: unless-stopped
    ports:
      - 4180:4180/tcp
```


### Authentik


key: chroma:document
string_value:
### Authentik

To configure a [Authentik](https://goauthentik.io/) OAuth client, please refer to [documentation](https://docs.goauthentik.io/docs/applications) on how to create an application and `OAuth2/OpenID Provider`.
The allowed redirect URI should include `<open-webui>/oauth/oidc/callback`.

While creating provider, please note `App-name`, `Client-ID` and `Client-Secret` and use it for open-webui environment variables:

```
      - 'ENABLE_OAUTH_SIGNUP=true'
      - 'OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true'
      - 'OAUTH_PROVIDER_NAME=Authentik'
      - 'OPENID_PROVIDER_URL=https://<authentik-url>/application/o/<App-name>/.well-known/openid-configuration'
      - 'OAUTH_CLIENT_ID=<Client-ID>'
      - 'OAUTH_CLIENT_SECRET=<Client-Secret>'
      - 'OAUTH_SCOPES=openid email profile'
      - 'OPENID_REDIRECT_URI=https://<open-webui>/oauth/oidc/callback'
```

### Authelia


key: chroma:document
string_value:
### Authelia

[Authelia](https://www.authelia.com/) can be configured to return a header for use with trusted header authentication.
Documentation is available [here](https://www.authelia.com/integration/trusted-header-sso/introduction/).

No example configs are provided due to the complexity of deploying Authelia.


key: chroma:document
string_value:
---
sidebar_position: 2200
title: "👥 Our Team"
---

import { TopBanners } from "@site/src/components/TopBanners";

<TopBanners />

## 🌟 Meet Our Team!

Our team is led by the dedicated creator and founder, [Tim J. Baek](https://github.com/tjbck). Although Tim is currently the only official member of the team, we are incredibly fortunate to have a community of **[amazing contributors](https://github.com/open-webui/open-webui/graphs/contributors)** who find this project valuable and actively participate in its continued success.

### 💓 Our Contributors

<a href="https://github.com/open-webui/open-webui/graphs/contributors">
  <img
    src="https://contrib.rocks/image?repo=open-webui/open-webui"
    alt="Contributors"
  />
</a>

### Important Note:


key: chroma:document
string_value:
### Important Note:

To keep things smooth and organized, please do not contact or `@` mention anyone other than the official maintainer. If you have any questions or need assistance, `@tjbck` is your go-to person. You can also reach out via our official email, hello@openwebui.com. 📨

Your understanding and cooperation are appreciated! 💪


Let's keep building something awesome together! 🚀


key: chroma:document
string_value:
---
sidebar_position: 7
title: "📖 Tutorials"
---

# Tutorials

## Tutorials Welcome

Are you a content creator with a blog post or YouTube video about your pipeline setup? Get in touch
with us, as we'd love to feature it here!

## Featured Tutorials

[Monitoring Open WebUI with Filters](https://medium.com/@0xthresh/monitor-open-webui-with-datadog-llm-observability-620ef3a598c6) (Medium article by @0xthresh)

- A detailed guide to monitoring the Open WebUI using DataDog LLM observability.
  
[Building Customized Text-To-SQL Pipelines](https://www.youtube.com/watch?v=y7frgUWrcT4) (YouTube video by Jordan Nanos)

- Learn how to develop tailored text-to-sql pipelines, unlocking the power of data analysis and extraction.

[Demo and Code Review for Text-To-SQL with Open-WebUI](https://www.youtube.com/watch?v=iLVyEgxGbg4) (YouTube video by Jordan Nanos)

- A hands-on demonstration and code review on utilizing text-to-sql tools powered by the Open WebUI.


key: chroma:document
string_value:
---
sidebar_position: 300 
title: "🔄 Updating Open WebUI"
---



## Why isn't my Open WebUI updating?

To update your local Docker installation of Open WebUI to the latest version available, you can either use **Watchtower** or manually update the container. Follow either of the steps provided below to be guided through updating your existing Open WebUI image.

### Manual Update

1. **Stop and remove the current container**:

   This will stop the running container and remove it, but it won't delete the data stored in the Docker volume. (Replace `open-webui` with your container's name throughout the updating process if it's different for you.)

```bash
docker rm -f open-webui
```

2. **Pull the latest Docker image**:

   This will update the Docker image, but it won't update the running container or its data.

```bash
docker pull ghcr.io/open-webui/open-webui:main
```


key: chroma:document
string_value:
```bash
docker pull ghcr.io/open-webui/open-webui:main
```


:::info
**Remove any existing data in the Docker volume (NOT RECOMMENDED UNLESS ABSOLUTELY NECCESSARY!)**. Skip this step entirely if not needed and move on to the last step:

   If you want to start with a clean slate, you can remove the existing data in the Docker volume. Be careful, as this will delete all your chat histories and other data.

   The data is stored in a Docker volume named `open-webui`. You can remove it with the following command:

```bash
docker volume rm open-webui
```
:::

3. **Start the container again with the updated image and existing volume attached**:

   If you didn't remove the existing data, this will start the container with the updated image and the existing data. If you removed the existing data, this will start the container with the updated image and a new, empty volume. **For Nvidia GPU support, add `--gpus all` to the docker run command**


key: chroma:document
string_value:
```bash
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
```

## Automatically Updating Open WebUI with Watchtower

You can use [Watchtower](https://containrrr.dev/watchtower/) to automate the update process for Open WebUI. Here are three options:

### Option 1: One-time Update

You can run Watchtower as a one-time update to stop the current container, pull the latest image, and start a new container with the updated image and existing volume attached (**For Nvidia GPU support, add `--gpus all` to the docker run command**):

```bash
docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui
```

### Option 2: Running Watchtower as a Separate Container

You can run Watchtower as a separate container that watches and updates your Open WebUI container:


key: chroma:document
string_value:
You can run Watchtower as a separate container that watches and updates your Open WebUI container:

```bash
docker run -d --name watchtower \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower -i 300 open-webui
```

This will start Watchtower in detached mode, watching your Open WebUI container for updates every 5 minutes.

### Option 3: Integrating Watchtower with a `docker-compose.yml` File

You can also integrate Watchtower with your `docker-compose.yml` file to automate updates for Open WebUI (**For Nvidia GPU support, add `--gpus all` to the docker run command**):

```yml
version: '3'
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data

  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 300 open-webui
    depends_on:
      - open-webui

volumes:
  open-webui:
```


key: chroma:document
string_value:
volumes:
  open-webui:
```

In this example, Watchtower is integrated with the `docker-compose.yml` file and watches the Open WebUI container for updates every 5 minutes.

## Persistent Data in Docker Volumes

The data is stored in a Docker volume named `open-webui`. The path to the volume is not directly accessible, but you can inspect the volume with the following command:

```bash
docker volume inspect open-webui
```

This will show you the details of the volume, including the mountpoint, which is usually located in `/var/lib/docker/volumes/open-webui/_data`.


key: chroma:document
string_value:
---
sidebar_position: 5
title: "🔗 URL Parameters"
---

In Open WebUI, chat sessions can be customized through various URL parameters. These parameters allow you to set specific configurations, enable features, and define model settings on a per-chat basis. This approach provides flexibility and control over individual chat sessions directly from the URL.

## URL Parameter Overview

The following table lists the available URL parameters, their function, and example usage.


key: chroma:document
string_value:
| **Parameter**      | **Description**                                                                  | **Example**                          |
|-----------------------|----------------------------------------------------------------------------------|--------------------------------------------------------|
| `models`           | Specifies the models to be used, as a comma-separated list.                     | `/?models=model1,model2`         |
| `model`            | Specifies a single model to be used for the chat session.                       | `/?model=model1`                 |
| `youtube`          | Specifies a YouTube video ID to be transcribed within the chat.                 | `/?youtube=VIDEO_ID`             |
| `web-search`       | Enables web search functionality if set to `true`.                              | `/?web-search=true`              |


key: chroma:document
string_value:
| `tools` or `tool-ids` | Specifies a comma-separated list of tool IDs to activate in the chat.          | `/?tools=tool1,tool2`            |
| `call`             | Enables a call overlay if set to `true`.                                        | `/?call=true`                    |
| `q`                | Sets an initial query or prompt for the chat.                                   | `/?q=Hello%20there`              |
| `temporary-chat`   | Marks the chat as temporary if set to `true`, for one-time sessions.            | `/?temporary-chat=true`          |


key: chroma:document
string_value:
### 1. **Models and Model Selection**

- **Description**: The `models` and `model` parameters allow you to specify which [language models](/features/workspace/models.md) should be used for a particular chat session.
- **How to Set**: You can use either `models` for multiple models or `model` for a single model.
- **Example**:
  - `/?models=model1,model2` – This initializes the chat with `model1` and `model2`.
  - `/?model=model1` – This sets `model1` as the sole model for the chat.

### 2. **YouTube Transcription**

- **Description**: The `youtube` parameter takes a YouTube video ID, enabling the chat to transcribe the specified video.
- **How to Set**: Use the YouTube video ID as the value for this parameter.
- **Example**: `/?youtube=VIDEO_ID`
- **Behavior**: This triggers transcription functionality within the chat for the provided YouTube video.

### 3. **Web Search**


key: chroma:document
string_value:
### 3. **Web Search**

- **Description**: Enabling `web-search` allows the chat session to access [web search](/tutorials/integrations/web_search) functionality.
- **How to Set**: Set this parameter to `true` to enable web search.
- **Example**: `/?web-search=true`
- **Behavior**: If enabled, the chat can retrieve web search results as part of its responses.

### 4. **Tool Selection**

- **Description**: The `tools` or `tool-ids` parameters specify which [tools](/features/plugin/tools) to activate within the chat.
- **How to Set**: Provide a comma-separated list of tool IDs as the parameter's value.
- **Example**: `/?tools=tool1,tool2` or `/?tool-ids=tool1,tool2`
- **Behavior**: Each tool ID is matched and activated within the session for user interaction.

### 5. **Call Overlay**


key: chroma:document
string_value:
### 5. **Call Overlay**

- **Description**: The `call` parameter enables a video or call overlay in the chat interface.
- **How to Set**: Set the parameter to `true` to enable the call overlay.
- **Example**: `/?call=true`
- **Behavior**: Activates a call interface overlay, allowing features such as live transcription and video input.

### 6. **Initial Query Prompt**

- **Description**: The `q` parameter allows setting an initial query or prompt for the chat.
- **How to Set**: Specify the query or prompt text as the parameter value.
- **Example**: `/?q=Hello%20there`
- **Behavior**: The chat starts with the specified prompt, automatically submitting it as the first message.

### 7. **Temporary Chat Sessions**


key: chroma:document
string_value:
### 7. **Temporary Chat Sessions**

- **Description**: The `temporary-chat` parameter marks the chat as a temporary session. This may limit features such as saving chat history or applying persistent settings.
- **How to Set**: Set this parameter to `true` for a temporary chat session.
- **Example**: `/?temporary-chat=true`
- **Behavior**: This initiates a disposable chat session without saving history or applying advanced configurations.

<details>
<summary>Example Use Case</summary>
:::tip **Temporary Chat Session**
Suppose a user wants to initiate a quick chat session without saving the history. They can do so by setting `temporary-chat=true` in the URL. This provides a disposable chat environment ideal for one-time interactions.
:::
</details>

## Using Multiple Parameters Together

These URL parameters can be combined to create highly customized chat sessions. For example:


key: chroma:document
string_value:
These URL parameters can be combined to create highly customized chat sessions. For example:

```bash
/chat?models=model1,model2&youtube=VIDEO_ID&web-search=true&tools=tool1,tool2&call=true&q=Hello%20there&temporary-chat=true
```

This URL will:

- Initialize the chat with `model1` and `model2`.
- Enable YouTube transcription, web search, and specified tools.
- Display a call overlay.
- Set an initial prompt of "Hello there."
- Mark the chat as temporary, avoiding any history saving.


key: chroma:document
string_value:
---
sidebar_position: 3
title: "⚙️ Valves"
---

# Valves

Valves are input variables that are set per pipeline. Valves are set as a subclass of the `Pipeline` class, and initialized as part of the `__init__` method of the `Pipeline` class.

When adding valves to your pipeline, include a way to ensure that valves can be reconfigured by admins in the web UI. There are a few options for this:

- Use `os.getenv()` to set an environment variable to use for the pipeline, and a default value to use if the environment variable isn't set. An example can be seen below:

```
self.valves = self.Valves(
    **{
        "LLAMAINDEX_OLLAMA_BASE_URL": os.getenv("LLAMAINDEX_OLLAMA_BASE_URL", "http://localhost:11434"),
        "LLAMAINDEX_MODEL_NAME": os.getenv("LLAMAINDEX_MODEL_NAME", "llama3"),
        "LLAMAINDEX_EMBEDDING_MODEL_NAME": os.getenv("LLAMAINDEX_EMBEDDING_MODEL_NAME", "nomic-embed-text"),
    }
)
```


key: chroma:document
string_value:
- Set the valve to the `Optional` type, which will allow the pipeline to load even if no value is set for the valve.

```
class Pipeline:
    class Valves(BaseModel):
        target_user_roles: List[str] = ["user"]
        max_turns: Optional[int] = None
```

If you don't leave a way for valves to be updated in the web UI, you'll see the following error in the Pipelines server log after trying to add a pipeline to the web UI:
`WARNING:root:No Pipeline class found in <pipeline name>`


key: chroma:document
string_value:
# Using Virtual Environments

Create isolated Python environments using `venv`.

## Steps

1. **Create a Virtual Environment:**

   ```bash
   python3 -m venv venv
   ```

2. **Activate the Virtual Environment:**

   - On Linux/macOS:

     ```bash
     source venv/bin/activate
     ```

   - On Windows:

     ```bash
     venv\Scripts\activate
     ```

3. **Install Open WebUI:**

   ```bash
   pip install open-webui
   ```

4. **Start the Server:**

   ```bash
   open-webui serve
   ```


key: chroma:document
string_value:
---
sidebar_position: 10
title: "📹 Video Call"
---

COMING SOON!

📹 Video Call Feature: Enable video calls with supported vision models like LlaVA and GPT-4o, adding a visual dimension to your communications.

    Both Camera & Microphone access is required using a secure connection over HTTPS for this feature to work.


key: chroma:document
string_value:
---
sidebar_position: 9
title: "🎙️ Hands-Free Voice Call"
---

COMING SOON!

🎙️ Hands-Free Voice Call Feature: Initiate voice calls without needing to use your hands, making interactions more seamless.

    Microphone access is required using a secure connection over HTTPS for this feature to work.


key: chroma:document
string_value:
---
sidebar_position: 17
title: "🪝 Webhook Integrations"
---

Overview
--------

Open WebUI provides a webhook feature that allows you to receive notifications automatically whenever new users sign up to your instance. This is done by providing a webhook URL to Open WebUI, which will then send notifications to that URL when a new user account is created.

Configuring Webhooks in Open WebUI
---------------------------------

You will need to obtain a webhook URL from an external service that supports webhooks, such as a Discord channel or a Slack workspace. This URL will be used to receive notifications from Open WebUI.

To configure webhooks in Open WebUI, you have two options:

### Option 1: Configure through the Admin Interface


key: chroma:document
string_value:
### Option 1: Configure through the Admin Interface

1. Log in to your Open WebUI instance as an administrator.
2. Navigate to the `Admin Panel`.
3. Click the `Settings` tab located at the top.
4. From there, navigate to the `General` sectionn of the setting in the admin panel.
5. Locate the `Webhook URL` field and enter the webhook URL.
6. Save the changes.

### Option 2: Configure through Environment Variables

Alternatively, you can configure the webhook URL by setting the `WEBHOOK_URL` environment variable. For more information on environment variables in Open WebUI, see [Environment Variable Configuration](https://docs.openwebui.com/getting-started/advanced-topics/env-configuration/#webhook_url).

### Step 3: Verify the Webhook

To verify that the webhook is working correctly, create a new user account in Open WebUI. If the webhook is configured correctly, you should receive a notification at the specified webhook URL.

Webhook Payload Format
----------------------


key: chroma:document
string_value:
Webhook Payload Format
----------------------

The webhook payload sent by Open WebUI is in plain text and contains a simple notification message about the new user account. The payload format is as follows:

```
New user signed up: <username>
```

For example, if a user named "Tim" signs up, the payload sent would be:

```
New user signed up: Tim
```

Troubleshooting
--------------

* Make sure the webhook URL is correct and properly formatted.
* Verify that the webhook service is enabled and configured correctly.
* Check the Open WebUI logs for any errors related to the webhook.
* Verify the connection hasn't been interrupted or blocked by a firewall or proxy.
* The webhook server could be temporarily unavailable or experiencing high latency.
* If provided through the webhook service, verify if the Webhook API key is invalid, expired, or revoked.

Note: The webhook feature in Open WebUI is still evolving, and we plan to add more features and event types in the future.


key: chroma:document
string_value:
---
sidebar_position: 5
title: "🌐 Web Search"
---

:::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.
:::

## 🌐 Web Search

This guide provides instructions on how to set up web search capabilities in Open WebUI using various search engines.

## SearXNG (Docker)

> "**SearXNG is a free internet metasearch engine which aggregates results from various search services and databases. Users are neither tracked nor profiled.**"

## 1. SearXNG Configuration

To configure SearXNG optimally for use with Open WebUI, follow these steps:

**Step 1: `git clone` SearXNG Docker and navigate to the folder:**

1. Create a New Directory `searxng-docker`


key: chroma:document
string_value:
1. Create a New Directory `searxng-docker`

 Clone the searxng-docker repository. This folder will contain your SearXNG configuration files. Refer to the [SearXNG documentation](https://docs.searxng.org/) for configuration instructions.

```bash
git clone https://github.com/searxng/searxng-docker.git
```

Navigate to the `searxng-docker` repository:

```bash
cd searxng-docker
```

**Step 2: Locate and and modify the `.env` file:**

1. Uncomment `SEARXNG_HOSTNAME` from the `.env` file and set it accordingly:

```bash
# By default listen on https://localhost
# To change this:
# * uncomment SEARXNG_HOSTNAME, and replace <host> by the SearXNG hostname
# * uncomment LETSENCRYPT_EMAIL, and replace <email> by your email (require to create a Let's Encrypt certificate)

SEARXNG_HOSTNAME=localhost:8080/
# LETSENCRYPT_EMAIL=<email>


key: chroma:document
string_value:
SEARXNG_HOSTNAME=localhost:8080/
# LETSENCRYPT_EMAIL=<email>

# Optional:
# If you run a very small or a very large instance, you might want to change the amount of used uwsgi workers and threads per worker
# More workers (= processes) means that more search requests can be handled at the same time, but it also causes more resource usage

# SEARXNG_UWSGI_WORKERS=4
# SEARXNG_UWSGI_THREADS=4
```

**Step 3: Modify the `docker-compose.yaml` file**

3. Remove the `localhost` restriction by modifying the `docker-compose.yaml` file:

```bash
sed -i "s/127.0.0.1:8080/0.0.0.0:8080/"
```

**Step 4: Grant Necessary Permissions**

4. Allow the container to create new config files by running the following command in the root directory:

```bash
sudo chmod a+rwx searxng-docker/searxng
```

**Step 5: Create a Non-Restrictive `limiter.toml` File**

5. Create a non-restrictive `searxng-docker/searxng/limiter.toml` config file:

<details>
<summary>searxng-docker/searxng/limiter.toml</summary>


key: chroma:document
string_value:
<details>
<summary>searxng-docker/searxng/limiter.toml</summary>

```bash
# This configuration file updates the default configuration file
# See https://github.com/searxng/searxng/blob/master/searx/botdetection/limiter.toml

[botdetection.ip_limit]
# activate link_token method in the ip_limit method
link_token = false

[botdetection.ip_lists]
block_ip = []
pass_ip = []
```

</details>

**Step 6: Remove the Default `settings.yml` File**

6. Delete the default `searxng-docker/searxng/settings.yml` file if it exists, as it will be regenerated on the first launch of SearXNG:

```bash
rm searxng-docker/searxng/settings.yml
```

**Step 7: Create a Fresh `settings.yml` File**


key: chroma:document
string_value:
```bash
rm searxng-docker/searxng/settings.yml
```

**Step 7: Create a Fresh `settings.yml` File**

:::note
On the first run, you must remove `cap_drop: - ALL` from the `docker-compose.yaml` file for the `searxng` service to successfully create `/etc/searxng/uwsgi`.ini. This is necessary because the `cap_drop: - ALL` directive removes all capabilities, including those required for the creation of the `uwsgi.ini` file. After the first run, you should re-add `cap_drop: - ALL` to the `docker-compose.yaml` file for security reasons.
:::

7. Bring up the container momentarily to generate a fresh settings.yml file:

```bash
docker compose up -d ; sleep 10 ; docker compose down
```

**Step 8: Add Formats and Update Port Number**

8. Add HTML and JSON formats to the `searxng-docker/searxng/settings.yml` file:

```bash
sed -i 's/formats: \[\"html\"\/]/formats: [\"html\", \"json\"]/' searxng-docker/searxng/settings.yml
```

Generate a secret key for your SearXNG instance:


key: chroma:document
string_value:
Generate a secret key for your SearXNG instance:

```bash
sed -i "s|ultrasecretkey|$(openssl rand -hex 32)|g" searxng-docker/searxng/settings.yml
```

Windows users can use the following powershell script to generate the secret key:

```powershell
$randomBytes = New-Object byte[] 32
(New-Object Security.Cryptography.RNGCryptoServiceProvider).GetBytes($randomBytes)
$secretKey = -join ($randomBytes | ForEach-Object { "{0:x2}" -f $_ })
(Get-Content searxng-docker/searxng/settings.yml) -replace 'ultrasecretkey', $secretKey | Set-Content searxng-docker/searxng/settings.yml
```

Update the port number in the `server` section to match the one you set earlier (in this case, `8080`):

```bash
sed -i 's/port: 8080/port: 8080/' searxng-docker/searxng/settings.yml
```

Change the `bind_address` as desired:

```bash
sed -i 's/bind_address: "0.0.0.0"/bind_address: "127.0.0.1"/' searxng-docker/searxng/settings.yml
```

#### Configuration Files

#### searxng-docker/searxng/settings.yml (Extract)


key: chroma:document
string_value:
#### Configuration Files

#### searxng-docker/searxng/settings.yml (Extract)

The default `settings.yml` file contains many engine settings. Below is an extract of what the default `settings.yml` file might look like:

<details>
<summary>searxng-docker/searxng/settings.yml</summary>

```yaml
# see https://docs.searxng.org/admin/settings/settings.html#settings-use-default-settings
use_default_settings: true

server:
  # base_url is defined in the SEARXNG_BASE_URL environment variable, see .env and docker-compose.yml
  secret_key: "ultrasecretkey"  # change this!
  limiter: true  # can be disabled for a private instance
  image_proxy: true
  port: 8080
  bind_address: "0.0.0.0"

ui:
  static_use_hash: true


key: chroma:document
string_value:
ui:
  static_use_hash: true

search:
  safe_search: 0
  autocomplete: ""
  default_lang: ""
  formats:
    - html
    - json # json is required
  # remove format to deny access, use lower case.
  # formats: [html, csv, json, rss]
redis:
  # URL to connect redis database. Is overwritten by ${SEARXNG_REDIS_URL}.
  # https://docs.searxng.org/admin/settings/settings_redis.html#settings-redis
  url: redis://redis:6379/0
```

The port in the settings.yml file for SearXNG should match that of the port number in your docker-compose.yml file for SearXNG.

</details>

**Step 9: Update `uwsgi.ini` File**

9. Ensure your `searxng-docker/searxng/uwsgi.ini` file matches the following:

<details>
<summary>searxng-docker/searxng/uwsgi.ini</summary>

```ini
[uwsgi]
# Who will run the code
uid = searxng
gid = searxng

# Number of workers (usually CPU count)
# default value: %k (= number of CPU core, see Dockerfile)
workers = %k


key: chroma:document
string_value:
# Number of threads per worker
# default value: 4 (see Dockerfile)
threads = 4

# The right granted on the created socket
chmod-socket = 666

# Plugin to use and interpreter config
single-interpreter = true
master = true
plugin = python3
lazy-apps = true
enable-threads = 4

# Module to import
module = searx.webapp

# Virtualenv and python path
pythonpath = /usr/local/searxng/
chdir = /usr/local/searxng/searx/

# automatically set processes name to something meaningful
auto-procname = true

# Disable request logging for privacy
disable-logging = true
log-5xx = true

# Set the max size of a request (request-body excluded)
buffer-size = 8192

# No keep alive
# See https://github.com/searx/searx-docker/issues/24
add-header = Connection: close

# uwsgi serves the static files
static-map = /static=/usr/local/searxng/searx/static
# expires set to one day
static-expires = /* 86400
static-gzip-all = True
offload-threads = 4
```

</details>

## 2. Alternative Setup


key: chroma:document
string_value:
</details>

## 2. Alternative Setup

Alternatively, if you don't want to modify the default configuration, you can simply create an empty `searxng-docker` folder and follow the rest of the setup instructions.

### Docker Compose Setup

Add the following environment variables to your Open WebUI `docker-compose.yaml` file:

```yaml
services:
  open-webui:
    environment:
      ENABLE_RAG_WEB_SEARCH: True
      RAG_WEB_SEARCH_ENGINE: "searxng"
      RAG_WEB_SEARCH_RESULT_COUNT: 3
      RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 10
      SEARXNG_QUERY_URL: "http://searxng:8080/search?q=<query>"
```

Create a `.env` file for SearXNG:

```
# SearXNG
SEARXNG_HOSTNAME=localhost:8080/
```

Next, add the following to SearXNG's `docker-compose.yaml` file:


key: chroma:document
string_value:
Next, add the following to SearXNG's `docker-compose.yaml` file:

```yaml
services:
  searxng:
    container_name: searxng
    image: searxng/searxng:latest
    ports:
      - "8080:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    env_file:
      - .env
    restart: unless-stopped
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
      - DAC_OVERRIDE
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"
```

Your stack is ready to be launched with:

```bash
docker compose up -d
```


key: chroma:document
string_value:
Your stack is ready to be launched with:

```bash
docker compose up -d
```

:::note
On the first run, you must remove `cap_drop: - ALL` from the `docker-compose.yaml` file for the `searxng` service to successfully create `/etc/searxng/uwsgi`.ini. This is necessary because the `cap_drop: - ALL` directive removes all capabilities, including those required for the creation of the `uwsgi.ini` file. After the first run, you should re-add `cap_drop: - ALL` to the `docker-compose.yaml` file for security reasons.
:::

Alternatively, you can run SearXNG directly using `docker run`:

```bash
docker run --name searxng --env-file .env -v ./searxng:/etc/searxng:rw -p 8080:8080 --restart unless-stopped --cap-drop ALL --cap-add CHOWN --cap-add SETGID --cap-add SETUID --cap-add DAC_OVERRIDE --log-driver json-file --log-opt max-size=1m,max-file=1 searxng/searxng:latest
```

## 3. Confirm Connectivity


key: chroma:document
string_value:
## 3. Confirm Connectivity

Confirm connectivity to SearXNG from your Open WebUI container instance in your command line interface:

```bash
docker exec -it open-webui curl http://host.docker.internal:8080/search?q=this+is+a+test+query&format=json
```

## 4. GUI Configuration

1. Navigate to: `Admin Panel` -> `Settings` -> `Web Search`
2. Toggle `Enable Web Search`
3. Set `Web Search Engine` from dropdown menu to `searxng`
4. Set `Searxng Query URL` to one of the following examples:


key: chroma:document
string_value:
* `http://searxng:8080/search?q=<query>` (using the container name and exposed port, suitable for Docker-based setups)
* `http://host.docker.internal:8080/search?q=<query>` (using the `host.docker.internal` DNS name and the host port, suitable for Docker-based setups)
* `http://<searxng.local>/search?q=<query>` (using a local domain name, suitable for local network access)
* `https://<search.domain.com>/search?q=<query>` (using a custom domain name for a self-hosted SearXNG instance, suitable for public or private access)

**Do note the `/search?q=<query>` part is mandatory.**
5. Adjust the `Search Result Count` and `Concurrent Requests` values accordingly
6. Save changes

![SearXNG GUI Configuration](/img/tutorial_searxng_config.png)

## 5. Using Web Search in a Chat

To access Web Search, Click on the + next to the message input field.

Here you can toggle Web Search On/Off.

![Web Search UI Toggle](/img/web_search_toggle.png)


key: chroma:document
string_value:
Here you can toggle Web Search On/Off.

![Web Search UI Toggle](/img/web_search_toggle.png)

By following these steps, you will have successfully set up SearXNG with Open WebUI, enabling you to perform web searches using the SearXNG engine.

#### Note

You will have to explicitly toggle this On/Off in a chat.

This is enabled on a per session basis eg. reloading the page, changing to another chat will toggle off.

## Google PSE API

### Setup


key: chroma:document
string_value:
## Google PSE API

### Setup

1. Go to Google Developers, use [Programmable Search Engine](https://developers.google.com/custom-search), and log on or create account.
2. Go to [control panel](https://programmablesearchengine.google.com/controlpanel/all) and click `Add` button
3. Enter a search engine name, set the other properties to suit your needs, verify you're not a robot and click `Create` button.
4. Generate `API key` and get the `Search engine ID`. (Available after the engine is created)
5. With `API key` and `Search engine ID`, open `Open WebUI Admin panel` and click `Settings` tab, and then click `Web Search`
6. Enable `Web search` and Set `Web Search Engine` to `google_pse`
7. Fill `Google PSE API Key` with the `API key` and `Google PSE Engine Id` (# 4)
8. Click `Save`

![Open WebUI Admin panel](/img/tutorial_google_pse1.png)

#### Note

You have to enable `Web search` in the prompt field, using plus (`+`) button.
Search the web ;-)


key: chroma:document
string_value:
You have to enable `Web search` in the prompt field, using plus (`+`) button.
Search the web ;-)

![enable Web search](/img/tutorial_google_pse2.png)

## Brave API

### Docker Compose Setup

Add the following environment variables to your Open WebUI `docker-compose.yaml` file:

```yaml
services:
  open-webui:
    environment:
      ENABLE_RAG_WEB_SEARCH: True
      RAG_WEB_SEARCH_ENGINE: "brave"
      BRAVE_SEARCH_API_KEY: "YOUR_API_KEY"
      RAG_WEB_SEARCH_RESULT_COUNT: 3
      RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 10
```

## Mojeek Search API

### Setup

1. Please visit [Mojeek Search API page](https://www.mojeek.com/services/search/web-search-api/) to obtain an `API key`
2. With `API key`, open `Open WebUI Admin panel` and click `Settings` tab, and then click `Web Search`
3. Enable `Web search` and Set `Web Search Engine` to `mojeek`
4. Fill `Mojeek Search API Key` with the `API key`
5. Click `Save`

### Docker Compose Setup


key: chroma:document
string_value:
### Docker Compose Setup

Add the following environment variables to your Open WebUI `docker-compose.yaml` file:

```yaml
services:
  open-webui:
    environment:
      ENABLE_RAG_WEB_SEARCH: True
      RAG_WEB_SEARCH_ENGINE: "mojeek"
      BRAVE_SEARCH_API_KEY: "YOUR_MOJEEK_API_KEY"
      RAG_WEB_SEARCH_RESULT_COUNT: 3
      RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 10
```

## SearchApi API

[SearchApi](https://searchapi.io) is a collection of real-time SERP APIs. Any existing or upcoming SERP engine that returns `organic_results` is supported. The default web search engine is `google`, but it can be changed to `bing`, `baidu`, `google_news`, `bing_news`, `google_scholar`, `google_patents`, and others.

### Setup


key: chroma:document
string_value:
### Setup

1. Go to [SearchApi](https://searchapi.io), and log on or create a new account.
2. Go to `Dashboard` and copy the API key.
3. With `API key`, open `Open WebUI Admin panel` and click `Settings` tab, and then click `Web Search`.
4. Enable `Web search` and set `Web Search Engine` to `searchapi`.
5. Fill `SearchApi API Key` with the `API key` that you copied in step 2 from [SearchApi](https://www.searchapi.io/) dashboard.
6. [Optional] Enter the `SearchApi engine` name you want to query. Example, `google`, `bing`, `baidu`, `google_news`, `bing_news`, `google_videos`, `google_scholar` and `google_patents.` By default, it is set to `google`.
7. Click `Save`.

![Open WebUI Admin panel](/img/tutorial_searchapi_search.png)

#### Note

You have to enable `Web search` in the prompt field, using plus (`+`) button to search the web using [SearchApi](https://www.searchapi.io/) engines.

![enable Web search](/img/enable_web_search.png)

## Kagi API

Coming Soon

### Setup


key: chroma:document
string_value:
![enable Web search](/img/enable_web_search.png)

## Kagi API

Coming Soon

### Setup

## Serpstack API

Coming Soon

### Setup

## Serper API

Coming Soon

### Setup

## Serply API

Coming Soon

### Setup

## DuckDuckGo API

### Setup

No setup is required to use DuckDuckGo API for Open WebUI's built in web search! DuckDuckGo works out of the box in Open WebUI.

:::note
There is a possibility of your web searches being rate limited.
:::

## Tavily API

Coming Soon

### Setup

## Jina API

Coming Soon

### Setup

## Bing API

### Setup


key: chroma:document
string_value:
## Tavily API

Coming Soon

### Setup

## Jina API

Coming Soon

### Setup

## Bing API

### Setup

1. Navigate to the [AzurePortal](https://portal.azure.com/#create/Microsoft.BingSearch) and create a new resource. After creation, you'll be redirected to the resource overview page. From there, select "Click here to manage keys." ![click here to manage keys](https://github.com/user-attachments/assets/dd2a3c67-d6a7-4198-ba54-67a3c8acff6d)
2. On the key management page, locate Key1 or Key2 and copy your desired key.
3. Open the Open WebUI Admin Panel, switch to the Settings tab, and then select Web Search.
4. Enable the Web search option and set the Web Search Engine to bing.
5. Fill `SearchApi API Key` with the `API key` that you copied in step 2 from [AzurePortal](https://portal.azure.com/#create/Microsoft.BingSearch) dashboard.
6. Click `Save`.


