Update documentation and guides for the monitoring dashboard
- Revised environment variables reference to clarify `HAPROXY_STATS_CORS_ORIGIN` requirements for the dashboard. - Enhanced README with details about the real-time monitoring dashboard and its capabilities. - Added a new "Monitoring Dashboard" guide, providing setup steps, login instructions, and feature overviews. - Included images for dashboard visuals (`dashboard_thumbnail.png`, `dashboard_login.png`).
This commit is contained in:
Joao Gilberto Magalhaes
parent
4dda1ed631
commit
d926cd7e69
5 changed files with 158 additions and 4 deletions
BIN
docs/dashboard_login.png
Normal file
BIN
docs/dashboard_login.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
BIN
docs/dashboard_thumbnail.png
Normal file
BIN
docs/dashboard_thumbnail.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
144
docs/guides/dashboard.md
Normal file
144
docs/guides/dashboard.md
Normal file
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
## 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://<host>:11936/` |
|
||||
| `8080` | `http://<host>:18080/` |
|
||||
|
||||
Open `http://<host>:11936/` (or `http://<host>: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:
|
||||
|
||||
|
||||
|
||||
Fill in the three fields:
|
||||
|
||||
| Field | What to enter | Example |
|
||||
|---|---|---|
|
||||
| **Stats URL** | The stats API base URL — `http://<host>:<HAPROXY_STATS_PORT>`. 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)
|
||||
|
|
@ -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://<host>:<HAPROXY_STATS_PORT + 10000>/`
|
||||
(default `http://<host>:11936/`). See the [Monitoring Dashboard guide](../guides/dashboard.md) for details.
|
||||
:::
|
||||
|
||||
:::note ACME/Certbot Environment Variables
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue