From 7bd5bdb18e4bea583ed025ad17d4df654b8ebed5 Mon Sep 17 00:00:00 2001 From: Classic Date: Sun, 1 Mar 2026 11:27:09 +0100 Subject: [PATCH] docs: frontend vs backend networking for connections - 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 --- .../extensibility/open-terminal/index.md | 49 +++++++++++++++++++ docs/troubleshooting/connection-error.mdx | 29 +++++++++++ 2 files changed, 78 insertions(+) diff --git a/docs/features/extensibility/open-terminal/index.md b/docs/features/extensibility/open-terminal/index.md index 65bc8eac..db6122cb 100644 --- a/docs/features/extensibility/open-terminal/index.md +++ b/docs/features/extensibility/open-terminal/index.md @@ -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. diff --git a/docs/troubleshooting/connection-error.mdx b/docs/troubleshooting/connection-error.mdx index 83d73b15..0b352d2f 100644 --- a/docs/troubleshooting/connection-error.mdx +++ b/docs/troubleshooting/connection-error.mdx @@ -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