Proxmox Atlas

Real-time multi-cluster monitoring dashboard for Proxmox VE infrastructure.

Proxmox Atlas provides a unified, high-performance dashboard to monitor all your Proxmox VE clusters in real time. Built with a performance-first architecture (~100MB RAM), it delivers live metrics via Server-Sent Events, anomaly detection, capacity planning simulations, and full historical data powered by Prometheus.

---

✨ Features

• Multi-Cluster Monitoring — Monitor unlimited Proxmox clusters from a single dashboard
• Real-Time Metrics — Live CPU, RAM, Storage, Network, Disk I/O, Pressure Stalls via SSE
• Anomaly Detection — Automatic 3σ statistical deviation alerts powered by Prometheus PromQL
• What-If Engine — Simulate node failures and predict migration outcomes
• Time Machine — Browse historical metrics with interactive Prometheus-backed charts
• Uptime Heatmaps — 30-day uptime visualization for every node and VM
• Smart Alerts — Configurable thresholds with webhook notifications (Slack, Teams, Discord)
• JWT Authentication — Secure login with bcrypt-hashed passwords and role-based access control
• HTTPS by Default — Self-signed SSL certificate auto-generated on first deploy
• Ultra Lightweight — Native SVG sparklines on the dashboard, Recharts for historical views (lazy-loaded), ~100MB RAM footprint

---

🚀 Quick Start

One-Line Install

curl -sSL https://raw.githubusercontent.com/Losstarot85/proxmox-atlas/main/install.sh | bash

This will:

1. Clone the repository to ~/proxmox-atlas
2. Generate a self-signed SSL certificate
3. Build and start all containers
4. Atlas will be available at https://<your-ip>

Default Credentials

Field	Value
Username	admin
Password	admin

You will be prompted to set a new password on first login.

Additional users can be created from Settings → User Management after logging in as admin.

Manual Install

git clone https://github.com/Losstarot85/proxmox-atlas.git
cd proxmox-atlas
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout certs/atlas.key -out certs/atlas.crt \
    -subj "/CN=proxmox-atlas"
docker compose up -d --build

---

🏗️ Architecture

                    ┌─────────────────────┐
                    │   Browser (HTTPS)   │
                    └─────────┬───────────┘
                              │ :443
                    ┌─────────▼───────────┐
                    │   Nginx (SSL/TLS)   │
                    │  Static Files + API  │
                    │   Reverse Proxy      │
                    └───┬─────────────┬───┘
                        │             │
              ┌─────────▼──┐   ┌──────▼────────┐
              │  FastAPI    │   │  Prometheus   │
              │  Backend    │◄──│  TSDB (30d)   │
              │  :8000      │──►│  :9090        │
              └─────────────┘   └───────────────┘

• Nginx — SSL termination, static frontend, API reverse proxy, security headers
• Backend — FastAPI + Uvicorn, SSE streaming, JWT auth, polling engine
• Prometheus — Time-series database for historical metrics and anomaly detection

Backend and Prometheus are not exposed to the host network. Only Nginx is accessible.

---

⚙️ Configuration

Adding Clusters

Clusters can be added directly from the Settings tab in the web UI. No manual file editing required.

Alternatively, you can pre-configure clusters by creating a clusters.json file in the Docker data volume.

Environment Variables

Variable	Default	Description
ATLAS_HTTPS_PORT	443	HTTPS port exposed on the host
ATLAS_HTTP_PORT	80	HTTP port (redirects to HTTPS)
DATA_DIR	/data	Path for persistent data inside the backend container
PROMETHEUS_URL	http://prometheus:9090	Prometheus endpoint

Example with custom port:

ATLAS_HTTPS_PORT=8443 docker compose up -d

---

👥 User Management & Roles

Proxmox Atlas supports multiple users with role-based access control. Users are managed from the Settings tab (admin only).

Roles

Role	Dashboard	Topology	Alerts	Clusters	Settings	Users	Password
admin	✅ view	✅ view	✅ view	✅ add/remove	✅ edit	✅ create/delete/reset	✅ change any
editor	✅ view	✅ view	✅ view	✅ add/remove	✅ edit	❌	✅ self only
viewer	✅ view	✅ view	✅ view	👁 read-only	👁 read-only	❌	✅ self only
demo	✅ view	✅ view	✅ view	👁 read-only	👁 read-only	❌	❌

Key Behaviors

• First login: All users (except demo) must change their password on first login
• Demo users: Read-only access to everything, no password change allowed — ideal for public demos
• Admin protection: The admin account cannot be deleted
• Password reset: Only admins can reset other users' passwords (forces password change on next login)

---

🔐 SSL Certificates

Self-Signed (Default)

A self-signed certificate is automatically generated on first deploy. Browsers will show a security warning — this is expected and safe for internal/lab use.

Custom Certificate

To use your own SSL certificate (e.g., from Let's Encrypt or your corporate CA):

# Copy your certificate and private key
cp /path/to/your-cert.pem ./certs/atlas.crt
cp /path/to/your-key.pem  ./certs/atlas.key

# Restart Nginx to apply
docker compose restart nginx

Let's Encrypt (Certbot)

# Generate certificate with certbot
sudo certbot certonly --standalone -d atlas.example.com

# Copy to Atlas
sudo cp /etc/letsencrypt/live/atlas.example.com/fullchain.pem ./certs/atlas.crt
sudo cp /etc/letsencrypt/live/atlas.example.com/privkey.pem   ./certs/atlas.key

# Restart
docker compose restart nginx

Tip: Set up a cron job to auto-renew and copy certificates periodically.

---

🔄 Updating

cd ~/proxmox-atlas
git pull
docker compose up -d --build

Or use the installer:

cd ~/proxmox-atlas && ./install.sh --update

Your data (clusters, settings, credentials) is persisted in Docker volumes and will survive updates.

---

🛡️ Security

• HTTPS enforced — HTTP automatically redirects to HTTPS
• JWT authentication — All API endpoints require a valid Bearer token with embedded role
• Role-based access control — Four roles (admin, editor, viewer, demo) with granular permissions
• bcrypt passwords — All passwords are hashed with bcrypt (never stored in plaintext)
• No exposed internal services — Prometheus and backend are only accessible within the Docker network
• Security headers — HSTS, X-Frame-Options, X-Content-Type-Options, CSP
• Non-root containers — Backend runs as unprivileged atlas user

Proxmox API Tokens

For monitoring, Proxmox API tokens only need read-only permissions:

• PVEAuditor role is sufficient for full monitoring capabilities
• Never use root tokens in production

Security Notes

JWT Secret Lifecycle: The JWT signing secret is generated once on first deploy and persisted in auth.json on the atlas-data Docker volume. If this file is deleted or corrupted, all active sessions are invalidated and the admin password resets to admin. Back up the Docker volume to preserve sessions across restarts.

Multi-User Auth Migration: If upgrading from a single-user version, the old auth.json format is automatically migrated to the multi-user structure on startup. No manual intervention required.

SSE Token in URL: The Server-Sent Events endpoint uses a query parameter (/stream?token=...) for authentication because the browser EventSource API does not support custom HTTP headers. Nginx is configured to strip query parameters from access logs for this endpoint, but operators should be aware of this if adding custom log forwarding.

Password Change: After changing a password, a new JWT is issued. The old token remains valid until its natural expiration (24 hours). For immediate revocation, restart the backend container. If an admin changes a user's role, the change takes effect on the user's next login.

---

📊 Prometheus Integration

Atlas automatically exports metrics in Prometheus format and ships with a built-in Prometheus instance. Metrics are retained for 30 days by default.

Available metrics:

• proxmox_node_cpu_usage_ratio, proxmox_node_mem_*, proxmox_node_uptime_seconds
• proxmox_vm_cpu_usage_ratio, proxmox_vm_mem_*, proxmox_vm_disk_*, proxmox_vm_net_*
• proxmox_node_storage_total_bytes, proxmox_node_storage_used_bytes

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.