Dilshod Rasulov
c6a32255df
The SSL deployment aborted even when Let's Encrypt had issued a perfectly
valid certificate. obtain_ssl_certificate() confirmed success with
[ -d "nginx/certbot/conf/live/${domain}" ]
but certbot runs as root inside its container and creates live/, archive/
and accounts/ with mode 0700. Whenever deploy.sh runs as a non-root user
that test fails with EACCES no matter what is on disk, so every SSL deploy
fell back to the HTTP-only config and printed "Failed to obtain SSL
certificate" right after certbot reported the certificate was fine.
Check the certificate from inside a container instead, and treat the files
on disk as the source of truth rather than certbot's exit code, so a
certificate that is present and not yet due for renewal counts as success.
Pass --keep-until-expiring to make that case explicit.
Also drop the recursive chmod on nginx/certbot: it could not touch the
root-owned files it was aimed at (producing the wall of "Operation not
permitted" noise) and would have exposed the private keys if it had.
Verify nginx actually came up after switching to the SSL config and roll
back to HTTP if it did not — a crash-looping nginx takes the whole panel
offline, which is worse than serving without HTTPS.
Reload nginx every 6h so renewed certificates are picked up: nginx reads
the certificate once at startup, so the renewal loop would otherwise keep
serving the old one until the container happened to restart.
Ignore nginx/certbot/ — it holds Let's Encrypt private keys and was
untracked but not ignored.
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.