# UBDCC Dashboard

> Browser-based live dashboard for the [UNICORN Binance DepthCache Cluster (UBDCC)](https://github.com/oliver-zehentleitner/unicorn-binance-depth-cache-cluster).
> Monitor every depth cache in your cluster at a glance, spot out-of-sync caches, add or remove caches on the fly.
> Inspect cluster health (pods, nodes, replica donuts) at a glance.
> Manage Binance API credentials with a two-click-confirm UI.
> Generate REST-API snippets for curl, HTTPie, Python (UBLDC client), JavaScript, Go, C#, Java, Rust, PHP, C/C++ — the API Builder.
> Part of [UNICORN Binance Suite](https://github.com/oliver-zehentleitner/unicorn-binance-suite).

Version: 0.3.1. Python 3.9 – 3.14.

## Authorship & License

Author / Maintainer: Oliver Zehentleitner (https://github.com/oliver-zehentleitner)
License: MIT — free for commercial and private use. No paid license, no subscription, no commercial tier.

Install: `pip install ubdcc-dashboard`

## Quick Start

```sh
pip install ubdcc-dashboard
ubdcc-dashboard start
```

Default bind is `127.0.0.1:8080` — localhost only. Your browser opens automatically and shows the dashboard; enter the URL of your UBDCC REST API node (default `http://127.0.0.1:42081`) and click `Connect`.

## CLI

```
ubdcc-dashboard start [--host HOST] [--port PORT] [--no-browser]
                      [--proxy-timeout SECONDS] [--batch-workers N]
```

- `--host` — interface to bind. Default `127.0.0.1` (localhost only, secure). Use `--host 0.0.0.0` to expose on the network.
- `--port` — TCP port, default `8080`.
- `--no-browser` — do not auto-open the dashboard in a browser.
- `--proxy-timeout` — seconds for CORS-proxy outbound fetches (default 10).
- `--batch-workers` — worker threads for `/proxy_batch` (default 32).

## Architecture

Two files matter:

- `ubdcc_dashboard/static/index.html` — the dashboard. Vanilla JS, no framework.
- `ubdcc_dashboard/server.py` — stdlib HTTP server that serves the HTML and acts as a small CORS proxy so the browser can talk to any UBDCC cluster.

Proxy endpoints (for agents wanting to script against the launcher):
- `GET  /proxy?url=<encoded_url>` — single pass-through GET.
- `POST /proxy  {url, body}` — single pass-through JSON POST.
- `POST /proxy_batch {base, requests: [{id, path, params}, …]}` — threaded fan-out, returns `{results: {id → {status, body}}}`.
- `GET  /version` — returns `{"version": "..."}` read from `ubdcc_dashboard.__version__`. Used by the header version badge and usable as a liveness/health-check target.

## Relation to UBDCC

The dashboard is a client, not part of the cluster. It talks to a running UBDCC cluster via its public REST API (typical URL: `http://<cluster-host>:42081`). See https://github.com/oliver-zehentleitner/unicorn-binance-depth-cache-cluster for the cluster itself.

## Feature modals

The header has four connect-gated buttons besides `Disconnect`:

- **Cluster ●** — live health dot (green = ok, yellow = degraded, red = unreachable / missing pods / DC slot shortfall). Backed by a 30 s `/get_cluster_info` poll. Modal shows pod-by-role groups, per-node topology, per-DC replica donut + sync state, credentials summary, mgmt version and DB-sync age. Manual `Refresh` button inside the modal.
- **Credentials** — add / list / remove Binance API key pairs. `api_secret` input is masked; listed keys show only a preview. Remove is two-click confirm with 3 s auto-disarm.
- **DepthCaches** — opens the Add-DepthCaches modal with live `exchangeInfo` symbol picker (spot, cross / isolated margin, futures, options — mainnet + testnets).
- **API Builder** — 11 pre-built tasks (credentials, depthcaches, order book, cluster info) rendered as ready-to-paste REST-API calls in 10 languages: curl, HTTPie, Python, JavaScript, Go, C#, Java, Rust, PHP, C/C++. Python tab uses the official UBLDC `Cluster` client idiom (`BinanceLocalDepthCacheManager` context manager + `ubldc.cluster.<method>()`). PHP uses the built-in cURL extension; C/C++ uses libcurl (`gcc … -lcurl` / `g++ … -lcurl`). Editable Base URL, `Try it →` for GET-safe tasks via the dashboard's CORS proxy, Copy button with secure-context + `execCommand` fallback. Modal footer links to the cluster's OpenAPI reference and to the dashboard's GitHub issue tracker for snippet bug reports.

The header title also carries a **version badge** that queries PyPI once on load. Up to date → accent colour. Outdated → animated rainbow gradient with a `pip install -U ubdcc-dashboard` hint in the hover tooltip.

## Links

- GitHub:        https://github.com/oliver-zehentleitner/ubdcc-dashboard
- Docs:          https://oliver-zehentleitner.github.io/ubdcc-dashboard
- PyPI:          https://pypi.org/project/ubdcc-dashboard
- Issues:        https://github.com/oliver-zehentleitner/ubdcc-dashboard/issues
- Changelog:     https://github.com/oliver-zehentleitner/ubdcc-dashboard/blob/master/CHANGELOG.md
- Telegram:      https://t.me/unicorndevs