Skip to content

Commit

Permalink
refac
Browse files Browse the repository at this point in the history
  • Loading branch information
@tjbck
tjbck committed Sep 25, 2024
1 parent d973f40 commit 831a48c
Show file tree
Hide file tree
Showing 14 changed files with 355 additions and 275 deletions.
2 changes: 1 addition & 1 deletion docs/getting-started/api.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
sidebar_position: 5
title: "Open WebUI API Endpoints"
title: "🔗 Open WebUI API Endpoints"
---

## Swagger Docs
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/env-configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
sidebar_position: 4
title: "Environment Variable Configuration"
title: "🌍 Environment Variable Configuration"
---


Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/installation.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
sidebar_position: 1
title: "Alternative Installation"
title: "🔧 Alternative Installation"
---

### Installing Both Ollama and Open WebUI Using Kustomize
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/logging.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
sidebar_position: 3
title: "Open WebUI Logging"
title: "📜 Open WebUI Logging"
---

## Browser Client Logging ##
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/updating.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
sidebar_position: 2
title: "Updating Open WebUI"
title: "🔄 Updating Open WebUI"
---

## Updating your Docker Installation
Expand Down
72 changes: 72 additions & 0 deletions docs/troubleshooting/connection-error.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
---
sidebar_position: 0
title: "🚧 Server Connection Error"
---

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.

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.

**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.

**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
```

274 changes: 8 additions & 266 deletions docs/troubleshooting/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,277 +3,19 @@ sidebar_position: 300
title: "🛠️ Troubleshooting"
---

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

<TopBanners />
## 🌟 General Troubleshooting Tips

## Open WebUI: Server Connection Error
Encountering issues? Don't worry, we're here to help! 😊 Start with this important step:

If you're experiencing connection issues, it’s often due to the WebUI docker container not being able to reach the Ollama server at 127.0.0.1:11434 (host.docker.internal:11434) inside the container . Use the `--network=host` flag in your docker command to resolve this. Note that the port changes from 3000 to 8080, resulting in the link: `http://localhost:8080`.
- 🔄 Make sure you're using the **latest version** of the software.

**Example Docker Command**:
With this project constantly evolving, updates and fixes are regularly added. Keeping your software up-to-date is crucial to take advantage of all the enhancements and fixes, ensuring the best possible experience. 🚀

```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
```
### 🤝 Community Support

If you're experiencing connection issues with the SSL error of huggingface.co, please checked the huggingface server, if it is down, you could set the `HF_ENDPOINT` to `https://hf-mirror.com/` in the `docker run` command.
This project thrives on community spirit and passion. If you still face problems after updating, we warmly invite you to join our vibrant community on [Discord](https://discord.com/invite/5rJgQTnV4s). There, you can share your experiences, find solutions, and connect with fellow enthusiasts who might be navigating similar challenges. Engaging with our community doesn't just help solve your problems; it strengthens the entire network of support, so we all grow together. 🌱

```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
```
🌟 If your issues are pressing and you need a quicker resolution, consider [supporting our project](/sponsorships). Your sponsorship not only fast-tracks your queries in a dedicated sponsor-only channel, but also directly supports the [dedicated maintainer](/mission) who is passionately committed to refining and enhancing this tool for everyone.

If you're using Podman on MacOS, to reach Ollama running on your computer you must enable the host loopback with `--network slirp4netns:allow_host_loopback=true` and override `OLLAMA_BASE_URL` to `http://host.containers.internal:11434`. The Open WebUI link remains the default: `http://localhost:3000`.

**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
```

## Microphone access and other permission issues with non-HTTPS connections
Chromium-based (Chrome, Brave, MS Edge, Opera, Vivaldi, ...) and firefox-based browsers often restrict site-level permissions on non-HTTPS URLs. This is most obvious when running an instance on your local network and reaching it from another device (example: a phone) of the same network: the microphone permission will most likely get denied right away without a clear way to whitelist the URL. Solutions for this include manually setting up HTTPS or adding an exception to the URL to flag it at secure. Use this at your own risk and we strongly recommend thinking carefully about the security implications before jumping into this. To flag a URL as secure:

- On chromium based browsers (Chrome, Brave, MS Edge, Opera, Vivaldi, ...): open `chrome://flags/#unsafely-treat-insecure-origin-as-secure` and add your non HTTPS address (for example: `http://192.168.1.35:3000`) then restart the app.

- On firefox-based browsers: Open `about:config`, and modify or add as a string the property `dom.securecontext.allowlist`, where one or more IPs can be defined split between commas. (Eg: http://127.0.0.1:8080 for a openwebui service provided locally, using port 8080).

## Difficulty Accessing Ollama from Open WebUI

If you're encountering difficulties accessing Ollama from the Open WebUI interface, it could be due to Ollama being configured to listen on a restricted network interface by default. To enable access from the Open WebUI, you need to configure Ollama to listen on a broader range of network interfaces.

Follow these steps to adjust the Ollama configuration:

1. **Configure Ollama Host**: Set the `OLLAMA_HOST` environment variable to `0.0.0.0`. This tells Ollama to listen on all available network interfaces, enabling connections from external sources, including the Open WebUI.

2. **Modify Ollama Environment Variables**: Depending on how you're running Ollama, you may need to adjust the environment variables accordingly. If you're running Ollama in a Docker container, ensure that the `OLLAMA_HOST` variable is correctly set within the container environment. For other deployment methods, refer to the respective documentation for instructions on setting environment variables.

3. **Restart Ollama**: After modifying the environment variables, restart the Ollama service to apply the changes. This ensures that Ollama begins listening on the specified network interfaces.

Once Ollama is configured to listen on `0.0.0.0`, you should be able to access it from the Open WebUI without any issues.

For detailed instructions on setting environment variables for Ollama, refer to the [official Ollama documentation](https://github.com/ollama/ollama/blob/main/docs/faq.md#setting-environment-variables-on-linux).

## General Connection Errors

**Ensure Ollama Version is Up-to-Date**: Always start by checking that you have the latest version of Ollama. Visit [Ollama's official site](https://ollama.com/) for the latest updates.

**Troubleshooting Steps**:

1. **Verify Ollama URL Format**:
- When running the Web UI container, ensure the `OLLAMA_BASE_URL` is correctly set. (e.g., `http://192.168.1.1:11434` for different host setups).
- In the Open WebUI, navigate to "Settings" > "General".
- Confirm that the Ollama Server URL is correctly set to `[OLLAMA URL]` (e.g., `http://localhost:11434`).

By following these enhanced troubleshooting steps, connection issues should be effectively resolved. For further assistance or queries, feel free to reach out to us on our community Discord.

## Network Diagrams of different deployments

#### Mac OS/Windows - Ollama on Host, Open WebUI in container

```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")
```

#### Mac OS/Windows - Ollama and Open WebUI in the same Compose stack

```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")
UpdateRelStyle(openwebui, ollama, $offsetX="-100", $offsetY="-50")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

#### Mac OS/Windows - Ollama and Open WebUI in containers, in different networks

```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")
```

#### Mac OS/Windows - Open WebUI in host network

```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 - Ollama on Host, Open WebUI in container

```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")
```

#### Linux - Ollama and Open WebUI in the same Compose stack

```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")
UpdateRelStyle(openwebui, ollama, $offsetX="-100", $offsetY="-50")
Rel(user, openwebui, "Makes requests via exposed port -p 3000:8080", "http://localhost:3000")
UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50")
```

#### Linux - Ollama and Open WebUI in containers, in different networks

```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")
```

#### Linux - Open WebUI in host network, Ollama on host

```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")
```

## Reset Admin Password

If you've forgotten your admin password, you can reset it by following these steps:

### Reset Admin Password in Docker

To reset the admin password for Open WebUI in a Docker deployment, generate a bcrypt hash of your new password and run a Docker command to update the database. Replace `your-new-password` with the desired password and execute:

1. **Generate bcrypt hash** (local machine):

```bash
htpasswd -bnBC 10 "" your-new-password | tr -d ':\n'
```

2. **Update password in Docker** (replace `HASH` and `[email protected]`):
```bash
docker run --rm -v open-webui:/data alpine/socat EXEC:"bash -c 'apk add sqlite && echo UPDATE auth SET password='\''HASH'\'' WHERE email='\''[email protected]'\''; | sqlite3 /data/webui.db'", STDIO
```

### Reset Admin Password Locally

For local installations of Open WebUI, navigate to the `open-webui` directory and update the password in the `backend/data/webui.db` database.

1. **Generate bcrypt hash** (local machine):

```bash
htpasswd -bnBC 10 "" your-new-password | tr -d ':\n'
```

2. **Update password locally** (replace `HASH` and `[email protected]`):
```bash
sqlite3 backend/data/webui.db "UPDATE auth SET password='HASH' WHERE email='[email protected]';"
```

## Understanding the Open WebUI Architecture

The Open WebUI system is designed to streamline interactions between the client (your browser) and the Ollama API. At the heart of this design is a backend reverse proxy, enhancing security and resolving CORS issues.

- **How it Works**: The Open WebUI is designed to interact with the Ollama API through a specific route. When a request is made from the WebUI to Ollama, it is not directly sent to the Ollama API. Initially, the request is sent to the Open WebUI backend via `/ollama` route. From there, the backend is responsible for forwarding the request to the Ollama API. This forwarding is accomplished by using the route specified in the `OLLAMA_BASE_URL` environment variable. Therefore, a request made to `/ollama` in the WebUI is effectively the same as making a request to `OLLAMA_BASE_URL` in the backend. For instance, a request to `/ollama/api/tags` in the WebUI is equivalent to `OLLAMA_BASE_URL/api/tags` in the backend.

- **Security Benefits**: This design prevents direct exposure of the Ollama API to the frontend, safeguarding against potential CORS (Cross-Origin Resource Sharing) issues and unauthorized access. Requiring authentication to access the Ollama API further enhances this security layer.
Together, let's harness these opportunities to create the best environment and keep pushing the boundaries of what we can achieve with our project. Thank you from the bottom of our hearts for your understanding, cooperation, and belief in our mission! 🙏
Loading

0 comments on commit 831a48c

Please sign in to comment.