LotusGuild/gandalf
3
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

README: add walkthrough GIF, rationale and gallery; add demo seed, mock PULSE and capture scripts
Lint / Python (flake8) (push) Failing after 2m9s
Details
Lint / JS (eslint) (push) Successful in 11s
Details
Lint / Deploy (push) Skipped
Details
Security / Python Security (bandit) (push) Successful in 39s
Details
Test / Python Tests (pytest) (push) Successful in 40s
Details
Lint / Notify on failure (push) Successful in 3s
Details

Browse Source
This commit is contained in:
jared
2026-10-03 02:23:26 -04:00
parent fed279a0bd
commit 4a1998046b
18 changed files with 365 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+46
View File
@@ -11,6 +11,52 @@ Deployed on **LXC 157** (monitor-02 / 10.10.10.9), reachable at `gandalf.lotusgu
**Design System**: [web_template](https://code.lotusguild.org/LotusGuild/web_template) — shared CSS, JS, and layout patterns for all LotusGuild apps
![GANDALF walkthrough: dashboard, link debug with optical readings, switch inspector, and a one-click link diagnostic](docs/img/demo.gif)
## Why this exists
A Proxmox/Ceph cluster lives or dies by its network, and network problems are sneaky: a link that flaps, a fibre with weak receive power, a switch port that quietly negotiated 1 Gbps. GANDALF watches the cluster's links from three angles at once (host NIC state from Prometheus, switch ports and LLDP from the UniFi controller, and reachability pings), alerts only on **regressions** (a link that was up and went down; ports that were never connected are learned as baseline and ignored), and files one ticket per real problem. When something looks wrong, a click on the switch port runs a full on-host diagnostic through [PULSE](https://code.lotusguild.org/LotusGuild/pulse) (`ethtool`, SFP optics, kernel log, LLDP) and explains what it found.
## Gallery
**Dashboard**: alert queue with linked tickets, a live topology, per-host interface status and the UniFi device inventory.
![Dashboard](docs/img/dashboard.png)
![Topology diagram](docs/img/topology.png)
![Host cards](docs/img/host-cards.png)
**Link debug**: per-interface speed, duplex, carrier flaps, error and drop rates, and **SFP optical readings** (temperature, TX/RX power) with colour-coded thresholds. Here a fibre with weak receive power is flagged while its neighbour is healthy.
![Link debug](docs/img/link-debug.png)
| Weak receive power on a fibre link | Healthy fibre link |
|---|---|
| ![SFP warning](docs/img/link-debug-sfp-warning.png) | ![SFP healthy](docs/img/link-debug-sfp.png) |
Switch ports are shown too, with PoE draw and the LLDP neighbour on each port:
![Switch ports](docs/img/link-debug-switch.png)
**Network inspector**: chassis diagrams for each UniFi switch. Click a port for its stats, LLDP neighbour and a side-by-side switch/server path check.
![Inspector](docs/img/inspector-port.png)
**One-click diagnostics**: GANDALF asks a PULSE worker to SSH to the host on the other end of the link and collect everything in one pass, then analyzes it: carrier, duplex and speed mismatches, SFP power levels, CRC errors, link flaps, recent kernel events and LLDP validation.
![Diagnostics](docs/img/inspector-diagnostics.png)
**Suppressions**: timed or manual maintenance windows per host, interface or UniFi device, with a full history.
![Suppressions](docs/img/suppressions.png)
**Light theme:**
![Dashboard, light theme](docs/img/dashboard-light.png)
<sub>Screenshots come from a throwaway local instance seeded with fictional data (documentation IP ranges), with PULSE replaced by a small mock. See `scripts/demo/`.</sub>
## Styling & Layout
GANDALF uses the **LotusGuild Terminal Design System**. For all styling, component, and layout documentation see: