Rob Bond
bc2dda2147
- 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>
65 lines
3.7 KiB
Markdown
65 lines
3.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project
|
|
|
|
Real-time dashboard for monitoring Proxmox VE nodes, VMs, and LXC containers. Next.js 15 App Router with Tailwind CSS 4.
|
|
|
|
## Commands
|
|
|
|
```
|
|
npm run dev # Start dev server (usually on port 3002)
|
|
npm run build # Production build
|
|
npm run start # Start production server
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
├── app/
|
|
│ ├── api/ # Next.js API routes (server-side)
|
|
│ │ ├── proxy/[...]/route.js # Reverse proxy to Proxmox web UI
|
|
│ │ ├── power/route.js # Power control (start/stop/restart)
|
|
│ │ ├── nodes/vms/lxc/route.js # Query endpoints (aggregates across nodes)
|
|
│ │ └── status/route.js # Aggregated summary stats
|
|
│ ├── layout.js # Root layout (Inter font, metadata)
|
|
│ └── page.js # Entry — renders <Dashboard />
|
|
├── components/
|
|
│ ├── Dashboard.js # Main UI: tabs, summary cards, polling, power action handler
|
|
│ ├── NodeList.js / NodeCard.js # Node overview (collapsible cards with subtotals)
|
|
│ ├── VMList.js / LXCList.js # VM/LXC lists grouped by node with search, power actions, console links, IPs
|
|
│ └── StatusBadge.js # Status indicator
|
|
└── lib/
|
|
└── proxmox.js # Proxmox API client — getNodes, getVMs, getLXC, getSummary, powerControl, getConfigIPs
|
|
```
|
|
|
|
## Key Patterns
|
|
|
|
- **Dual API endpoints**: Queries use `/api2/json`, power operations use `/api2/extjs`. Power actions send empty body `{}`.
|
|
- **API routes** aggregate data across all Proxmox nodes before returning to the client. They are thin wrappers around `lib/proxmox.js`.
|
|
- **Dashboard** uses direct React state + manual `setInterval` polling (not SWR) for periodic data fetching. Power actions use direct `axios.get()` calls for instant UI sync.
|
|
- **Power action flow**: `handlePowerAction` in Dashboard.js fires `POST /api/power`, then immediately re-fetches all four caches (`/api/nodes`, `/api/vms`, `/api/lxc`, `/api/status`) and sets state directly. Use `requestAnimationFrame` flush before the API call so status messages paint.
|
|
- **Auth**: PVEAPIToken header: `Authorization: PVEAPIToken=${TOKEN_ID}=${TOKEN_SECRET}`.
|
|
- **Console**: VMList/LXCList build `consoleUrl` from `PROXMOX_WEB_URL` with `?console={qemu|lxc}&vmid={id}&node={node}&resize=scale` params. Dashboard opens it via `window.open()` in a new tab so browser session cookies handle Proxmox auth. LXC console uses `xtermjs=1`, QEMU uses `novnc=1`.
|
|
- **Per-VM/LXC IPs**: `getConfigIPs()` in proxmox.js fetches QEMU IPs from `/agent/network-get-interfaces`, LXC IPs from `/interfaces` endpoint (fallback to `/config` `net0`-`net7` parsing). IPv4 only.
|
|
- **TLS**: `NODE_TLS_REJECT_UNAUTHORIZED=0` in `.env.local` for self-signed certs. Shows a console warning — acceptable for internal lab use.
|
|
- **Tailwind CSS 4**: Uses `@tailwindcss/postcss` config. CSS vars in `globals.css` for theming.
|
|
- **All API routes return 502 on Proxmox failures** with `{ error, data: null }`.
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|---|---|---|
|
|
| `PROXMOX_API_URL` | Yes | Base URL, e.g. `https://host:8006/api2/json` |
|
|
| `PROXMOX_TOKEN_ID` | Yes | API token ID |
|
|
| `PROXMOX_TOKEN_SECRET` | Yes | API token secret |
|
|
| `PROXMOX_WEB_URL` | No | Web UI URL (defaults from PROXMOX_API_URL) |
|
|
| `API_POLL_INTERVAL` | No | Poll interval ms (default 30000) |
|
|
| `NODE_TLS_REJECT_UNAUTHORIZED` | No | `0` for self-signed certs |
|
|
|
|
## Git Workflow
|
|
|
|
Repository is on Gitea. User works in feature branches, merges via PR. Use clean main as base. Gitea token may need to be embedded in remote URL for auth.
|