Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions docs/getting-started/advanced-topics/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Testing it and reporting what you find is the lowest-effort way to help, and it
| Requirement | Version |
|-------------|---------|
| **Python** | 3.11 or 3.12 (see note below; 3.13 not supported yet) |
| **Node.js** | 22.10+ |
| **Node.js** | 20.19+ on Node 20, or 22.13+ on Node 22 (`package.json` stops at 22.x; with `engine-strict` on, locked dependencies such as `pdfjs-dist`, `yargs` and `eslint-visitor-keys` need 20.19 or later, and `eslint-visitor-keys` needs 22.13 or later on Node 22; the official image builds on Node 22) |
| **Git** | Any recent version |

:::info Python version compatibility
Expand Down Expand Up @@ -79,7 +79,7 @@ npm run build
npm run dev
```

`npm run build` compiles the frontend and catches build-time errors early. `npm run dev` then starts the dev server at [http://localhost:5173](http://localhost:5173). It will show a waiting screen until the backend is running.
`npm run build` compiles the frontend and catches build-time errors early. `npm run dev` then starts the dev server at [http://localhost:5173](http://localhost:5173). Until the backend is running it redirects to a "Backend Required" error page; reload once the backend is up.

:::tip
If `npm install` fails with compatibility warnings, run `npm install --force`.
Expand Down Expand Up @@ -114,7 +114,7 @@ pip install -r requirements.txt -U
sh dev.sh
```

The backend starts at [http://localhost:8080](http://localhost:8080). API docs are available at [http://localhost:8080/docs](http://localhost:8080/docs).
`dev.sh` does not generate a secret key, so export `WEBUI_SECRET_KEY` (any long random value) or add it to the root `.env` before running it; without it the backend stops at startup. The backend starts at [http://localhost:8080](http://localhost:8080). API docs are available at [http://localhost:8080/docs](http://localhost:8080/docs). The `/docs` page is served only when `ENV=dev`, which is the default when running from source; the Docker image runs with `ENV=prod` and does not serve it.

Refresh the frontend at [http://localhost:5173](http://localhost:5173) and you should see the full application.

Expand All @@ -133,6 +133,8 @@ export CORS_ALLOW_ORIGIN="http://localhost:5173;http://localhost:8080;http://192

3. Restart the backend and browse to `http://192.168.1.42:5173`

`npm run dev` runs `vite dev --host`, so the dev server already listens on every interface and proxies `/api`, `/ollama`, `/openai`, `/oauth` and `/ws` to the backend. The CORS entry is still needed because Socket.IO checks the browser's `Origin` against `CORS_ALLOW_ORIGIN`, and the proxy passes that header through. If the backend runs on another machine, point the proxy at it with `WEBUI_BACKEND_URL=http://<host>:8080 npm run dev`.

---

## Troubleshooting
Expand Down Expand Up @@ -160,11 +162,11 @@ lsof -i :5173
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess
```

Terminate the process or change the port in `vite.config.js` (frontend) or `dev.sh` (backend).
Terminate the process, or start on another port: `PORT=9000 sh dev.sh` for the backend (then `WEBUI_BACKEND_URL=http://localhost:9000 npm run dev`), and `npm run dev:5050` for the frontend after adding `http://localhost:5050` to `CORS_ALLOW_ORIGIN` in `backend/dev.sh`.

### Icons not loading (CORS)
### Icons not loading

If static assets fail to load, configure `CORS_ALLOW_ORIGIN` in `backend/dev.sh` to include your frontend URL. See [CORS configuration](/reference/env-configuration#cors_allow_origin) for details.
Static assets come from the Vite dev server, not the backend, so `CORS_ALLOW_ORIGIN` does not affect them. Check the dev server's terminal for the failing request instead.

### Hot reload not working

Expand Down
8 changes: 5 additions & 3 deletions docs/getting-started/advanced-topics/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Open WebUI has two logging surfaces: the **browser console** for frontend debugg

## Frontend Logging

The frontend uses standard browser `console.log()` calls. Open your browser's developer tools (**F12** or **Cmd+Option+I** on macOS), navigate to the **Console** tab, and you'll see informational messages, warnings, and errors from the client application.
The frontend logs to the browser console: open your browser's developer tools (**F12** or **Cmd+Option+I** on macOS) and go to the **Console** tab. Production builds, the Docker image included, strip `console.log`, `console.debug` and `console.error` calls at build time unless the frontend was built with `ENV=dev`, so there you mainly see `console.warn` and `console.info` output plus the browser's own errors; run the dev server (`npm run dev`) for the full output.

Browser-specific documentation:

Expand Down Expand Up @@ -60,6 +60,8 @@ environment:
Use `DEBUG` for development and troubleshooting. For production, stick with `INFO` or `WARNING` to keep log volume manageable.
:::

A value Python's `logging` module does not recognise (for example `TRACE`) falls back to `INFO`. Use one of the level names above; aliases such as `WARN` or `FATAL` are not Loguru level names. The per-component `SRC_LOG_LEVELS` mechanism from older releases is kept only as an empty placeholder and no longer changes any logger.

---

### What the Log Level Costs
Expand Down Expand Up @@ -94,8 +96,8 @@ environment:
| `msg` | Log message |
| `caller` | Source location (`module:function:line`) |
| `extra` | Additional context data (if any) |
| `error` | Error details (if applicable) |
| `stacktrace` | Stack trace (if applicable) |
| `error` | Error details, as an object with `type`, `message` and `stacktrace` (if applicable) |
| `stacktrace` | Only on lines logged before the Loguru sink starts by a call that passes `stack_info=True` (Open WebUI itself does not); those early lines carry `caller` as the module name alone and `error` as a plain string |

**Example output:**

Expand Down
Loading