docs: update README, CLAUDE.md, backlog, and .env.example
- README: add all features, correct tech stack (axios/setInterval), add IP addresses section, fix API routes - CLAUDE.md: fix architecture, remove SWR references, fix env var names, add IP address patterns - backlog: remove ip6= mention, clean duplicate entries, mark done - .env.example: remove unused PROXMOX_CONSOLE_TOKEN Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
50
README.md
50
README.md
@@ -4,17 +4,24 @@ A real-time dashboard for monitoring Proxmox VE nodes, VMs, and LXC containers.
|
||||
|
||||
## Features
|
||||
|
||||
- **Node overview** — CPU, memory, uptime, and load for each Proxmox node
|
||||
- **Node overview** — CPU, memory, uptime, and load for each Proxmox node, grouped into collapsible cards
|
||||
- **VM & LXC tracking** — status, resource usage across all nodes
|
||||
- **Summary cards** — total nodes, running/stopped VMs, aggregate memory
|
||||
- **Auto-refresh** — polling every 30s (configurable)
|
||||
- **Tabbed navigation** — switch between Nodes, VMs, and LXCs
|
||||
- **Per-VM/LXC IP addresses** — IPv4 from guest agent (QEMU) or network config (LXC), displayed below VM/LXC name
|
||||
- **Power control** — Start/stop/restart buttons per row
|
||||
- **Console links** — Opens Proxmox web UI console in a new tab
|
||||
- **Search / filter** — Client-side filtering by name, node, or status with auto-expand
|
||||
- **Group by node** — Collapsible node cards with running/stopped subtotals
|
||||
- **Manual refresh** — Button in header to refresh all data
|
||||
- **Custom poll interval** — Adjustable polling interval (default 30s) via header input
|
||||
- **Uptime display** — Formatted as "Xd Yh Zm"
|
||||
- **Auto-refresh** — Manual `setInterval` polling every 30s (configurable)
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Framework** — Next.js 15 (App Router)
|
||||
- **UI** — React 19, Tailwind CSS 4
|
||||
- **Data fetching** — SWR (auto-refresh), Axios
|
||||
- **Data fetching** — Axios with manual `setInterval` polling
|
||||
- **Proxmox** — API2 Token-based auth
|
||||
|
||||
## Getting Started
|
||||
@@ -32,7 +39,7 @@ cp .env.example .env.local
|
||||
```
|
||||
PROXMOX_API_URL=https://your-proxmox-host:8006/api2/json
|
||||
PROXMOX_TOKEN_ID=root@pam!token-name
|
||||
PROXMOX_TOKEN_SECRET=your-secret-uuid
|
||||
PROXMOX_TOKEN_SECRET=<your-token-secret>
|
||||
API_POLL_INTERVAL=30000
|
||||
NODE_TLS_REJECT_UNAUTHORIZED=0
|
||||
```
|
||||
@@ -69,27 +76,30 @@ src/
|
||||
│ │ ├── nodes/route.js # Proxmox node stats
|
||||
│ │ ├── vms/route.js # QEMU VMs across all nodes
|
||||
│ │ ├── lxc/route.js # LXC containers across all nodes
|
||||
│ │ └── status/route.js # Aggregated summary
|
||||
│ │ ├── status/route.js # Aggregated summary
|
||||
│ │ ├── power/route.js # Power control endpoint
|
||||
│ │ └── proxy/[...]/ # Reverse proxy to Proxmox web UI
|
||||
│ ├── layout.js
|
||||
│ └── page.js
|
||||
├── components/
|
||||
│ ├── Dashboard.js # Main dashboard with tabs & summary
|
||||
│ ├── NodeList.js # Node cards
|
||||
│ ├── NodeCard.js # Single node display
|
||||
│ ├── VMList.js # VM list view
|
||||
│ ├── LXCList.js # LXC list view
|
||||
│ └── StatusBadge.js # Online/good/warn/error/dead
|
||||
│ ├── Dashboard.js # Main dashboard with tabs, summary, polling
|
||||
│ ├── NodeList.js # Node overview
|
||||
│ ├── NodeCard.js # Single node card
|
||||
│ ├── VMList.js # VM list with group by node, filter, power actions
|
||||
│ ├── LXCList.js # LXC list with group by node, filter, power actions
|
||||
│ └── StatusBadge.js # Status indicator
|
||||
└── lib/
|
||||
└── proxmox.js # Proxmox API client & data mappers
|
||||
└── proxmox.js # Proxmox API client — nodes, VMs, LXC, IPs, power control
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `PROXMOX_API_URL` | Yes | Base URL of the Proxmox API |
|
||||
| `PROXMOX_API_URL` | Yes | Base URL of the Proxmox API (e.g. `https://host:8006/api2/json`) |
|
||||
| `PROXMOX_TOKEN_ID` | Yes | API token ID (e.g. `root@pam!monitorapp`) |
|
||||
| `PROXMOX_TOKEN_SECRET` | Yes | API token secret |
|
||||
| `PROXMOX_WEB_URL` | No | Web UI URL (defaults from `PROXMOX_API_URL`). Used for console links. |
|
||||
| `API_POLL_INTERVAL` | No | Refresh interval in ms (default: `30000`) |
|
||||
| `NODE_TLS_REJECT_UNAUTHORIZED` | No | Set to `0` for self-signed certs |
|
||||
|
||||
@@ -98,6 +108,14 @@ src/
|
||||
| Route | Method | Description |
|
||||
|---|---|---|
|
||||
| `/api/nodes` | GET | All Proxmox nodes |
|
||||
| `/api/vms` | GET | All QEMU VMs |
|
||||
| `/api/lxc` | GET | All LXC containers |
|
||||
| `/api/vms` | GET | All QEMU VMs (with IPv4 from guest agent) |
|
||||
| `/api/lxc` | GET | All LXC containers (with IPv4 from interfaces/config) |
|
||||
| `/api/status` | GET | Aggregated summary stats |
|
||||
| `/api/power` | POST | Power control (start/stop/restart) |
|
||||
| `/api/proxy/*` | GET | Reverse proxy to Proxmox web UI |
|
||||
|
||||
## Per-VM/LXC IP Addresses
|
||||
|
||||
- **QEMU VMs**: fetched from `/nodes/<node>/qemu/<id>/agent/network-get-interfaces` (requires QEMU guest agent installed)
|
||||
- **LXC**: fetched from `/nodes/<node>/lxc/<id>/interfaces` (preferred) or parsed from `/config` `net0`-`net7` fields (fallback)
|
||||
- IPv4 only — IPv6 addresses are excluded
|
||||
|
||||
Reference in New Issue
Block a user