proxmox_manager/README.md

Proxmox Manager

Applicazione web per gestire macchine virtuali Proxmox VE con supporto multi-utente, backup, snapshot e DNS Cloudflare.

---

Prerequisiti

Prima di iniziare, assicurati di avere installato:

• Python 3.10+ — scarica qui
• MySQL o MariaDB — database relazionale
• Accesso a un'istanza Proxmox VE con API token configurato
• (Opzionale) Account Cloudflare con API token per la gestione DNS

---

Installazione passo per passo

1. Clona o scarica il progetto

# Se usi Git:
git clone https://git.gwserver.it/hersel/proxmox_manager.git
cd proxmox_manager

# Oppure estrai lo zip nella cartella desiderata

2. Crea un ambiente virtuale Python

# Windows
python -m venv venv
venv\Scripts\activate

# Linux / macOS
python3 -m venv venv
source venv/bin/activate

3. Installa le dipendenze

pip install -r requirements.txt

4. Configura le variabili d'ambiente

Copia il file di esempio e compila i tuoi dati:

# Windows
copy .env.example .env

# Linux / macOS
cp .env.example .env

Apri .env con un editor di testo e modifica questi campi:

# Chiave segreta Flask (cambiala con una stringa casuale lunga)
SECRET_KEY=cambia-questa-stringa-con-qualcosa-di-random

# Database MySQL/MariaDB
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=la-tua-password-mysql
DB_NAME=proxmox_manager

# Proxmox VE
PROXMOX_IP=192.168.1.100        # IP del tuo server Proxmox
PROXMOX_PORT=8006
API_TOKEN_ID=root@pam!mytoken   # ID del token API Proxmox
API_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# URL pubblico per l'accesso console (via reverse proxy)
PROXMOX_PUBLIC_URL=https://proxmox.tuodominio.it

# Impostazioni applicazione
MAX_BACKUPS_PER_USER=3
SESSION_TIMEOUT_MINUTES=60

# Cloudflare (opzionale, solo per gestione sottodomini DNS)
CLOUDFLARE_API_TOKEN=il-tuo-token-cloudflare
CLOUDFLARE_ZONE_ID=il-tuo-zone-id
CLOUDFLARE_DOMAIN=tuodominio.it

5. Crea il database

Esegui lo script Python che crea automaticamente l'intero database:

python create_database.py

Lo script creerà:

• Il database proxmox_manager
• Tutte le tabelle necessarie
• Un utente admin di default

Credenziali di default:

Utente	Password	Ruolo
admin	admin123	Amministratore
testuser	test123	Utente normale

IMPORTANTE: Cambia le password al primo accesso!

6. Avvia l'applicazione

python app.py

Apri il browser e vai su: http://localhost:5000

---

Come ottenere il Token API di Proxmox

1. Accedi alla tua interfaccia Proxmox (https://IP-PROXMOX:8006)
2. Vai in Datacenter → Permissions → API Tokens
3. Clicca Add e crea un token per l'utente root@pam
4. Copia il Token ID e il Token Secret
5. Incollali nel file .env:

   API_TOKEN_ID=root@pam!nome-del-token
   API_TOKEN_SECRET=il-secret-copiato
   

---

Come ottenere il Token API di Cloudflare (opzionale)

Solo se vuoi usare la funzione di gestione sottodomini DNS:

1. Accedi a dash.cloudflare.com
2. Vai su My Profile → API Tokens → Create Token
3. Scegli il template Edit zone DNS
4. Seleziona il tuo dominio e crea il token
5. Copia il token e incollalo nel .env
6. Per il Zone ID: torna sulla dashboard, seleziona il dominio → sidebar destra → Zone ID

---

Struttura del progetto

PROXMOX_FINAL/
├── app.py              # Applicazione principale Flask (route e logica)
├── models.py           # Modelli database (User, VM, Log, ecc.)
├── config.py           # Configurazione (legge .env)
├── create_database.py  # Script per creare il database
├── schema.sql          # Schema SQL (riferimento)
├── requirements.txt    # Dipendenze Python
├── .env.example        # Template configurazione
├── .env                # La tua configurazione (NON condividere!)
├── static/
│   └── css/            # Fogli di stile
└── templates/          # Pagine HTML (Jinja2)

---

Funzionalità principali

Funzionalità	Descrizione
Dashboard VM	Visualizza e gestisci le tue VM assegnate
Start / Stop / Reboot	Controlla lo stato delle VM
Snapshot	Crea e cancella snapshot (max 3 per utente)
Backup	Crea e gestisci backup (max configurabile)
Console	Accedi alla console della VM via browser
Sottodomini DNS	Crea/elimina record DNS su Cloudflare
IPAM	Gestione indirizzi IP delle VM
Pannello Admin	Gestione utenti, assegnazione VM, log audit
Topologia Cluster	Visualizzazione grafica del cluster Proxmox

---

Risoluzione problemi

Errore di connessione al database:

• Verifica che MySQL/MariaDB sia avviato
• Controlla le credenziali nel file .env
• Assicurati che l'utente MySQL abbia i permessi sul database

Errore di connessione a Proxmox:

• Verifica che l'IP di Proxmox sia raggiungibile
• Controlla che il token API sia valido e non scaduto
• L'applicazione ignora gli errori SSL (certificato self-signed Proxmox è normale)

Login non funziona con admin/admin123:

• Assicurati di aver eseguito python create_database.py
• Prova a eseguire nuovamente lo script, sovrascriverà i dati esistenti

La porta 5000 è già in uso:

• Su macOS la porta 5000 è occupata da AirPlay. Modifica in app.py la riga finale:

  app.run(host='0.0.0.0', port=5001, debug=True)
  

---

Note di sicurezza

• Non esporre l'applicazione su internet senza un reverse proxy (nginx/caddy) con HTTPS
• Cambia SECRET_KEY con una stringa casuale sicura
• Non committare mai il file .env su Git (è già in .gitignore)
• Cambia le password di default dopo il primo accesso