Dilshod Rasulov
c40611bedb
Some checks failed
Deploy to Production / Trigger production update (push) Failing after 10s
Quotas were only enforced by check_quota() on the backend, which answers 429
from the deploy endpoint — so a user walked all five wizard steps and learned
about the limit on the very last click. QuotaHint coloured the offending number
red but blocked nothing.
Split the two situations the UI never distinguished:
* No headroom at all (used >= limit): no configuration would ever fit, so the
wizard does not open. It is replaced by a message naming exactly which
limits are used up, with their numbers.
* Headroom left but the chosen configuration does not fit (used + requested >
limit): the wizard opens, and from the config step onwards it names the
metric and disables Next/Deploy until the resources are reduced.
The overrun check deliberately stays quiet until the config step. Gating every
step meant a default size that did not fit the remaining quota stranded the user
on the server picker, with no way to reach the fields and shrink it.
Neither block applies to admins: their own quota says nothing about an instance
they are creating on behalf of someone else, and blocking on it would lock an
admin with a quota out of the wizard entirely. The figures are still shown.
Also label the quota card as a projection. It renders used + the instance being
created, so a user with 3 of 4 instances saw "4 / 4" and reasonably read it as
already exhausted — which is what prompted this.
The arithmetic lives in features/instances/quota.ts as pure functions rather
than inline in JSX, so the two thresholds can be reasoned about on their own.
PVEmanager
Modern web panel for managing Proxmox servers, virtual machines and LXC containers
Overview
PVEmanager is a self-hosted web panel that provides a unified interface for managing multiple Proxmox VE servers and clusters. It covers the full VM/LXC lifecycle — from provisioning to monitoring — with role-based access control, notifications, and IP address management.
Features
Infrastructure
- Multi-server management — connect and manage multiple Proxmox servers and clusters from a single panel
- VM & LXC lifecycle — create, start, stop, restart, resize, delete virtual machines and containers
- Bulk operations — mass start / stop / restart / delete with queue and progress tracking
- Snapshot management — create, rollback, delete snapshots with an async queue system
- OS templates — deploy VMs from templates; cross-node replication handled automatically
- Cloud image catalog — browse, download, and convert OS images from cloud repositories (default Proxmox mirrors and custom sources); auto-convert to VM templates with architecture-aware filtering
- CT template deployment — create LXC containers directly from Proxmox CT template files (
.tar.zst,.tar.gz) with full IPAM and SSH key integration - Unified Create Instance Wizard — multi-step wizard supporting both QEMU VM templates and LXC CT templates in a single flow
- SDN support — manage Software-Defined Networking zones, VNets, and subnets; edit zones and VNets; auto-create IPAM networks for subnets
- Node networking — manage node-level network interfaces (bridges, bonds, VLANs); apply/revert pending config
- Networks page — unified UI for SDN and node interface management
App Store
- Self-hosted app catalog — one-click install of self-hosted apps, each into its own unprivileged LXC running Docker Compose (1 app = 1 LXC); multi-source catalog —
runtipi/runtipi-appstore(~265 apps) plus optionalgetumbrel/umbrel-apps(~380 apps), selectable viaAPPSTORE_SOURCES - Install wizard — dynamic app parameters (form fields), advanced LXC resources, auto-generated secrets, live install progress over WebSocket, and one-time credential display
- My Apps lifecycle — start / stop / restart / logs / delete, with background reconciliation (orphan detection) and per-app status
- Update & Rollback — snapshot-backed updates (
docker compose pull) with health-check and one-click rollback to the pre-update snapshot - Global operations tray — minimize a running install or golden-template build into a global tray that survives page navigation and tab reload; click a chip to resume the dialog where you left off
- Secure by design — unprivileged LXC only, Fernet-encrypted secrets, injection-safe
pct exec/pct push, RBACapp:view/app:install/app:manage
Access & Console
- VNC console — in-browser console via noVNC, no client software required
- xterm.js terminal — full interactive shell directly in the browser for LXC containers
- Remote commands — execute bash commands via QEMU Guest Agent
- SSH Keys Management — personal SSH key library per user; keys selectable when deploying VMs/LXC; admin can manage keys for any user
- RBAC v2 — granular role-based access control with per-resource permissions
- Server assignment — directly assign specific Proxmox servers to users with workspace-conflict validation
- VM/LXC ownership — assign an owner user to any VM or LXC container; non-privileged users see only their own instances everywhere, including the dashboard and per-node resource views
- Per-user quotas — limit each user's number of instances and total vCPU, RAM and disk; enforced at deploy time (HTTP 429), with admin management and self-service usage view
- Session management — active session list, remote session revocation, login protection
- Smart login redirect — users are automatically routed to the first page they have access to
Monitoring & Alerts
- Real-time metrics — CPU, RAM, Disk, Network charts per node and per VM; live per-disk fill, IOPS and network I/O rates (bytes/sec) on the instance Overview tab and instances list
- Background sync — automatic VM state synchronization from Proxmox API (
status/currentat 1 s granularity for running VMs) - Notifications — In-App (bell icon), Email (SMTP), Telegram (Bot API)
- Audit log — full action log with user, timestamp, and details
Other
- Command palette —
Ctrl+Kpalette with search over a unified navigation registry for keyboard-driven jumps to any page - IPAM — IP Address Management with allocation history and orphan detection
- Multilingual — Russian and English interface; language preference is per-user account
- Encrypted credentials — sensitive fields stored encrypted in the database
- Styled confirmation dialogs — all destructive actions use a consistent themed modal instead of the native browser
confirm()
Quick Start
# 1. Clone
git clone https://git.tzim.uz/markmorado/pvemanager.git
cd pvemanager
# 2. Configure
cp .env.example .env
cp backend/.env.example backend/.env
# Edit .env — set POSTGRES_PASSWORD and TZ
# 3. Start
docker compose up -d
# 4. Open
# http://localhost:3001
# Default login: admin / admin123
Important: Change the default password immediately after first login.
Requirements
| Requirement | Minimum |
|---|---|
| Docker | 24.x+ |
| Docker Compose | v2.x+ |
| RAM | 512 MB (app) + 256 MB (DB) |
| Proxmox VE | 7.x / 8.x / 9.x |
Configuration
Environment variables (.env)
# Database
POSTGRES_PASSWORD=your_secure_password
# Timezone (IANA format)
TZ=Europe/Moscow
# Update checks (for private repos — disable or provide a token)
DISABLE_UPDATE_CHECK=false
GITHUB_TOKEN= # optional, for private repo update checks
Notifications
Configured via the web interface — Settings → Notifications:
- Email — SMTP server, port, login, password (Yandex, Gmail, Mail.ru and others)
- Telegram — Bot token and Chat ID via @BotFather
Tech Stack
| Layer | Technology |
|---|---|
| Backend | Python 3.12, FastAPI, SQLAlchemy |
| Frontend | React 19, TypeScript, Vite 8 |
| UI Components | shadcn/ui, Tailwind CSS v4, lucide-react |
| State & Data | TanStack Query v5, Zustand, React Router v7 |
| Database | PostgreSQL 16 |
| Containerization | Docker, Alpine Linux |
| Proxmox API | proxmoxer |
| VNC | noVNC |
| Charts | Recharts |
| Terminal | xterm.js |
| i18n | i18next, react-i18next |
Documentation
| Document | Description |
|---|---|
| WIKI.md | Full user and administrator guide |
| CHANGELOG.md | Version history and release notes |
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Commit your changes:
git commit -m 'feat: add my feature' - Push:
git push origin feature/my-feature - Open a Pull Request
License
MIT — free to use, modify, and distribute.