diff --git a/README.md b/README.md index b5bacbd..dd18174 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ EasyHAProxy dynamically creates `haproxy.cfg` based on metadata from your worklo - **Custom SSL certificates** — volume-mount or label-embed your own PEM files - **TCP mode** — proxy any TCP service, not just HTTP - **Plugin system** — JWT validation, IP whitelisting, Cloudflare IP restoration, FastCGI, path blocking, and custom plugins -- **HAProxy stats dashboard** — optional, password-protected +- **Real-time monitoring dashboard** — built-in, zero-dependency web UI with live traffic charts, frontend/backend health, and per-server stats (enabled with a single env var) - **Balance algorithms** — roundrobin, leastconn, source, uri, and more ## Supported platforms @@ -56,6 +56,13 @@ EasyHAProxy is part of some projects: - [MicroK8s](docs/guides/microk8s.md) - [DigitalOcean Marketplace](docs/guides/digitalocean.md) +## Monitoring Dashboard + +[![HAProxy Monitor](docs/dashboard_thumbnail.png)](docs/guides/dashboard.md) + +A real-time dashboard is available at `http://:11936/` whenever `HAPROXY_PASSWORD` is set — +no extra containers, no Prometheus, no Grafana. See the [dashboard guide](docs/guides/dashboard.md). + ## See EasyHAProxy in action Click on the image to see the videos (use HD for better visualization) diff --git a/docs/dashboard_login.png b/docs/dashboard_login.png new file mode 100644 index 0000000..07ae0e0 Binary files /dev/null and b/docs/dashboard_login.png differ diff --git a/docs/dashboard_thumbnail.png b/docs/dashboard_thumbnail.png new file mode 100644 index 0000000..0808d55 Binary files /dev/null and b/docs/dashboard_thumbnail.png differ diff --git a/docs/guides/dashboard.md b/docs/guides/dashboard.md new file mode 100644 index 0000000..c8b4954 --- /dev/null +++ b/docs/guides/dashboard.md @@ -0,0 +1,144 @@ +--- +sidebar_position: 0 +sidebar_label: "Monitoring Dashboard" +--- + +# HAProxy Monitoring Dashboard + +EasyHAProxy ships a real-time monitoring dashboard that gives you a live view of your HAProxy +instance — frontends, backends, servers, traffic volume, request rates, and more — all from a +single page, with no extra software required. + +![HAProxy Monitor dashboard](../dashboard.png) + +## Enabling the dashboard + +Two environment variables are required: + +| Variable | Purpose | +|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| `HAPROXY_PASSWORD` | Enables the stats endpoint and the dashboard. | +| `HAPROXY_STATS_CORS_ORIGIN` | Allows the dashboard page to call the stats API. **Required** — without it the browser blocks the requests and the dashboard shows no data. | + +The dashboard page is served from port `HAPROXY_STATS_PORT + 10000`, but it fetches data from +the stats API at `HAPROXY_STATS_PORT`. Because those are different ports, the browser treats +them as different origins and enforces CORS. Set `HAPROXY_STATS_CORS_ORIGIN` to the exact origin +you will use to open the dashboard. + +```bash +docker run \ + -e HAPROXY_PASSWORD=secret \ + -e HAPROXY_STATS_CORS_ORIGIN=http://localhost:11936 \ + ... byjg/easy-haproxy +``` + +If you access the dashboard from a non-localhost address (e.g. a server IP or hostname), match +that origin instead: + +```bash +-e HAPROXY_STATS_CORS_ORIGIN=http://192.168.1.10:11936 +``` + +## Accessing the dashboard + +The dashboard is served on a dedicated port: **`HAPROXY_STATS_PORT + 10000`**. + +| `HAPROXY_STATS_PORT` (default `1936`) | Dashboard URL | +|---------------------------------------|-----------------------------| +| `1936` | `http://:11936/` | +| `8080` | `http://:18080/` | + +Open `http://:11936/` (or `http://:11936/dashboard.html`) in your browser. +Requests to `/` and `/index.html` are automatically redirected to the dashboard page. +Any other path returns a `404`. + +### Login + +The first time you open the dashboard (or after disconnecting), a **Connect to HAProxy** dialog +appears: + +![Connect to HAProxy login dialog](../dashboard_login.png) + +Fill in the three fields: + +| Field | What to enter | Example | +|---|---|---| +| **Stats URL** | The stats API base URL — `http://:`. The dashboard appends `/;json` automatically. | `http://localhost:1936` | +| **Username** | The value of `HAPROXY_USERNAME`. | `admin` | +| **Password** | The value of `HAPROXY_PASSWORD`. | `secret` | + +You can also adjust the **Polling Interval** (1 s – 60 s) to control how often the dashboard +refreshes live data. Click **Connect** to open the main view. + +:::info Why enter the Stats URL manually? +The dashboard HTML is static — it has no knowledge of which host or port HAProxy is running on. +Entering the URL at login time makes the dashboard work in any environment without any +server-side configuration. +::: + +:::info Why a separate port? +The stats API (`HAPROXY_STATS_PORT`) speaks the native HAProxy stats protocol. +The dashboard port (`+10000`) is a plain HTTP frontend that proxies to an embedded Python +HTTP server running inside EasyHAProxy. This split keeps the two concerns cleanly separated +and avoids HAProxy's 16 KB inline-file limit. +::: + +## What you can see + +### Summary cards + +At the top of the page, eight cards give an instant health snapshot: + +| Card | Description | +|---------------|------------------------------------------------------------------------------| +| **FRONTENDS** | Number of open frontends vs. total, with an "All UP" indicator | +| **BACKENDS** | Number of backends that are UP vs. total; highlights DOWN backends in orange | +| **SERVERS** | Server health across all backends — UP, DOWN, and "no check" counts | +| **BYTES IN** | Cumulative bytes received since last HAProxy start | +| **BYTES OUT** | Cumulative bytes sent since last HAProxy start | +| **SESSIONS** | Current active sessions | +| **REQUESTS** | Total HTTP requests processed | +| **REQ/S** | Current request rate | + +### Charts + +Two real-time charts update every few seconds: + +- **Traffic Volume** — bytes in and bytes out plotted over time +- **Request Rate & Sessions** — req/s and concurrent sessions plotted over time + +### Frontends & Backends table + +A tabbed table lets you drill into every frontend and backend: + +- **All** tab — frontends first, then backends and their servers +- **Frontends** tab — name, status (OPEN/CLOSED), sessions, bytes in/out, request rate +- **Backends & Servers** tab — backend health (UP/DOWN), session count, traffic, per-server + detail with Expand / Flat toggle + +You can filter by name using the search box above each section. + +## What makes this unique + +Most HAProxy installations expose only the raw stats page (tables of numbers) or require +a separate Grafana + Prometheus stack for visualization. +EasyHAProxy bundles a polished, self-contained dashboard that: + +- requires **zero extra containers** — it runs inside the EasyHAProxy process itself +- uses **HAProxy's own stats socket** — no metrics scraping pipeline +- works **out of the box** — enable with a single environment variable +- is accessible over a plain HTTP connection — no TLS setup needed for internal monitoring + +## Environment variables + +| Variable | Description | Default | +|---|---|---| +| `HAPROXY_PASSWORD` | Enables stats **and** the dashboard. Required. | *empty* | +| `HAPROXY_USERNAME` | Username for the stats endpoint. | `admin` | +| `HAPROXY_STATS_PORT` | Stats API port. Dashboard is served on this port **+ 10000**. | `1936` | +| `HAPROXY_STATS_CORS_ORIGIN` | **Required for the dashboard.** Set to the exact origin you use to open the dashboard (e.g. `http://localhost:11936`). Without this the browser blocks stats API calls and the dashboard shows no data. | *empty* | + +See the full [Environment Variables reference](../reference/environment-variables.md) for details. + +---- +[Open source ByJG](http://opensource.byjg.com) diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md index 4e6026d..9e88d32 100644 --- a/docs/reference/environment-variables.md +++ b/docs/reference/environment-variables.md @@ -19,11 +19,14 @@ sidebar_label: "Environment Variables" | HAPROXY_USERNAME | (Optional) The HAProxy username for the statistics endpoint (used only when `HAPROXY_PASSWORD` is set). | `admin` | | HAPROXY_PASSWORD | (Optional) The HAProxy password to the statistics endpoint. Stats are **disabled** unless this is defined. | *empty* | | HAPROXY_STATS_PORT | (Optional) The HAProxy port to the statistics. If set to `false`, disable statistics. Only applies when `HAPROXY_PASSWORD` is defined. | `1936` | -| HAPROXY_STATS_CORS_ORIGIN | (Optional) Enable CORS for the HAProxy stats dashboard by specifying the allowed origin (e.g., `http://localhost:3000`). Only applies when `HAPROXY_PASSWORD` is defined. | *empty* | +| HAPROXY_STATS_CORS_ORIGIN | Required for the monitoring dashboard to function. Set to the origin you use to open the dashboard (e.g. `http://localhost:11936`). The dashboard page calls the stats API from a different port, so the browser enforces CORS — without this header the dashboard shows no data. Only applies when `HAPROXY_PASSWORD` is defined. | *empty* | | HAPROXY_CUSTOMERRORS | (Optional) If HAProxy will use custom HTML errors. true/false. | `false` | -:::tip HAProxy Stats -Statistics are only configured when `HAPROXY_PASSWORD` is set. Without a password, the stats section is not generated. +:::tip HAProxy Stats & Dashboard +Statistics are only configured when `HAPROXY_PASSWORD` is set. Without a password, neither the +stats endpoint nor the monitoring dashboard is generated. +When enabled, the real-time dashboard is available at `http://:/` +(default `http://:11936/`). See the [Monitoring Dashboard guide](../guides/dashboard.md) for details. ::: :::note ACME/Certbot Environment Variables