README: add Quick run block, demo GIF, rationale and gallery; add terminal renderer script

2026-10-03 01:25:46 -04:00
parent e7d183f627
commit 6201bc54c8
4 changed files with 139 additions and 0 deletions
@@ -4,6 +4,41 @@

 ProxDoc is a comprehensive diagnostic tool for Proxmox server health monitoring and system examination.

+![ProxDoc quick check running on a Proxmox node](docs/img/demo.gif)
+
+## ⚡ Quick run
+
+Copy and paste on any Proxmox node (as root). Nothing is installed; the script is fetched and run.
+
+```bash
+# Quick health check: services, temperatures, disk SMART, node exporter, Ceph
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --quick
+
+# Full examination (CPU, RAM, DIMMs, storage, network/NICs, HBAs, services, VMs, containers, Ceph)
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --diags
+
+# One area at a time
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --services     # vital Proxmox services
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --drives       # physical drive-bay map (DriveAtlas)
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --ceph         # Ceph health, OSD tree, usage
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --vm-list      # VM vitals
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --ct-list      # container vitals
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --backup       # backup health
+curl -sL "https://code.lotusguild.org/LotusGuild/proxDoc/raw/branch/main/proxDoc.sh" | bash -s -- --checks=cpu,ram   # pick specific checks
+```
+
+## Why this exists
+
+When something is wrong with one of six Proxmox nodes I want the same answer every time, in one command, without remembering which of a dozen tools to run: *are the services up, are the drives healthy, is Ceph happy, is it running hot?* ProxDoc is a single read-only bash script (it never changes system state) that runs those checks and prints a colour-coded report. It is meant to be run straight from the repository with `curl | bash`, so every node always runs the current version.
+
+## Gallery
+
+`--quick` on a live node (`compute-storage-01`): services, temperatures, SMART summary, node exporter and Ceph status. A Ceph warning (slow BlueStore operations, with the standing `noout` flag set) shows up in amber at the bottom.
+
+![proxDoc --quick](docs/img/quick-check.png)
+
+<sub>Rendered from real command output with `scripts/render_terminal.py`; private IPs are masked.</sub>
+
 ## Features

 - Complete system diagnostics and health checks