Files

Rob Bond 6696db82e9 docs: update backlog and CLAUDE.md for console and power control

- backlog: mark Console Link as done (merged to main)
- CLAUDE.md: remove ConsolePanel and /api/vnc from architecture
- CLAUDE.md: note console URL format and new-tab behavior
- CLAUDE.md: remove PROXMOX_CONSOLE_TOKEN env var

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-11 13:18:10 +01:00

3.4 KiB

Raw Blame History

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, power action handler
│   ├── NodeList.js / NodeCard.js   # Node overview
│   ├── VMList.js / LXCList.js     # VM/LXC list views (each row has Console/Start/Stop buttons)
│   └── StatusBadge.js     # Status indicator
└── lib/
    └── proxmox.js         # Proxmox API client — getNodes, getVMs, getLXC, getSummary, powerControl

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 axios.get() calls for power actions (instant UI sync), and SWR with refreshInterval for periodic polling of the same endpoints.
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} params. Dashboard opens it via window.open() in a new tab so browser session cookies handle Proxmox auth.
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)
`NEXT_PUBLIC_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.

3.4 KiB Raw Blame History