Add README with usage, proxy mapping and limitations
This commit is contained in:
Archibold committed
1 parent
85bad1d0e8
commit
2e78143812
1 file changed
+140
@@ -0,0 +1,140 @@
|
||||
# UwuDash MK3
|
||||
|
||||
A single Python app that is both the frontend and the backend for a dashboard of
|
||||
internal services. The sidebar has one button per service; clicking it loads the
|
||||
service in an iframe **through the dashboard's built-in reverse proxy**, so the
|
||||
upstream services never need to be public.
|
||||
|
||||
```
|
||||
browser ──► uwudash (host:port) ──► /proxy/<id>/<path> ──► upstream origin
|
||||
```
|
||||
|
||||
## Run
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
uv run uwudash-mk3
|
||||
# http://127.0.0.1:8000
|
||||
```
|
||||
|
||||
Development reload:
|
||||
|
||||
```bash
|
||||
uv run uwudash-mk3 --reload
|
||||
```
|
||||
|
||||
### Command line flags
|
||||
|
||||
| Flag | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `--host` | `127.0.0.1` | bind address |
|
||||
| `--port` | `8000` | bind port |
|
||||
| `--data-dir` | `data` | directory holding `services.json` |
|
||||
| `--services-file` | `<data-dir>/services.json` | explicit store path |
|
||||
| `--reload` | off | uvicorn reload on source changes |
|
||||
|
||||
### Environment variables
|
||||
|
||||
| Variable | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `UWUDASH_HOST` | `127.0.0.1` | bind address |
|
||||
| `UWUDASH_PORT` | `8000` | bind port |
|
||||
| `UWUDASH_DATA_DIR` | `data` | data directory |
|
||||
| `UWUDASH_SERVICES_FILE` | `data/services.json` | services store path |
|
||||
| `UWUDASH_PROXY_TIMEOUT` | `30.0` | upstream request timeout (seconds) |
|
||||
| `UWUDASH_STRIP_FRAME_OPTIONS` | `true` | strip `X-Frame-Options` and CSP `frame-ancestors` from proxied responses |
|
||||
|
||||
CLI flags override environment variables.
|
||||
|
||||
## Services
|
||||
|
||||
Services live in `data/services.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"services": [
|
||||
{
|
||||
"id": "grafana",
|
||||
"name": "Grafana",
|
||||
"url": "http://10.6.9.199:3000/dashboards",
|
||||
"description": "Metrics dashboards",
|
||||
"icon": "G",
|
||||
"open_in": "iframe",
|
||||
"enabled": true,
|
||||
"headers": { "Authorization": "Bearer ..." }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `id` is generated from the name (slugified, unique) and stays stable across edits.
|
||||
- `url` may include a path; that path becomes the landing path of the proxy.
|
||||
- `open_in` is `iframe` (default) or `newtab`.
|
||||
- `headers` are injected into every proxied request to that service.
|
||||
- `enabled: false` keeps the entry in the sidebar but the proxy returns `403`.
|
||||
|
||||
Edit them from the **Settings** page in the UI, or via the API.
|
||||
|
||||
## How the proxy works
|
||||
|
||||
Only the upstream **origin** (`scheme://host:port`) is mapped onto the dashboard:
|
||||
|
||||
```
|
||||
/proxy/<id> -> <origin>/
|
||||
/proxy/<id>/<path> -> <origin>/<path>
|
||||
```
|
||||
|
||||
So a service with `url = http://internal-host:8080/sub/page` is served at
|
||||
`/proxy/<id>/sub/page`, and any link the upstream page emits to
|
||||
`http://internal-host:8080/...` or `//internal-host:8080/...` is rewritten to
|
||||
`/proxy/<id>/...`. Relative links need no rewriting.
|
||||
|
||||
Details:
|
||||
|
||||
- `Location` headers on `3xx` responses are rewritten back onto the proxy prefix;
|
||||
redirects are **not** followed, so the browser stays on the proxy.
|
||||
- `text/html` responses are buffered and rewritten; everything else (JSON, CSS,
|
||||
images, downloads) is streamed through unchanged.
|
||||
- `X-Frame-Options` and CSP `frame-ancestors` are stripped from proxied responses
|
||||
so the iframe can render (disable with `UWUDASH_STRIP_FRAME_OPTIONS=false`).
|
||||
- Hop-by-hop request/response headers are dropped; per-service `headers` are merged
|
||||
into the upstream request.
|
||||
- Request bodies are buffered with a 10 MB cap (`413` above it).
|
||||
- WebSocket upgrades are rejected with `400` - the proxy is HTTP only.
|
||||
|
||||
## API
|
||||
|
||||
| Method | Path | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/services` | list services |
|
||||
| `POST` | `/api/services` | create |
|
||||
| `GET` | `/api/services/{id}` | read |
|
||||
| `PATCH` / `PUT` | `/api/services/{id}` | update |
|
||||
| `DELETE` | `/api/services/{id}` | delete |
|
||||
| `GET` | `/api/services/{id}/health` | upstream reachability check |
|
||||
| `GET` | `/api/config` | effective config |
|
||||
| `GET` | `/health` | dashboard health |
|
||||
| `ANY` | `/proxy/{id}` and `/proxy/{id}/{path}` | reverse proxy |
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
src/uwudash_mk3/
|
||||
config.py env-driven Config dataclass
|
||||
models.py Service / ServiceInput / ServicePatch + URL helpers
|
||||
store.py JSON file store (atomic writes, lock)
|
||||
proxy.py reverse proxy: header filtering, HTML/redirect rewriting
|
||||
api.py /api routes
|
||||
app.py FastAPI factory, static mount, proxy routes
|
||||
main.py CLI entrypoint
|
||||
templates/ index.html
|
||||
static/ styles.css, app.js
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- No authentication on the dashboard itself - it is meant for a trusted LAN.
|
||||
- No WebSocket proxying.
|
||||
- Upstream cookies work, but they are scoped to the dashboard origin, so
|
||||
cross-service cookie sharing is possible if two services share a proxy host.
|
||||
Reference in new issue
Block a user