Rob Bond
6696db82e9
- 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>
64 lines
3.4 KiB
Markdown
64 lines
3.4 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, 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.
|