Dilshod Rasulov
c4fda1b0bb
Instances deployed while save_vm_instance() dropped the owner are still sitting
in the database with owner_id = NULL, so their users cannot see them. Recover
the creator from the two places it was recorded:
1. deploy_tasks — user_id is a real foreign key stored when the deploy was
queued. server_id is absent for LXC deploys, so a NULL there is treated as
matching any server instead of discarding the row.
2. audit_logs — vm_create / ct_create / lxc_create entries, which only carry a
username and are matched by name.
Ownership decides who may see, stop and delete an instance, so a wrong guess is
worse than no owner at all: a row is updated only when every applicable piece of
evidence names the same existing user. VMIDs get reused, so conflicting evidence
is expected and those instances deliberately stay ownerless for an operator to
assign with assign_instances_owner.py. Existing owners, soft-deleted rows,
failed create events and logs from deleted users are all left alone, which also
makes the migration idempotent.
Note this recovers who created an instance, not who it was meant for: a VM an
admin created on behalf of a user is attributed to the admin, because the
intended owner was never persisted before the fix.
The attribution rule is a pure function (pick_backfill_owner) so it can be
tested directly. The migration's own statements are portable, so the tests run
it against SQLite with the two information_schema helpers stubbed out.
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.