Skip to content

Commit d926cd7

Browse files
byjgbyjg
committed
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`).
1 parent 4dda1ed commit d926cd7

5 files changed

Lines changed: 158 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ EasyHAProxy dynamically creates `haproxy.cfg` based on metadata from your worklo
2323
- **Custom SSL certificates** — volume-mount or label-embed your own PEM files
2424
- **TCP mode** — proxy any TCP service, not just HTTP
2525
- **Plugin system** — JWT validation, IP whitelisting, Cloudflare IP restoration, FastCGI, path blocking, and custom plugins
26-
- **HAProxy stats dashboard** — optional, password-protected
26+
- **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)
2727
- **Balance algorithms** — roundrobin, leastconn, source, uri, and more
2828

2929
## Supported platforms
@@ -56,6 +56,13 @@ EasyHAProxy is part of some projects:
5656
- [MicroK8s](docs/guides/microk8s.md)
5757
- [DigitalOcean Marketplace](docs/guides/digitalocean.md)
5858

59+
## Monitoring Dashboard
60+
61+
[![HAProxy Monitor](docs/dashboard_thumbnail.png)](docs/guides/dashboard.md)
62+
63+
A real-time dashboard is available at `http://<host>:11936/` whenever `HAPROXY_PASSWORD` is set —
64+
no extra containers, no Prometheus, no Grafana. See the [dashboard guide](docs/guides/dashboard.md).
65+
5966
## See EasyHAProxy in action
6067

6168
Click on the image to see the videos (use HD for better visualization)

‎docs/dashboard_login.png‎

23.5 KB
Loading

‎docs/dashboard_thumbnail.png‎

46.2 KB
Loading

‎docs/guides/dashboard.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
sidebar_position: 0
3+
sidebar_label: "Monitoring Dashboard"
4+
---
5+
6+
# HAProxy Monitoring Dashboard
7+
8+
EasyHAProxy ships a real-time monitoring dashboard that gives you a live view of your HAProxy
9+
instance — frontends, backends, servers, traffic volume, request rates, and more — all from a
10+
single page, with no extra software required.
11+
12+
![HAProxy Monitor dashboard](../dashboard.png)
13+
14+
## Enabling the dashboard
15+
16+
Two environment variables are required:
17+
18+
| Variable | Purpose |
19+
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
20+
| `HAPROXY_PASSWORD` | Enables the stats endpoint and the dashboard. |
21+
| `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. |
22+
23+
The dashboard page is served from port `HAPROXY_STATS_PORT + 10000`, but it fetches data from
24+
the stats API at `HAPROXY_STATS_PORT`. Because those are different ports, the browser treats
25+
them as different origins and enforces CORS. Set `HAPROXY_STATS_CORS_ORIGIN` to the exact origin
26+
you will use to open the dashboard.
27+
28+
```bash
29+
docker run \
30+
-e HAPROXY_PASSWORD=secret \
31+
-e HAPROXY_STATS_CORS_ORIGIN=http://localhost:11936 \
32+
... byjg/easy-haproxy
33+
```
34+
35+
If you access the dashboard from a non-localhost address (e.g. a server IP or hostname), match
36+
that origin instead:
37+
38+
```bash
39+
-e HAPROXY_STATS_CORS_ORIGIN=http://192.168.1.10:11936
40+
```
41+
42+
## Accessing the dashboard
43+
44+
The dashboard is served on a dedicated port: **`HAPROXY_STATS_PORT + 10000`**.
45+
46+
| `HAPROXY_STATS_PORT` (default `1936`) | Dashboard URL |
47+
|---------------------------------------|-----------------------------|
48+
| `1936` | `http://<host>:11936/` |
49+
| `8080` | `http://<host>:18080/` |
50+
51+
Open `http://<host>:11936/` (or `http://<host>:11936/dashboard.html`) in your browser.
52+
Requests to `/` and `/index.html` are automatically redirected to the dashboard page.
53+
Any other path returns a `404`.
54+
55+
### Login
56+
57+
The first time you open the dashboard (or after disconnecting), a **Connect to HAProxy** dialog
58+
appears:
59+
60+
![Connect to HAProxy login dialog](../dashboard_login.png)
61+
62+
Fill in the three fields:
63+
64+
| Field | What to enter | Example |
65+
|---|---|---|
66+
| **Stats URL** | The stats API base URL — `http://<host>:<HAPROXY_STATS_PORT>`. The dashboard appends `/;json` automatically. | `http://localhost:1936` |
67+
| **Username** | The value of `HAPROXY_USERNAME`. | `admin` |
68+
| **Password** | The value of `HAPROXY_PASSWORD`. | `secret` |
69+
70+
You can also adjust the **Polling Interval** (1 s – 60 s) to control how often the dashboard
71+
refreshes live data. Click **Connect** to open the main view.
72+
73+
:::info Why enter the Stats URL manually?
74+
The dashboard HTML is static — it has no knowledge of which host or port HAProxy is running on.
75+
Entering the URL at login time makes the dashboard work in any environment without any
76+
server-side configuration.
77+
:::
78+
79+
:::info Why a separate port?
80+
The stats API (`HAPROXY_STATS_PORT`) speaks the native HAProxy stats protocol.
81+
The dashboard port (`+10000`) is a plain HTTP frontend that proxies to an embedded Python
82+
HTTP server running inside EasyHAProxy. This split keeps the two concerns cleanly separated
83+
and avoids HAProxy's 16 KB inline-file limit.
84+
:::
85+
86+
## What you can see
87+
88+
### Summary cards
89+
90+
At the top of the page, eight cards give an instant health snapshot:
91+
92+
| Card | Description |
93+
|---------------|------------------------------------------------------------------------------|
94+
| **FRONTENDS** | Number of open frontends vs. total, with an "All UP" indicator |
95+
| **BACKENDS** | Number of backends that are UP vs. total; highlights DOWN backends in orange |
96+
| **SERVERS** | Server health across all backends — UP, DOWN, and "no check" counts |
97+
| **BYTES IN** | Cumulative bytes received since last HAProxy start |
98+
| **BYTES OUT** | Cumulative bytes sent since last HAProxy start |
99+
| **SESSIONS** | Current active sessions |
100+
| **REQUESTS** | Total HTTP requests processed |
101+
| **REQ/S** | Current request rate |
102+
103+
### Charts
104+
105+
Two real-time charts update every few seconds:
106+
107+
- **Traffic Volume** — bytes in and bytes out plotted over time
108+
- **Request Rate & Sessions** — req/s and concurrent sessions plotted over time
109+
110+
### Frontends & Backends table
111+
112+
A tabbed table lets you drill into every frontend and backend:
113+
114+
- **All** tab — frontends first, then backends and their servers
115+
- **Frontends** tab — name, status (OPEN/CLOSED), sessions, bytes in/out, request rate
116+
- **Backends & Servers** tab — backend health (UP/DOWN), session count, traffic, per-server
117+
detail with Expand / Flat toggle
118+
119+
You can filter by name using the search box above each section.
120+
121+
## What makes this unique
122+
123+
Most HAProxy installations expose only the raw stats page (tables of numbers) or require
124+
a separate Grafana + Prometheus stack for visualization.
125+
EasyHAProxy bundles a polished, self-contained dashboard that:
126+
127+
- requires **zero extra containers** — it runs inside the EasyHAProxy process itself
128+
- uses **HAProxy's own stats socket** — no metrics scraping pipeline
129+
- works **out of the box** — enable with a single environment variable
130+
- is accessible over a plain HTTP connection — no TLS setup needed for internal monitoring
131+
132+
## Environment variables
133+
134+
| Variable | Description | Default |
135+
|---|---|---|
136+
| `HAPROXY_PASSWORD` | Enables stats **and** the dashboard. Required. | *empty* |
137+
| `HAPROXY_USERNAME` | Username for the stats endpoint. | `admin` |
138+
| `HAPROXY_STATS_PORT` | Stats API port. Dashboard is served on this port **+ 10000**. | `1936` |
139+
| `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* |
140+
141+
See the full [Environment Variables reference](../reference/environment-variables.md) for details.
142+
143+
----
144+
[Open source ByJG](http://opensource.byjg.com)

‎docs/reference/environment-variables.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,14 @@ sidebar_label: "Environment Variables"
1919
| HAPROXY_USERNAME | (Optional) The HAProxy username for the statistics endpoint (used only when `HAPROXY_PASSWORD` is set). | `admin` |
2020
| HAPROXY_PASSWORD | (Optional) The HAProxy password to the statistics endpoint. Stats are **disabled** unless this is defined. | *empty* |
2121
| HAPROXY_STATS_PORT | (Optional) The HAProxy port to the statistics. If set to `false`, disable statistics. Only applies when `HAPROXY_PASSWORD` is defined. | `1936` |
22-
| 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* |
22+
| 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* |
2323
| HAPROXY_CUSTOMERRORS | (Optional) If HAProxy will use custom HTML errors. true/false. | `false` |
2424

25-
:::tip HAProxy Stats
26-
Statistics are only configured when `HAPROXY_PASSWORD` is set. Without a password, the stats section is not generated.
25+
:::tip HAProxy Stats & Dashboard
26+
Statistics are only configured when `HAPROXY_PASSWORD` is set. Without a password, neither the
27+
stats endpoint nor the monitoring dashboard is generated.
28+
When enabled, the real-time dashboard is available at `http://<host>:<HAPROXY_STATS_PORT + 10000>/`
29+
(default `http://<host>:11936/`). See the [Monitoring Dashboard guide](../guides/dashboard.md) for details.
2730
:::
2831

2932
:::note ACME/Certbot Environment Variables

0 commit comments

Comments
 (0)