Add pve-metrics/README.md

pve-metrics/README.md

@@ -0,0 +1,68 @@
+# Homelab Telemetry API (Proxmox)
+
+This script creates a lightweight, zero-dependency REST API endpoint directly on your Proxmox host to expose real-time system metrics (CPU, RAM, Network I/O, ZFS, and VM counts). 
+
+### 1 - Configure your Variables
+Before running, check your primary network interface and ZFS pool names. 
+Find your active interface:
+```bash
+ip -br a
+```
+Find your ZFS pool (if using ZFS):
+```bash
+zpool list
+```
+Edit `/opt/homelab-api.py` and update the configuration block at the top of the file to match your setup:
+```python
+PORT = 8080
+IFACE = "vmbr0"
+ENABLE_ZFS = True
+ZPOOL = "rpool"
+```
+
+### 2 - Open the Firewall (If applicable)
+If you are using the Proxmox Datacenter Firewall, you need to allow incoming TCP traffic on port `8080`. 
+*(Note: If your host firewall is disabled on your local LAN, you can skip this step).*
+
+If using `ufw` on a standard Debian/Ubuntu host:
+```bash
+sudo ufw allow 8080/tcp
+```
+If using `iptables`:
+```bash
+sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
+```
+
+### 3 - Enable and Start the Service
+Ensure the script is executable and the systemd service is loaded:
+```bash
+sudo chmod +x /opt/homelab-api.py
+sudo systemctl daemon-reload
+sudo systemctl enable --now homelab-api.service
+```
+
+### 4 - Test the Endpoint
+Test the call point by using `curl` from a different machine on your network to ensure the firewall is open and the script is returning data correctly:
+
+```bash
+curl http://<your-proxmox-ip>:8080/api/homelab
+```
+
+**Expected Output:**
+```json
+{
+  "cpu": 14.5,
+  "ram": {"percent": 56.2, "used_gb": 18.0, "total_gb": 32.0},
+  "rx_mb": 0.45,
+  "tx_mb": 2.10,
+  "load_avg": [0.45, 0.51, 0.49],
+  "uptime_days": 14.2,
+  "root_disk_pct": 34.1,
+  "temp_c": 42.5,
+  "zfs_pct": 61.2,
+  "vms_running": 4,
+  "lxcs_running": 6
+}
+```
+
+This endpoint can now be seamlessly consumed by your Astro/Stellar frontend dashboard, or added to **Uptime-Kuma** as a standard JSON HTTP monitor!