mirror of
https://github.com/open-webui/docs.git
synced 2025-12-12 07:29:49 +07:00
refac
This commit is contained in:
Timothy J. Baek
254
docs/troubleshooting/index.md
Normal file
254
docs/troubleshooting/index.md
Normal file
@@ -0,0 +1,254 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "🛠️ Troubleshooting"
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## 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.
|
||||
|
||||
## Open WebUI: Server Connection Error
|
||||
|
||||
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`.
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```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 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
|
||||
```
|
||||
|
||||
### 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")
|
||||
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
## 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 `admin@example.com`):
|
||||
```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
|
||||
```
|
||||
|
||||
### 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 `admin@example.com`):
|
||||
```bash
|
||||
sqlite3 backend/data/webui.db "UPDATE auth SET password='HASH' WHERE email='admin@example.com';"
|
||||
```
|
||||
Reference in New Issue
Block a user