Proxmox Management Server.

Description

Proxmox Management Server is a from-scratch rewrite of a Proxmox VE management panel. It is a single-port monorepo: a Fastify and TypeScript backend serves the REST API, WebSockets, and background workers, and also serves the built React frontend, with everything sitting behind Traefik with automatic TLS.

The panel manages servers, virtual machines, LXC containers, networking, packages, and users, giving operators a single control plane over a fleet of Proxmox nodes.

Background

This is the second version of an earlier management panel, rebuilt from the ground up to consolidate a scattered v1 into a clean, typed monorepo. The v1 project is kept only as an archived, read-only reference. The rewrite was an opportunity to modernize the stack, introduce granular role-based permissions, and add a new networking allocation model.

Goal

The goal was a maintainable, secure, single-port deployment that could manage many Proxmox nodes with real-time task progress, granular RBAC, and a network allocation system that prevents port/IP/MAC collisions. It was designed to migrate its own database on startup and deploy behind Traefik with minimal manual configuration.

Features

• Authentication with email/password, TOTP two-factor, Redis-backed sessions, and JWT bearer tokens for API access.
• User management and granular role-based access control, with role priority and per-feature permissions plus activity logging.
• Server/node management: listing with filtering and sorting, soft delete, favorites, hidden and disabled servers, sync and smart sync, comments with attachments, labels, pricing, and backups.
• VM (QEMU) management: create/clone, suspend, terminate, reinstall, config editing, cross-node VM finder, and a noVNC console over a WebSocket proxy.
• LXC container management with the same lifecycle actions plus an xterm.js terminal over a termproxy WebSocket.
• A new networking model: network pools, explicit port/IP/MAC allocation with a free → reserved → assigned → quarantine state machine, collision-safe allocation, audit events, and automatic reconciliation to Traefik and dnsmasq.
• Package management with groups, RAM limits, and quota notifications.
• Task queue with real-time progress over WebSockets.
• Settings including multi-language UI (English/Indonesian), Discord webhook notifications, and global site configuration.

Technologies

• Backend: Fastify with TypeScript, Drizzle ORM on MySQL, BullMQ workers, and Redis
• Frontend: React with Vite and shadcn/ui
• Infrastructure: Docker for local MySQL/Redis/Traefik, Traefik with auto-TLS in production
• Security: helmet (CSP/HSTS), per-IP rate limiting, trustProxy, and secrets encrypted at rest

How to Run

Requires Node 20+ and Docker for local infrastructure. Run npm install, copy .env.example to .env and set secrets, then npm run infra:up to start MySQL, Redis, and Traefik, and npm run dev to run the backend and frontend concurrently. For production, a single-port image is built and run via docker compose -f docker-compose.prod.yml up -d --build; the container migrates on start and the first admin is seeded once via a script or the /api/setup installer.

Technical Decisions

A single-port architecture was chosen so the backend serves the built SPA directly, simplifying deployment behind Traefik with automatic TLS. Drizzle provides typed migrations that run on startup, and BullMQ with Redis backs both background jobs and real-time task progress. The most substantial design work went into the networking model, using a state machine plus FOR UPDATE SKIP LOCKED and node-level locks to make allocation collision-safe under concurrency, with periodic reconciliation that renders configuration out to Traefik and dnsmasq.

What I Learned

Rewriting from v1 was a strong lesson in scoping a rebuild around a clear feature list and a typed, single-port monorepo. The networking allocation system pushed me into concurrency-safe database patterns and state-machine design, while proxying noVNC and xterm.js over WebSockets deepened my understanding of streaming interactive sessions. Hardening the deployment — encrypted secrets, rate limiting, CSP/HSTS — made production security concerns concrete rather than abstract.

Notes

This project has no public GitHub repository, so the source is not available to browse. A screenshot or live preview may be added later. It manages live Proxmox infrastructure and depends on Docker-based services (MySQL, Redis, Traefik), so it is not runnable as a standalone browser demo.