centersl/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-03-26 13:18:42 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs: frontend vs backend networking for connections

Browse Source 
- Add Networking & Connectivity section to Open Terminal docs
  - Request origin table (admin=backend, user=browser)
  - Common symptoms table (502, localhost resolution, timeouts)
  - Warning about same URL different results with reverse proxy example
  - Quick test command to verify backend reachability
- Add general Frontend vs Backend Connections section to connection-error.mdx
  - Core rule table explaining what localhost means in each context
  - Cross-references to Open Terminal and Tool Server networking docs
  - Covers the #1 source of connection confusion across all features
This commit is contained in:
Classic
2026-03-01 11:27:09 +01:00
parent db1ca1a342
commit 7bd5bdb18e
2 changed files with 78 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/features/extensibility/open-terminal/index.md
View File

@@ -252,6 +252,55 @@ When a terminal is selected, the chat controls panel gains a **Files** tab:
The file browser remembers your last-visited directory between panel open/close cycles and automatically reloads when you switch terminals.
### Networking & Connectivity
Understanding where requests originate is essential for configuring Open Terminal correctly. **Admin-configured and user-configured connections work fundamentally differently at the network level**, and using the wrong URL is the most common cause of connection failures.
#### Where Do Requests Come From?
| Connection Type | Request Origin | What `localhost` Means |
| :--- | :--- | :--- |
| **Admin-Configured (System)** | Open WebUI **backend server** | The machine/container running Open WebUI |
| **User-Configured (Direct)** | User's **browser** | The machine running the browser |
| **Generic OpenAPI (User)** | User's **browser** | The machine running the browser |
| **Generic OpenAPI (Global)** | Open WebUI **backend server** | The machine/container running Open WebUI |
This means:
- **A URL that works for a user-configured terminal may not work for an admin-configured terminal** (and vice versa), even though the URL is identical.
- If Open WebUI runs in Docker, `localhost` inside the container refers to the container itself — not the host machine. Use the container/service name (e.g. `http://open-terminal:8000`) or `host.docker.internal` instead.
- If you use a reverse proxy (e.g. Nginx) to expose Open Terminal under a path like `https://yourdomain.com/terminal`, the backend must be able to resolve and reach that hostname. If the hostname resolves to `127.0.0.1` on the backend, the request will fail with a 502 error.
#### Common Symptoms
| Symptom | Likely Cause | Fix |
| :--- | :--- | :--- |
| **502 Bad Gateway** on `/api/v1/terminals/...` endpoints | The Open WebUI backend cannot reach the terminal URL | Use a URL the backend can resolve — container name, internal IP, or `host.docker.internal` |
| **User connection works, admin connection doesn't** | The URL resolves correctly from the browser but not from the backend container | Use a different URL for admin config that the backend can reach |
| **`Connect call failed ('127.0.0.1', ...)`** in backend logs | Hostname resolves to localhost inside the container | Use the actual IP, container name, or Docker network hostname |
| **Connection timeout** | Firewall blocking traffic between containers/hosts | Ensure both containers are on the same Docker network, or open the necessary ports |
:::warning Same URL, Different Results
**The same URL can work as a user-configured terminal but fail as an admin-configured terminal.** This is not a bug — it's how networking works.
**Example:** You have Open Terminal at `https://myserver.com/terminal` with an Nginx reverse proxy. When a user adds this URL, their browser connects directly to `myserver.com` → Nginx → Open Terminal. When an admin adds the same URL, the Open WebUI backend tries to connect to `myserver.com`, which may resolve to `127.0.0.1` inside the Docker container — bypassing Nginx entirely and failing with a 502.
**Fix:** For admin-configured terminals, use the **internal URL** that the backend can reach directly (e.g. `http://open-terminal:8000` if both containers are on the same Docker network).
:::
:::tip Quick Test
To verify the backend can reach your terminal URL, exec into the Open WebUI container and test:
```bash
# From inside the Open WebUI container
curl -s http://open-terminal:8000/openapi.json | head -c 200
```
If this returns JSON, the backend can reach it. If it fails, your admin-configured terminal will also fail.
:::
For the same networking concepts applied to generic OpenAPI tool servers, see the [Tool Server Networking Guide](/features/extensibility/plugin/tools/openapi-servers/open-webui#main-difference-where-are-requests-made-from).
### Generic OpenAPI Tool Server
Open Terminal is also a standard FastAPI application that exposes an OpenAPI specification at `/openapi.json`. This means it works as a generic [OpenAPI Tool Server](/features/extensibility/plugin/tools/openapi-servers/open-webui) — useful when you want more control over which tools are enabled per-chat.

29
docs/troubleshooting/connection-error.mdx
View File

@@ -163,6 +163,35 @@ Disabling proxy buffering also **significantly improves streaming speed**, as re
- **Traefik**: Check compression/buffering middleware settings
- **Caddy**: Generally handles SSE correctly by default, but check for any buffering plugins
## 🌐 Frontend vs. Backend Connections (localhost Confusion)
Several Open WebUI features offer **two ways** to configure connections: a **user/direct** method (from the browser) and an **admin/global** method (from the backend). These work at completely different network levels, and the same URL can succeed in one and fail in the other.
### The Core Rule
| Request Origin | What `localhost` Means | Who Uses This |
| :--- | :--- | :--- |
| **Browser (client-side)** | The machine running the browser | User Tool Servers, User-Configured Terminals, Direct Connections |
| **Backend (server-side)** | The machine/container running Open WebUI | Global Tool Servers, Admin-Configured Terminals, Ollama connections |
### Why the Same URL Can Work and Fail
When you add a URL like `https://myserver.com/api` as a **user/direct** connection, your browser resolves `myserver.com` and connects directly. When you add the same URL as an **admin/global** connection, the Open WebUI backend resolves that hostname — and inside a Docker container, it may resolve to `127.0.0.1`, bypassing your reverse proxy entirely.
**Common symptoms:**
- 502 Bad Gateway on admin-configured connections while user connections work fine
- `Connect call failed ('127.0.0.1', ...)` in backend logs
- Connection timeout on global tool servers
**Fix:** For backend/admin connections, use the **internal URL** that the backend can actually reach:
- Docker service names (e.g. `http://open-terminal:8000`)
- `host.docker.internal` (to reach the host machine from inside Docker)
- Internal IPs (e.g. `http://192.168.1.50:8000`)
:::tip
This applies to **all** backend-proxied connections in Open WebUI — not just Open Terminal. The same pattern affects [Tool Server connections](/features/extensibility/plugin/tools/openapi-servers/open-webui#main-difference-where-are-requests-made-from), [Open Terminal admin connections](/features/extensibility/open-terminal#networking--connectivity), and Ollama/OpenAI API endpoints.
:::
## 🌟 Connection to Ollama Server
### 🚀 Accessing Ollama from Open WebUI