GazziNet - Contributi dell'utente [it]

Tips Varie

2026-04-06T22:07:36Z

Maintenance script: Aggiunto riferimento Ventoy nella sezione Tips_Varie

__NOTOC__
Breve raccolta di riferimenti trasversali usati nel contesto GazziNet. La pagina serve come indice rapido per contenuti non classificati altrove ma ancora utili operativamente.

== Risorse varie ==

=== Sicurezza, rete e certificati ===
* [[TIPS SSL]]
* [[RUSTDESK]]

=== Automazione e bot ===
* [[TIPS BOT]]

=== Streaming e contenuti ===
* [[TIPS TWITCH]]

=== Hardware e laboratorio ===
* [[INCISORE LASER]]

== Ventoy ==
'''Ventoy''' e' un tool open source per creare chiavette bootabili multi-ISO senza dover riscrivere la pendrive ogni volta.

Riferimenti:
* [[Ventoy]]: guida operativa completa con installazione, uso, Secure Boot, TreeView, boot da dischi locali, plugin e persistenza
* [https://www.gazzi.net/2026/04/07/ventoy-guida-pratica-creare-e-usare-una-chiavetta-bootabile-multi-iso/ Articolo WordPress su Ventoy]

== Note d'uso ==
* Usare questa pagina come indice temporaneo o trasversale, non come contenitore definitivo.
* Se un argomento cresce o diventa ricorrente, spostarlo in una sezione dedicata del wiki.
* Mantenere qui solo voci eterogenee che non appartengono chiaramente a Linux, Windows, Database, Container o Sicurezza.

Ventoy

2026-04-06T22:07:35Z

Maintenance script: Aggiunta guida Ventoy con uso pratico e funzioni avanzate

__NOTOC__
'''Ventoy''' e' uno strumento open source per creare supporti bootabili multi-immagine senza dover riscrivere la chiavetta ogni volta. Il principio operativo e' semplice: installi Ventoy una sola volta sul dispositivo, poi copi nella prima partizione i file immagine che vuoi avviare.

Pagina ufficiale:
* [https://www.ventoy.net/en/ Ventoy]
* [https://www.ventoy.net/en/doc_start.html Get Started]

== Cosa supporta ==
Ventoy puo' avviare direttamente file:
* <code>.iso</code>
* <code>.wim</code>
* <code>.img</code>
* <code>.vhd</code> / <code>.vhdx</code>
* <code>.efi</code>

Supporta in modo unificato:
* BIOS Legacy x86
* UEFI IA32
* UEFI x86_64
* UEFI ARM64
* UEFI MIPS64EL

Note utili:
* il supporto ufficiale evidenzia oltre 1300 image file testati
* la chiavetta puo' contenere piu' immagini contemporaneamente
* dopo l'installazione Ventoy la prima partizione puo' restare usata anche come normale spazio dati
* l'aggiornamento di Ventoy non rimuove i file gia' presenti nella prima partizione

== Flusso di utilizzo base ==
# scaricare il pacchetto dal sito ufficiale
# installare Ventoy sul dispositivo USB o altro supporto compatibile
# copiare nella prima partizione i file immagine da avviare
# fare boot dal dispositivo
# scegliere l'immagine dal menu Ventoy

Attenzione:
* durante l'installazione iniziale il dispositivo viene formattato
* verificare con molta attenzione il disco selezionato

== Installazione su Windows ==
Metodo grafico consigliato:
# scaricare l'archivio Windows di Ventoy
# estrarre il pacchetto
# eseguire <code>Ventoy2Disk.exe</code>
# selezionare il dispositivo corretto
# scegliere <code>Install</code> oppure <code>Update</code>

Note operative:
* per default il tool mostra solo dispositivi USB
* se abiliti la visualizzazione di tutti i dischi aumenta il rischio di scegliere il disco sbagliato
* la scelta <code>MBR</code> o <code>GPT</code> viene usata in fase di installazione, non di update
* dopo l'installazione puoi riformattare la prima partizione con <code>exFAT</code>, <code>FAT32</code>, <code>NTFS</code>, <code>UDF</code>, <code>XFS</code>, <code>Ext2/3/4</code> se necessario

== Installazione su Linux ==
=== Modalita CLI ===
Scarica il pacchetto Linux, estrailo e lancia come root:

<pre>
sh Ventoy2Disk.sh { -i | -I | -u } /dev/sdX
</pre>

Sintassi utile:
<pre>
Ventoy2Disk.sh CMD [ OPTION ] /dev/sdX

CMD:
-i installa Ventoy su sdX se non e' gia' presente
-I forza l'installazione
-u aggiorna Ventoy su sdX
-l mostra le informazioni Ventoy sul disco

OPTION:
-r SIZE_MB preserva spazio alla fine del disco durante l'installazione
-s abilita Secure Boot
-g usa schema GPT, altrimenti MBR
-L label della partizione principale
</pre>

Esempi:
<pre>
sudo sh Ventoy2Disk.sh -i /dev/sdb
sudo sh Ventoy2Disk.sh -i -g /dev/sdb
sudo sh Ventoy2Disk.sh -u /dev/sdb
</pre>

=== Modalita WebUI su Linux ===
Ventoy fornisce anche una GUI via browser, utile quando la macchina Linux non ha desktop locale.

Avvio:
<pre>
sudo bash VentoyWeb.sh
</pre>

Uso:
# aprire nel browser l'indirizzo mostrato dal comando, in genere <code>http://127.0.0.1:24680</code>
# per ascoltare su altro IP/porta usare ad esempio:

<pre>
sudo bash VentoyWeb.sh -H 192.168.0.100 -P 8080
</pre>

Note:
* di default la WebUI ascolta solo su localhost
* se esposta su altro IP puo' essere usata da un altro computer nella stessa rete o raggiungibile
* per chiudere la WebUI basta chiudere il browser e terminare il processo con <code>Ctrl+C</code>

== Copia delle immagini ==
Dopo l'installazione:
* la prima partizione e' quella usata per i file immagine
* puoi copiare i file ovunque, anche in sottodirectory
* Ventoy cerca ricorsivamente le immagini e le mostra nel menu in ordine alfabetico
* se vuoi limitare la scansione a directory specifiche puoi usare i plugin

Tip pratici:
* organizzare le ISO per cartelle aiuta molto quando il numero cresce
* con molte immagini conviene usare la modalita TreeView

== Modalita di navigazione e boot ==
=== List mode e TreeView ===
Per default Ventoy mostra una lista alfabetica di tutte le immagini trovate.

Se hai molte immagini:
* premi <code>F3</code> per entrare in TreeView
* in TreeView puoi navigare le directory reali
* usa <code>Enter</code> per entrare in una sottocartella
* usa <code>ESC</code> per tornare indietro
* se sei al livello top, <code>ESC</code> riporta alla vista lista

La modalita di default puo' essere cambiata anche via plugin di controllo globale.

=== Boot di file presenti su dischi locali ===
Ventoy supporta anche il browsing di file immagine presenti su altri dischi locali.

Uso rapido:
* premi <code>F2</code> nel menu principale
* naviga i dischi e scegli il file da avviare
* <code>ESC</code> torna al menu precedente

Note importanti:
* la funzione di browsing locale non usa tutti i plugin
* per compatibilita estesa con plugin, la documentazione Ventoy rimanda anche al meccanismo <code>vlnk</code>
* questa funzione e' comoda quando una ISO e' gia' su SSD/HDD e non vuoi copiarla sulla chiavetta

== Secure Boot ==
Ventoy supporta Secure Boot in UEFI.

Punti da ricordare:
* il supporto e' presente da tempo nella documentazione ufficiale
* l'opzione Secure Boot e' disponibile nel tool di installazione
* al primo avvio su una macchina con Secure Boot attivo puo' essere necessario completare una procedura di enrollment
* la procedura va fatta una sola volta per macchina

Comportamento pratico:
* se il sistema mostra la schermata prevista, seguire la procedura guidata per registrare chiave o hash
* se la macchina mostra errori o incompatibilita, la soluzione ufficiale puo' richiedere:
** reinstallare o aggiornare Ventoy senza supporto Secure Boot
** disattivare Secure Boot nel firmware

Riferimento:
* [https://www.ventoy.net/en/doc_secure.html About Secure Boot in UEFI mode]

== Plugin e personalizzazione ==
Ventoy permette di estendere il comportamento tramite una directory <code>/ventoy</code> nella prima partizione e un file <code>ventoy.json</code>.

Regole base:
* la directory <code>/ventoy</code> va creata manualmente nella root della prima partizione
* <code>ventoy.json</code> deve stare direttamente dentro <code>/ventoy</code>
* il file deve essere JSON valido, UTF-8 e con oggetto root <code>{ }</code>

Esempi di uso plugin:
* tema personalizzato
* alias di menu
* messaggi descrittivi
* auto installazione
* persistenza Linux
* protezione con password
* sostituzione di file di configurazione di boot

Per configurazioni piu' complesse:
* [https://www.ventoy.net/en/plugin.html Plugin]
* [https://www.ventoy.net/en/plugin_entry.html Plugin Entrypoint]

== Persistenza Linux ==
Ventoy supporta la persistenza per diverse live distro Linux senza imporre una partizione dedicata separata.

Concetto:
* si usa un file backend nella prima partizione
* il file viene associato alla ISO tramite configurazione JSON
* al boot Ventoy puo' usare il backend corretto o mostrare un menu di scelta

Esempio concettuale:
<pre>
{
"persistence": [
{
"image": "/ISO/ubuntu.iso",
"backend": "/persistence/ubuntu.dat"
}
]
}
</pre>

Note:
* distro diverse usano label differenti
* per alcune immagini servono opzioni aggiuntive specifiche
* la documentazione ufficiale elenca distro testate e formato del backend

Riferimento:
* [https://www.ventoy.net/en/plugin_persistence.html Ventoy Persistence Plugin]

== Quando ha senso usare Ventoy ==
Ventoy e' particolarmente utile se:
* vuoi una chiavetta multiuso con piu' installer e live image
* testi spesso distro Linux, strumenti rescue o installazioni Windows
* vuoi ridurre il tempo perso a riscrivere supporti USB
* vuoi organizzare immagini per cartelle e categorie
* vuoi mantenere una base comune ma con personalizzazioni tramite plugin

== Limiti e attenzioni ==
* l'installazione iniziale cancella il contenuto del dispositivo scelto
* non tutti i plugin valgono in tutte le modalita di browsing
* alcune macchine possono avere incompatibilita con Secure Boot
* prima di usare funzioni avanzate conviene verificare la documentazione ufficiale della singola feature

== Collegamenti utili ==
* [https://www.gazzi.net/2026/04/07/ventoy-guida-pratica-creare-e-usare-una-chiavetta-bootabile-multi-iso/ Articolo WordPress su Ventoy]
* [https://www.ventoy.net/en/ Ventoy official site]
* [https://www.ventoy.net/en/doc_start.html Start to use Ventoy]
* [https://www.ventoy.net/en/doc_linux_webui.html Linux GUI WebUI]
* [https://www.ventoy.net/en/doc_treeview.html TreeView Mode]
* [https://www.ventoy.net/en/doc_browser.html Browse/Boot Files In Local Disk]
* [https://www.ventoy.net/en/doc_vlnk.html Boot Ventoy Vlnk File]
* [https://www.ventoy.net/en/doc_secure.html Secure Boot]
* [https://www.ventoy.net/en/plugin.html Plugin]
* [https://www.ventoy.net/en/plugin_entry.html Plugin Entrypoint]
* [https://www.ventoy.net/en/plugin_persistence.html Persistence Plugin]

Tips Varie

2026-04-06T22:01:07Z

Maintenance script: Aggiunto riferimento Ventoy nella sezione Tips_Varie

__NOTOC__
Breve raccolta di riferimenti trasversali usati nel contesto GazziNet. La pagina serve come indice rapido per contenuti non classificati altrove ma ancora utili operativamente.

== Risorse varie ==

=== Sicurezza, rete e certificati ===
* [[TIPS SSL]]
* [[RUSTDESK]]

=== Automazione e bot ===
* [[TIPS BOT]]

=== Streaming e contenuti ===
* [[TIPS TWITCH]]

=== Hardware e laboratorio ===
* [[INCISORE LASER]]

== Ventoy ==
'''Ventoy''' e' un tool open source per creare chiavette bootabili multi-ISO senza dover riscrivere la pendrive ogni volta.

Riferimenti:
* [[Ventoy]]: guida operativa completa con installazione, uso, Secure Boot, TreeView, boot da dischi locali, plugin e persistenza
* [https://www.gazzi.net/2026/04/06/ventoy-guida-pratica-creare-e-usare-una-chiavetta-bootabile-multi-iso/ Articolo WordPress su Ventoy]

== Note d'uso ==
* Usare questa pagina come indice temporaneo o trasversale, non come contenitore definitivo.
* Se un argomento cresce o diventa ricorrente, spostarlo in una sezione dedicata del wiki.
* Mantenere qui solo voci eterogenee che non appartengono chiaramente a Linux, Windows, Database, Container o Sicurezza.

Ventoy

2026-04-06T22:01:06Z

Maintenance script: Aggiunta guida Ventoy con uso pratico e funzioni avanzate

__NOTOC__
'''Ventoy''' e' uno strumento open source per creare supporti bootabili multi-immagine senza dover riscrivere la chiavetta ogni volta. Il principio operativo e' semplice: installi Ventoy una sola volta sul dispositivo, poi copi nella prima partizione i file immagine che vuoi avviare.

Pagina ufficiale:
* [https://www.ventoy.net/en/ Ventoy]
* [https://www.ventoy.net/en/doc_start.html Get Started]

== Cosa supporta ==
Ventoy puo' avviare direttamente file:
* <code>.iso</code>
* <code>.wim</code>
* <code>.img</code>
* <code>.vhd</code> / <code>.vhdx</code>
* <code>.efi</code>

Supporta in modo unificato:
* BIOS Legacy x86
* UEFI IA32
* UEFI x86_64
* UEFI ARM64
* UEFI MIPS64EL

Note utili:
* il supporto ufficiale evidenzia oltre 1300 image file testati
* la chiavetta puo' contenere piu' immagini contemporaneamente
* dopo l'installazione Ventoy la prima partizione puo' restare usata anche come normale spazio dati
* l'aggiornamento di Ventoy non rimuove i file gia' presenti nella prima partizione

== Flusso di utilizzo base ==
# scaricare il pacchetto dal sito ufficiale
# installare Ventoy sul dispositivo USB o altro supporto compatibile
# copiare nella prima partizione i file immagine da avviare
# fare boot dal dispositivo
# scegliere l'immagine dal menu Ventoy

Attenzione:
* durante l'installazione iniziale il dispositivo viene formattato
* verificare con molta attenzione il disco selezionato

== Installazione su Windows ==
Metodo grafico consigliato:
# scaricare l'archivio Windows di Ventoy
# estrarre il pacchetto
# eseguire <code>Ventoy2Disk.exe</code>
# selezionare il dispositivo corretto
# scegliere <code>Install</code> oppure <code>Update</code>

Note operative:
* per default il tool mostra solo dispositivi USB
* se abiliti la visualizzazione di tutti i dischi aumenta il rischio di scegliere il disco sbagliato
* la scelta <code>MBR</code> o <code>GPT</code> viene usata in fase di installazione, non di update
* dopo l'installazione puoi riformattare la prima partizione con <code>exFAT</code>, <code>FAT32</code>, <code>NTFS</code>, <code>UDF</code>, <code>XFS</code>, <code>Ext2/3/4</code> se necessario

== Installazione su Linux ==
=== Modalita CLI ===
Scarica il pacchetto Linux, estrailo e lancia come root:

<pre>
sh Ventoy2Disk.sh { -i | -I | -u } /dev/sdX
</pre>

Sintassi utile:
<pre>
Ventoy2Disk.sh CMD [ OPTION ] /dev/sdX

CMD:
-i installa Ventoy su sdX se non e' gia' presente
-I forza l'installazione
-u aggiorna Ventoy su sdX
-l mostra le informazioni Ventoy sul disco

OPTION:
-r SIZE_MB preserva spazio alla fine del disco durante l'installazione
-s abilita Secure Boot
-g usa schema GPT, altrimenti MBR
-L label della partizione principale
</pre>

Esempi:
<pre>
sudo sh Ventoy2Disk.sh -i /dev/sdb
sudo sh Ventoy2Disk.sh -i -g /dev/sdb
sudo sh Ventoy2Disk.sh -u /dev/sdb
</pre>

=== Modalita WebUI su Linux ===
Ventoy fornisce anche una GUI via browser, utile quando la macchina Linux non ha desktop locale.

Avvio:
<pre>
sudo bash VentoyWeb.sh
</pre>

Uso:
# aprire nel browser l'indirizzo mostrato dal comando, in genere <code>http://127.0.0.1:24680</code>
# per ascoltare su altro IP/porta usare ad esempio:

<pre>
sudo bash VentoyWeb.sh -H 192.168.0.100 -P 8080
</pre>

Note:
* di default la WebUI ascolta solo su localhost
* se esposta su altro IP puo' essere usata da un altro computer nella stessa rete o raggiungibile
* per chiudere la WebUI basta chiudere il browser e terminare il processo con <code>Ctrl+C</code>

== Copia delle immagini ==
Dopo l'installazione:
* la prima partizione e' quella usata per i file immagine
* puoi copiare i file ovunque, anche in sottodirectory
* Ventoy cerca ricorsivamente le immagini e le mostra nel menu in ordine alfabetico
* se vuoi limitare la scansione a directory specifiche puoi usare i plugin

Tip pratici:
* organizzare le ISO per cartelle aiuta molto quando il numero cresce
* con molte immagini conviene usare la modalita TreeView

== Modalita di navigazione e boot ==
=== List mode e TreeView ===
Per default Ventoy mostra una lista alfabetica di tutte le immagini trovate.

Se hai molte immagini:
* premi <code>F3</code> per entrare in TreeView
* in TreeView puoi navigare le directory reali
* usa <code>Enter</code> per entrare in una sottocartella
* usa <code>ESC</code> per tornare indietro
* se sei al livello top, <code>ESC</code> riporta alla vista lista

La modalita di default puo' essere cambiata anche via plugin di controllo globale.

=== Boot di file presenti su dischi locali ===
Ventoy supporta anche il browsing di file immagine presenti su altri dischi locali.

Uso rapido:
* premi <code>F2</code> nel menu principale
* naviga i dischi e scegli il file da avviare
* <code>ESC</code> torna al menu precedente

Note importanti:
* la funzione di browsing locale non usa tutti i plugin
* per compatibilita estesa con plugin, la documentazione Ventoy rimanda anche al meccanismo <code>vlnk</code>
* questa funzione e' comoda quando una ISO e' gia' su SSD/HDD e non vuoi copiarla sulla chiavetta

== Secure Boot ==
Ventoy supporta Secure Boot in UEFI.

Punti da ricordare:
* il supporto e' presente da tempo nella documentazione ufficiale
* l'opzione Secure Boot e' disponibile nel tool di installazione
* al primo avvio su una macchina con Secure Boot attivo puo' essere necessario completare una procedura di enrollment
* la procedura va fatta una sola volta per macchina

Comportamento pratico:
* se il sistema mostra la schermata prevista, seguire la procedura guidata per registrare chiave o hash
* se la macchina mostra errori o incompatibilita, la soluzione ufficiale puo' richiedere:
** reinstallare o aggiornare Ventoy senza supporto Secure Boot
** disattivare Secure Boot nel firmware

Riferimento:
* [https://www.ventoy.net/en/doc_secure.html About Secure Boot in UEFI mode]

== Plugin e personalizzazione ==
Ventoy permette di estendere il comportamento tramite una directory <code>/ventoy</code> nella prima partizione e un file <code>ventoy.json</code>.

Regole base:
* la directory <code>/ventoy</code> va creata manualmente nella root della prima partizione
* <code>ventoy.json</code> deve stare direttamente dentro <code>/ventoy</code>
* il file deve essere JSON valido, UTF-8 e con oggetto root <code>{ }</code>

Esempi di uso plugin:
* tema personalizzato
* alias di menu
* messaggi descrittivi
* auto installazione
* persistenza Linux
* protezione con password
* sostituzione di file di configurazione di boot

Per configurazioni piu' complesse:
* [https://www.ventoy.net/en/plugin.html Plugin]
* [https://www.ventoy.net/en/plugin_entry.html Plugin Entrypoint]

== Persistenza Linux ==
Ventoy supporta la persistenza per diverse live distro Linux senza imporre una partizione dedicata separata.

Concetto:
* si usa un file backend nella prima partizione
* il file viene associato alla ISO tramite configurazione JSON
* al boot Ventoy puo' usare il backend corretto o mostrare un menu di scelta

Esempio concettuale:
<pre>
{
"persistence": [
{
"image": "/ISO/ubuntu.iso",
"backend": "/persistence/ubuntu.dat"
}
]
}
</pre>

Note:
* distro diverse usano label differenti
* per alcune immagini servono opzioni aggiuntive specifiche
* la documentazione ufficiale elenca distro testate e formato del backend

Riferimento:
* [https://www.ventoy.net/en/plugin_persistence.html Ventoy Persistence Plugin]

== Quando ha senso usare Ventoy ==
Ventoy e' particolarmente utile se:
* vuoi una chiavetta multiuso con piu' installer e live image
* testi spesso distro Linux, strumenti rescue o installazioni Windows
* vuoi ridurre il tempo perso a riscrivere supporti USB
* vuoi organizzare immagini per cartelle e categorie
* vuoi mantenere una base comune ma con personalizzazioni tramite plugin

== Limiti e attenzioni ==
* l'installazione iniziale cancella il contenuto del dispositivo scelto
* non tutti i plugin valgono in tutte le modalita di browsing
* alcune macchine possono avere incompatibilita con Secure Boot
* prima di usare funzioni avanzate conviene verificare la documentazione ufficiale della singola feature

== Collegamenti utili ==
* [https://www.gazzi.net/2026/04/06/ventoy-guida-pratica-creare-e-usare-una-chiavetta-bootabile-multi-iso/ Articolo WordPress su Ventoy]
* [https://www.ventoy.net/en/ Ventoy official site]
* [https://www.ventoy.net/en/doc_start.html Start to use Ventoy]
* [https://www.ventoy.net/en/doc_linux_webui.html Linux GUI WebUI]
* [https://www.ventoy.net/en/doc_treeview.html TreeView Mode]
* [https://www.ventoy.net/en/doc_browser.html Browse/Boot Files In Local Disk]
* [https://www.ventoy.net/en/doc_vlnk.html Boot Ventoy Vlnk File]
* [https://www.ventoy.net/en/doc_secure.html Secure Boot]
* [https://www.ventoy.net/en/plugin.html Plugin]
* [https://www.ventoy.net/en/plugin_entry.html Plugin Entrypoint]
* [https://www.ventoy.net/en/plugin_persistence.html Persistence Plugin]

Codex per struttura wiki e pubblicazione articoli

2026-03-30T23:25:13Z

Maintenance script: Aggiunto richiamo a CartClin sotto Codex per struttura wiki e pubblicazione articoli

__NOTOC__
= Codex per struttura wiki e pubblicazione articoli =

Questa pagina documenta in modo pratico come il sistema Codex e stato usato per riorganizzare il wiki GazziNet e per supportare la generazione e pubblicazione di articoli sul sito WordPress.

== Contesto d'uso ==
Il sistema e stato usato come agente operativo, non come semplice generatore di testo. Nel lavoro svolto ha avuto tre ruoli principali:

* riorganizzazione del wiki MediaWiki
* supporto alla produzione di articoli tecnici e news sul sito
* automazione di task ripetitivi su tema, struttura, contenuti e pubblicazione

== Come e stato usato sul wiki ==
Sul wiki l'uso principale e stato editoriale e strutturale. In pratica il flusso e stato questo:

# lettura delle pagine esistenti
# verifica del contenuto attuale e del markup reale servito dal sito
# riorganizzazione in sezioni piu leggibili
# normalizzazione di titoli, indici e pagine "Tips"
# correzione di nomi errati, redirect e link interni
# aggiornamento del CSS globale MediaWiki quando necessario per allineare il layout al sito principale

Esempi pratici di attivita fatte:
* pulizia e reimpaginazione della home del wiki
* revisione di pagine come ''Tips Linux'', ''Tips Windows'', ''Tips Database'', ''Tips Application Server'', ''Tips Virtualizzatori''
* correzione della pagina ''Conteiner'' in ''Container'' con redirect esplicito
* miglioramento della documentazione hardware della workstation locale
* ripristino dei controlli di editing quando erano stati nascosti dal CSS

== Come e stato usato per gli articoli ==
Sul sito WordPress Codex e stato usato per:

* generare articoli tecnici in stile coerente con la sezione ''GenDaIa''
* migliorare titoli, excerpt e struttura SEO dei post esistenti
* pubblicare nuovi articoli con categoria corretta
* uniformare template, tipografia e layout tra home, hub e singoli articoli

Il sistema e stato usato sia in modalita manuale che in modalita assistita. In pratica:
* su richiesta venivano creati nuovi articoli
* i testi venivano adattati al taglio tecnico o divulgativo richiesto
* i contenuti venivano poi pubblicati o corretti direttamente via WordPress

== Flusso operativo tipico ==
Un flusso tipico di lavoro con Codex, in questo contesto, e stato:

# richiesta dell'obiettivo
# analisi del contesto reale del sito o del wiki
# lettura dei file o del markup pubblico
# proposta implicita della modifica tramite esecuzione operativa
# verifica del risultato sul frontend o tramite API
# eventuale rifinitura successiva

Questo approccio e stato utile soprattutto quando il problema non era solo nel contenuto, ma nella combinazione di:
* struttura pagina
* stile
* template
* automazione
* pubblicazione

== Dev e piattaforme ==
Tra i progetti documentati in questa area rientra anche:

* [[Progetti/CartClin]]

La pagina del progetto raccoglie la configurazione di pubblicazione di:

* runtime applicativo su web01
* backend Nginx locale
* reverse proxy pubblico su proxy01
* certificato TLS Let's Encrypt per <code>cartclin.gazzi.net</code>

== Integrazione tra Codex, ChatGPT e IA locale ==
Nel lavoro pratico questi tre livelli possono convivere, ma non hanno lo stesso ruolo.

=== Codex ===
Codex viene usato come agente operativo: legge il contesto, controlla file, verifica pagine, modifica contenuti, esegue comandi e aggiorna strutture reali del sito o del wiki.

=== ChatGPT ===
ChatGPT e utile soprattutto come interfaccia conversazionale generale: brainstorming, chiarimenti, riscrittura, sintesi, definizione dell'obiettivo o raffinamento di una richiesta prima dell'esecuzione operativa.

=== IA locale ===
Una IA locale, per esempio tramite Ollama, e utile quando si vuole:
* generare contenuti senza dipendere da un servizio esterno
* fare test rapidi su prompt, classificazione o riscrittura
* mantenere alcuni flussi in ambiente locale
* ridurre costi ricorrenti per task ripetitivi o batch

=== Integrazione pratica ===
Nel contesto GazziNet l'integrazione puo essere vista cosi:
* ChatGPT o interfaccia simile per definire l'obiettivo o iterare sulla richiesta
* Codex per eseguire il lavoro concreto su file, WordPress, MediaWiki e struttura del sistema
* IA locale per automazioni editoriali, generazione assistita o test di pipeline locali

=== Esempio concreto ===
Un flusso concreto puo essere:
# scegliere un tema o una richiesta editoriale
# usare un modello locale per produrre una prima bozza
# usare Codex per controllare struttura, compatibilita, pubblicazione e verifica finale
# usare ChatGPT per rifinire tono, taglio o spiegazione quando serve un passaggio piu discorsivo

=== Vantaggio dell'approccio ibrido ===
L'aspetto interessante non e scegliere un solo sistema, ma usare ogni componente per il compito giusto:
* conversazione e ideazione
* esecuzione tecnica
* generazione locale o automatizzata

== Vantaggi pratici osservati ==
* riduzione del lavoro manuale ripetitivo
* maggiore uniformita tra pagine e sezioni diverse
* velocita nel passare da richiesta a modifica reale
* facilita nel documentare sistemi, procedure e note operative
* supporto concreto alla produzione di articoli e alla manutenzione del sito

== Limiti da tenere presenti ==
* i contenuti generati vanno sempre riletti se riguardano temi sensibili o decisioni operative
* la qualita finale dipende molto dalla precisione delle richieste iniziali
* per automazioni editoriali o pubblicazione automatica servono comunque controlli su credenziali, permessi e qualita del testo
* per temi tecnici complessi resta importante la validazione umana

== Uso sul sito GazziNet ==
Nel contesto GazziNet il sistema e stato quindi usato come supporto tecnico-editoriale per:
* rifare la struttura del wiki
* migliorare la coerenza tra le pagine
* pubblicare articoli tecnici sul sito
* preparare automazioni per la generazione di news e articoli
* documentare il sistema locale, i componenti hardware e le piattaforme usate

== Nota finale ==
Il valore pratico del sistema non sta nel "scrivere da solo", ma nel combinare analisi del contesto, modifica concreta, verifica e documentazione in un unico flusso di lavoro.

Pagina principale

2026-03-30T23:25:12Z

Maintenance script: Aggiunto link CartClin nella sezione Dev e piattaforme della home wiki

__NOTOC__
<div class="gazzi-wiki-home">
<div class="gazzi-wiki-hero">
<h2>GazziNet Wiki</h2>
<p>Base tecnica interna con appunti operativi, procedure e raccolte tematiche.</p>
</div>

<div class="gazzi-wiki-grid">
<div class="gazzi-wiki-card">
<h3>Sistemi</h3>
<ul>
<li>[[Tips Linux]]</li>
<li>[[Tips Windows]]</li>
<li>[[Tips Database]]</li>
<li>[[Tips Application Server]]</li>
<li>[[Tips Virtualizzatori]]</li>
<li>[[Tips Automation]]</li>
<li>[[Tips Varie]]</li>
</ul>
</div>

<div class="gazzi-wiki-card">
<h3>Rete e sicurezza</h3>
<ul>
<li>[[Sicurezza & Forense]]</li>
<li>[[Operatore]]</li>
</ul>
</div>

<div class="gazzi-wiki-card">
<h3>Dev e piattaforme</h3>
<ul>
<li>[[Container|Container]]</li>
<li>[[Sviluppo]]</li>
<li>[[OBS]]</li>
<li>[[HW]]</li>
<li>[[Codex per struttura wiki e pubblicazione articoli]]</li>
<li>[[Progetti/CartClin]]</li>
</ul>
</div>

<div class="gazzi-wiki-card">
<h3>Supporto</h3>
<ul>
<li>[[Corso]]</li>
</ul>
</div>
</div>
</div>

Progetti/CartClin

2026-03-30T23:09:58Z

Maintenance script: Aggiunta documentazione progetto CartClin e pubblicazione cartclin.gazzi.net

== CartClin ==

'''CartClin''' e' un'applicazione web Python/Flask pubblicata dietro reverse proxy come:

* URL pubblico: <code>https://cartclin.gazzi.net/</code>
* host applicativo: <code>web01.gazzi.local</code>
* host proxy pubblico: <code>proxy01.gazzi.local</code>

== Architettura ==

La pubblicazione e' divisa in tre livelli:

* '''runtime applicativo''' su <code>web01</code>
* '''backend HTTP interno''' su <code>web01</code>
* '''reverse proxy e TLS''' su <code>proxy01</code>

=== Runtime applicativo su web01 ===

Il codice applicativo viene installato in:

* <code>/opt/cartclin</code>

Componenti principali runtime:

* virtualenv Python: <code>/opt/cartclin/venv</code>
* database SQLite locale: <code>/opt/cartclin/cartclin.db</code>
* cache locale per WeasyPrint/fontconfig: <code>/opt/cartclin/.cache</code>

Il servizio applicativo e' gestito da systemd:

* unit file: <code>/etc/systemd/system/cartclin.service</code>
* service name: <code>cartclin.service</code>
* utente runtime: <code>www-data</code>
* working directory: <code>/opt</code>
* variabili runtime rilevanti:
** <code>PYTHONPATH=/opt</code>
** <code>HOME=/opt/cartclin</code>
** <code>XDG_CACHE_HOME=/opt/cartclin/.cache</code>

Il servizio avvia:

* <code>gunicorn --workers 2 --bind 127.0.0.1:8090 cartclin.app:app</code>

=== Backend HTTP interno su web01 ===

Nginx locale su <code>web01</code> pubblica l'app su una porta interna dedicata:

* vhost backend: <code>/etc/nginx/sites-available/cartclin-backend</code>
* symlink attivo: <code>/etc/nginx/sites-enabled/cartclin-backend</code>
* bind interno: <code>0.0.0.0:8082</code>
* upstream applicativo: <code>http://127.0.0.1:8090</code>

Test locale atteso su <code>web01</code>:

* <code>http://127.0.0.1:8090/</code> risponde con redirect a <code>/login</code>
* <code>http://127.0.0.1:8082/</code> risponde come proxy locale verso l'app

=== Reverse proxy e TLS su proxy01 ===

La pubblicazione pubblica e' gestita da <code>proxy01</code>:

* vhost: <code>/etc/nginx/sites-available/cartclin</code>
* symlink attivo: <code>/etc/nginx/sites-enabled/cartclin</code>
* host pubblico: <code>cartclin.gazzi.net</code>
* upstream interno: <code>http://172.16.1.3:8082</code>

Comportamento del vhost:

* su porta 80 esegue redirect verso HTTPS
* su porta 443 termina TLS e inoltra verso <code>web01:8082</code>

== Certificato TLS ==

Il certificato pubblico e' gestito con Let's Encrypt su <code>proxy01</code>:

* certificate path: <code>/etc/letsencrypt/live/cartclin.gazzi.net/fullchain.pem</code>
* private key path: <code>/etc/letsencrypt/live/cartclin.gazzi.net/privkey.pem</code>
* rinnovo automatico: gestito da Certbot

== Flusso richieste ==

Percorso sintetico di una richiesta:

# il client apre <code>https://cartclin.gazzi.net/</code>
# <code>proxy01</code> riceve TLS e inoltra verso <code>http://172.16.1.3:8082</code>
# <code>web01</code> inoltra verso <code>gunicorn</code> su <code>127.0.0.1:8090</code>
# l'app Flask serve la login page o le route applicative

== Verifiche rapide ==

Su <code>web01</code>:

* <code>systemctl status cartclin.service</code>
* <code>curl -I http://127.0.0.1:8090/</code>
* <code>curl -I -H 'Host: web01.gazzi.local' http://127.0.0.1:8082/</code>

Su <code>proxy01</code>:

* <code>nginx -t</code>
* <code>curl -I --resolve cartclin.gazzi.net:443:127.0.0.1 https://cartclin.gazzi.net/ -k</code>
* <code>certbot certificates</code>

== Note operative ==

* Non versionare segreti o password nel repository.
* Il file SQLite fa parte del runtime applicativo e va trattato come dato operativo, non come configurazione di proxy.
* Se si cambia host o porta interna, aggiornare sia il backend Nginx su <code>web01</code> sia il reverse proxy su <code>proxy01</code>.

Sezione

2026-03-29T20:07:24Z

Maintenance script: Espansione

__NOTOC__
Breve raccolta di riferimenti sulla virtualizzazione usati nel contesto GazziNet. La pagina serve come indice rapido per verifiche host, risorse e accesso alle piattaforme dedicate.

== Verifiche rapide ==

=== Risorse host ===
<pre>
uptime
lscpu
free -h
df -h
</pre>

=== Rete e bridge ===
<pre>
ip a
ip r
bridge link
ss -tulpn
</pre>

=== Storage e volumi ===
<pre>
lsblk
pvs
vgs
lvs
</pre>

== Troubleshooting operativo ==
* Verificare sempre se il problema e sull'host, sulla VM o sullo storage sottostante.
* Prima di agire, annotare uso CPU, RAM, spazio, stato rete e saturazione I/O.
* Controllare eventuali snapshot, lock, backup in corso o contenitori storage pieni.

== Piattaforme ==
* [[PROXMOX]]

== Proxmox VE ==

'''Proxmox VE''' e una piattaforma di virtualizzazione basata su Debian che integra:
* '''KVM''' per macchine virtuali complete
* '''LXC''' per container Linux
* gestione storage locale e condiviso
* clustering, migrazione, backup e replica
* interfaccia web e CLI native

=== Quando usarlo ===
Ha senso usare Proxmox VE quando:
* vuoi centralizzare gestione di VM e container
* ti servono snapshot, backup e restore in modo semplice
* vuoi crescere da host singolo a cluster
* vuoi usare storage locali o condivisi con un'interfaccia unificata

=== Requisiti minimi e logica di sizing ===
Per valutazione o lab:
* CPU 64 bit con supporto Intel VT/AMD-V
* almeno 16 GiB di spazio disco per l'host, oltre allo spazio per guest
* almeno una NIC

Per produzione:
* privilegiare hardware server stabile
* prevedere RAM in base ai guest, non solo all'host
* separare se possibile traffico management, storage e migration
* valutare ECC RAM soprattutto se si usa ZFS

== Installazione ==

=== Metodo consigliato: ISO ufficiale ===
L'installazione da ISO e il metodo raccomandato da Proxmox per utenti nuovi ed esistenti.

Flusso tipico:
# scaricare la ISO ufficiale
# preparare la chiavetta di installazione
# avviare il server dalla ISO
# scegliere il disco o i dischi di destinazione
# impostare filesystem/root storage
# configurare hostname, password root, email e rete
# completare installazione e riavviare

Durante il setup l'installer:
* partiziona i dischi locali
* applica configurazioni base come lingua, timezone e rete
* installa Debian e i pacchetti Proxmox VE necessari

=== Metodo alternativo: installazione su Debian ===
Proxmox VE puo anche essere installato sopra un sistema Debian esistente, ma questa via e consigliata solo a utenti avanzati.

Ha senso usarla quando:
* hai gia un'immagine Debian standard gestita da automazione
* vuoi maggiore controllo iniziale sul partizionamento
* vuoi integrare l'host in procedure di bootstrap gia esistenti

Rischi tipici:
* repository sbagliati o incompleti
* pacchetti non allineati
* rete e storage meno prevedibili rispetto all'installer dedicato

=== Installazione automatizzata ===
Proxmox documenta anche l''''Automated Installation''' per deployment unattended.

Serve quando:
* devi installare piu host bare metal in modo coerente
* vuoi preparare una ISO con answer file
* vuoi demandare il post-config a strumenti come Ansible o simili

=== Prime attivita dopo l'installazione ===
Checklist pratica iniziale:
* verificare data/ora e DNS
* applicare aggiornamenti
* controllare bridge di rete
* controllare storage locale configurato dall'installer
* definire repository corretti in base a subscription o no-subscription
* configurare backup prima di creare guest critici
* registrare hostname, IP management, storage e note operative

Comandi rapidi:
<syntaxhighlight lang="bash">
pveversion -v
ip a
bridge link
pvesm status
lsblk
</syntaxhighlight>

== Filesystem e storage: come scegliere ==

La scelta corretta dipende da:
* host singolo o cluster
* storage locale o condiviso
* bisogno di snapshot/cloni
* budget RAM
* necessita di integrita dati e replica
* carico prevalente: VM, container, ISO, template, backup

=== 1. Setup predefinito LVM + LVM-thin ===
L'installer attuale usa come default '''LVM''' sul disco locale.

Schema tipico:
* volume group <code>pve</code>
* logical volume <code>root</code> formattato '''ext4''' per il sistema operativo
* logical volume <code>swap</code>
* logical volume <code>data</code> come '''LVM-thin''' per dischi VM

Vantaggi:
* semplice
* buon default per host singolo
* snapshot e clone efficienti sul thin pool
* basso overhead RAM rispetto a ZFS

Limiti:
* non condiviso tra nodi
* meno funzioni di integrita rispetto a ZFS
* meno flessibile per storage file-level generici rispetto a una directory dedicata

Consigli pratici:
* buona scelta per host piccoli o medi con storage locale
* adatto quando vuoi partire in fretta senza complessita extra
* tenere backup e ISO possibilmente separati dal thin pool se il disco e piccolo

=== 2. Directory storage su ext4 o XFS ===
Lo storage di tipo '''Directory''' usa una directory POSIX su filesystem Linux standard.

Puoi usarlo per:
* immagini VM
* container
* template
* ISO
* backup

Proxmox segnala che:
* una directory puo essere locale oppure un mount standard Linux
* il backend assume compatibilita POSIX
* non offre snapshot a livello storage
* con immagini <code>qcow2</code> esiste il workaround degli snapshot interni al formato

Quando scegliere '''ext4''':
* vuoi il filesystem piu semplice e prevedibile
* l'uso principale e backup, ISO, template o immagini non troppo complesse
* vuoi massima familiarita operativa

Quando scegliere '''XFS''':
* vuoi un filesystem robusto per grandi volumi file-based
* prevedi repository backup o directory storage di grandi dimensioni
* preferisci una soluzione nota per throughput e gestione file grandi

Limite importante:
* se il tuo obiettivo principale sono snapshot e cloni storage-level delle VM, una directory pura non e la scelta migliore

Regola pratica:
* '''ext4/XFS + dir''' vanno molto bene per ISO, template e backup
* per i dischi VM principali, usare spesso '''LVM-thin''' o '''ZFS''' e piu coerente

=== 3. ZFS ===
ZFS combina filesystem e volume manager.

Proxmox ne evidenzia vantaggi importanti:
* protezione da corruzione dati
* compressione
* snapshot
* cloni copy-on-write
* vari livelli RAID
* self-healing
* integrity checking continua
* replica asincrona
* gestione integrata da GUI e CLI

Quando scegliere ZFS:
* vuoi integrita dati e checksum end-to-end
* vuoi snapshot e replica native
* hai abbastanza RAM
* puoi dare a ZFS accesso diretto ai dischi

Attenzioni fondamentali:
* Proxmox raccomanda almeno '''8 GB''' di RAM per iniziare
* e raccomandata '''ECC RAM''' quando possibile
* non usare ZFS sopra controller RAID hardware con cache propria
* meglio HBA o controller in modalita IT

Nota pratica importante:
* nelle installazioni nuove da Proxmox VE 8.1 il limite ARC viene impostato al '''10%''' della RAM fisica, con massimo '''16 GiB''', scritto in <code>/etc/modprobe.d/zfs.conf</code>

Scelte RAID ZFS in installazione:
* '''RAID0''': massima capacita, nessuna ridondanza
* '''RAID1''': mirror, adatto a 2 dischi
* '''RAID10''': buone prestazioni e ridondanza, richiede almeno 4 dischi
* '''RAIDZ-1''': parita singola
* '''RAIDZ-2''': parita doppia
* '''RAIDZ-3''': parita tripla

Consiglio operativo:
* per host piccoli con 2 dischi, il mirror ZFS e spesso la scelta piu pulita
* per host con tanti dischi, RAID10 o RAIDZ-2 sono in genere piu prudenziali di RAIDZ-1
* evitare ZFS se la RAM e molto limitata o se l'hardware e gia vincolato a RAID hardware non bypassabile

=== 4. BTRFS ===
BTRFS esiste nel mondo Linux come filesystem moderno con snapshot e checksum, ma in Proxmox la documentazione e la pratica operativa ruotano molto di piu attorno a '''LVM-thin''' e '''ZFS'''.

Consiglio pragmatico:
* se ti serve una scelta stabile e ben coperta dalla documentazione Proxmox, privilegia '''LVM-thin''' o '''ZFS'''
* usa BTRFS solo se hai gia competenza specifica e una ragione forte per adottarlo

== Raccomandazioni rapide ==

=== Host singolo piccolo o homelab semplice ===
Scelta consigliata:
* installer ISO
* default '''LVM + ext4 root + LVM-thin'''
* directory separata per ISO e backup se possibile

=== Host singolo con priorita a integrita e snapshot ===
Scelta consigliata:
* installer ISO con '''ZFS mirror''' se hai 2 dischi
* ECC RAM se possibile
* niente RAID hardware davanti a ZFS

=== Nodo dedicato soprattutto a backup ===
Scelta consigliata:
* directory storage su '''ext4''' o '''XFS'''
* evitare di mescolare senza controllo backup pesanti e dischi VM critici sullo stesso spazio piccolo

=== Cluster o crescita futura ===
Considerare fin da subito:
* separazione rete management/storage
* strategia storage condiviso o replica
* naming coerente di nodi, bridge e datastore
* policy di backup e restore testato

== Errori comuni ==
* usare ZFS sopra RAID hardware opaco
* sottostimare la RAM necessaria a host e guest
* riempire lo storage locale con backup, ISO e template fino a saturazione
* scegliere directory storage pensando di avere snapshot storage-level nativi
* non documentare bridge, VLAN, datastore e layout dischi
* creare VM critiche prima di aver validato backup e ripristino

== Verifiche utili su host Proxmox ==

=== Versione e stato generale ===
<syntaxhighlight lang="bash">
pveversion -v
uptime
</syntaxhighlight>

=== Rete ===
<syntaxhighlight lang="bash">
ip a
ip r
bridge link
</syntaxhighlight>

=== Storage LVM ===
<syntaxhighlight lang="bash">
lsblk
pvs
vgs
lvs
</syntaxhighlight>

=== Storage Proxmox ===
<syntaxhighlight lang="bash">
pvesm status
cat /etc/pve/storage.cfg
</syntaxhighlight>

=== ZFS ===
<syntaxhighlight lang="bash">
zpool status
zfs list
</syntaxhighlight>

== Fonti ufficiali ==
* [https://pve.proxmox.com/pve-docs-8/chapter-pve-installation.html Installing Proxmox VE]
* [https://pve.proxmox.com/wiki/Quick_installation Quick installation]
* [https://pve.proxmox.com/wiki/Automated_Installation Automated Installation]
* [https://pve.proxmox.com/wiki/Logical_Volume_Manager_%28LVM%29 Logical Volume Manager (LVM)]
* [https://pve.proxmox.com/wiki/Storage Storage]
* [https://pve.proxmox.com/wiki/Storage%3A_Directory Storage: Directory]
* [https://pve.proxmox.com/wiki/ZFS_on_Linux ZFS on Linux]
* [https://pve.proxmox.com/wiki/Installation%3A_Tips_and_Tricks Installation: Tips and Tricks]

== Note d'uso ==
* Separare sempre i problemi di orchestrazione da quelli di singola VM.
* Non saturare lo storage locale con immagini, backup e template senza controllo dello spazio.
* Documentare hostname host, datastore coinvolto e VM interessata prima di aprire ticket o incidente.

Esempi Pyinfra

2026-03-29T19:21:07Z

Maintenance script: Aggiunta

= Esempi Pyinfra =

Questa pagina raccoglie esempi leggibili e progressivi: si parte dal minimo indispensabile e si arriva a pattern piu vicini a un uso reale.

== Prima idea da fissare ==
Un progetto pyinfra semplice ha di solito almeno due file:
<pre>
inventory.py
deploy.py
</pre>

L'inventory descrive i target. Il deploy descrive cosa fare.

== Esempio base 1: esecuzione su host locali ==
Se vuoi solo capire la CLI:
<pre>
pyinfra @local exec -- echo "hello world"
</pre>

Questo serve quando vuoi verificare:
* che pyinfra sia installato
* che il runner funzioni
* che l'output arrivi correttamente

Tradotto in pratica:
* se il comando parte, sai che <code>pyinfra</code> esiste davvero sul manager
* se l'operation viene eseguita, sai che il runner locale funziona
* se vedi <code>hello world</code>, sai che l'output viene raccolto correttamente

== Esempio concreto: devo controllare 10 server ==
Questo e uno dei casi piu utili per capire bene come ragiona pyinfra.

Scenario:
* hai una macchina '''manager'''
* da quella macchina vuoi controllare o configurare '''10 server target'''

=== Cosa deve esserci sul manager ===
Sul manager devono esserci:
* <code>Python</code>
* <code>pyinfra</code>
* i file di progetto, ad esempio <code>inventory.py</code> e <code>deploy.py</code>
* connettivita SSH verso i 10 server
* chiavi SSH oppure credenziali adatte
* eventuali permessi <code>sudo</code> se il deploy deve fare operazioni amministrative

In sintesi:
* il manager e la macchina da cui lanci i comandi
* il manager contiene la logica
* il manager non deve essere per forza uno dei 10 server target

=== Cosa deve esserci sui 10 server target ===
In generale pyinfra e '''agentless''', quindi non richiede un agente pyinfra installato sui target.

Di solito sui target servono:
* accesso SSH dal manager
* un utente valido con cui entrare
* eventuale <code>sudo</code> se devi amministrare il sistema
* shell e strumenti di base coerenti con quello che vuoi eseguire

In pratica:
* sui target '''non installi pyinfra'''
* sui target devi rendere possibile l'accesso e l'esecuzione delle operazioni richieste

=== Riepilogo semplice ===
* manager: installi pyinfra
* target: non installi pyinfra
* manager -> target: usi SSH

== Esempio con 10 server ==
Inventory minimale:
<pre>
all_servers = [
"srv01.example.net",
"srv02.example.net",
"srv03.example.net",
"srv04.example.net",
"srv05.example.net",
"srv06.example.net",
"srv07.example.net",
"srv08.example.net",
"srv09.example.net",
"srv10.example.net",
]
</pre>

Se vuoi dividere per gruppi:
<pre>
web_servers = [
"srv01.example.net",
"srv02.example.net",
"srv03.example.net",
"srv04.example.net",
"srv05.example.net",
]

db_servers = [
"srv06.example.net",
"srv07.example.net",
]

misc_servers = [
"srv08.example.net",
"srv09.example.net",
"srv10.example.net",
]
</pre>

== Primo test vero sui 10 server ==
Prima di fare configurazione, conviene fare un controllo innocuo.

Deploy:
<pre>
from pyinfra.operations import server

server.shell(
name="Show hostname and uptime",
commands=[
"hostname",
"uptime",
],
)
</pre>

Esecuzione dal manager:
<pre>
pyinfra inventory.py deploy.py
</pre>

Questo test serve a verificare:
* che il manager raggiunga tutti i target
* che l'utente SSH funzioni
* che pyinfra riesca a eseguire comandi su tutti i server
* che i risultati siano leggibili nell'output

== Esempio di controllo piu utile ==
Se vuoi controllare disco e un servizio:
<pre>
from pyinfra.operations import server

server.shell(
name="Check disk",
commands=["df -h /"],
)

server.shell(
name="Check nginx service",
commands=["systemctl is-active nginx || true"],
)
</pre>

Questo non modifica nulla, ma ti da gia una fotografia dei 10 server.

== Esempio di deploy reale ==
Se vuoi installare <code>vim</code> e assicurarti che <code>nginx</code> sia attivo:
<pre>
from pyinfra.operations import apt, systemd

apt.packages(
name="Install vim",
packages=["vim"],
update=True,
)

systemd.service(
name="Ensure nginx is running",
service="nginx",
running=True,
enabled=True,
)
</pre>

In questo caso:
* sul manager hai solo pyinfra e i file del deploy
* sui target non hai pyinfra, ma hai accesso SSH e permessi adeguati
* pyinfra esegue il lavoro dal manager verso tutti i target

== Come pensarlo mentalmente ==
Formula utile:
* '''manager = cervello'''
* '''target = macchine su cui applicare le operazioni'''

Pyinfra gira nel cervello, non nelle braccia.

== Esempio base 2: inventory minimale ==
<pre>
web_servers = [
"web-01.example.net",
"web-02.example.net",
]
</pre>

Qui hai solo una lista di host.

== Esempio base 3: operation semplice ==
<pre>
from pyinfra.operations import server

server.shell(
name="Show uptime",
commands=["uptime"],
)
</pre>

Esecuzione:
<pre>
pyinfra inventory.py deploy.py
</pre>

== Esempio base 4: installare pacchetti ==
<pre>
from pyinfra.operations import apt

apt.packages(
name="Install packages",
packages=["vim", "curl"],
update=True,
)
</pre>

Questo e un esempio di operation idempotente: se i pacchetti sono gia presenti, pyinfra non rifara cambiamenti inutili.

== Esempio base 5: gestire file ==
<pre>
from pyinfra.operations import files

files.file(
name="Ensure app log exists",
path="/var/log/app.log",
user="app",
group="app",
mode="644",
)
</pre>

== Esempio base 6: gestire servizi ==
<pre>
from pyinfra.operations import systemd

systemd.service(
name="Ensure nginx is running",
service="nginx",
running=True,
enabled=True,
)
</pre>

== Esempio intermedio 1: dati host ==
Inventory:
<pre>
app_servers = [
("app-01.example.net", {"install_nginx": True}),
("app-02.example.net", {"install_nginx": False}),
]
</pre>

Deploy:
<pre>
from pyinfra import host
from pyinfra.operations import apt

if host.data.get("install_nginx"):
apt.packages(
name="Install nginx",
packages=["nginx"],
update=True,
)
</pre>

Qui usi Python per rendere il deploy diverso in base ai dati del target.

== Esempio intermedio 2: gruppi ==
<pre>
from pyinfra import host, local
from pyinfra.operations import server

if "web_servers" in host.groups:
local.include("tasks/web.py")

if "db_servers" in host.groups:
local.include("tasks/database.py")

server.shell(
name="Run everywhere",
commands=["hostname"],
)
</pre>

Questo pattern e utile quando vuoi dividere la logica in file piu piccoli.

== Esempio avanzato 1: deploy locale che richiama un helper Python ==
Questo e il pattern usato nel progetto Proxmox Web UI: pyinfra gira su <code>@local</code> ma esegue un helper esterno che contiene la logica vera.

<pre>
#!/usr/bin/env python3
import os
import shlex
from pathlib import Path

from pyinfra.operations import server

BASE_DIR = Path(__file__).resolve().parents[1]
python_bin = os.environ.get("PYTHON_BIN", str(BASE_DIR / "venv" / "bin" / "python"))
helper = BASE_DIR / "lib" / "proxmox_ssh.py"
cmd = f"{shlex.quote(python_bin)} {shlex.quote(str(helper))}"

server.shell(
name=f"Create Proxmox VM {os.environ.get('VM_NAME', '')}",
commands=[cmd],
)
</pre>

Idea pratica:
* pyinfra fa da orchestratore locale
* il file helper fa il lavoro specializzato
* le variabili ambiente passano i parametri del job

== Esempio avanzato 2: usare pyinfra come backend di una UI ==
Nel caso GazziNet il flusso e:
# la UI riceve input dell'utente
# la UI valida i campi
# la UI crea un job con stato e log
# il job lancia <code>pyinfra @local deploy.py -y</code>
# pyinfra richiama un helper che esegue SSH su Proxmox

Questa soluzione e utile quando vuoi:
* separare presentazione e automazione
* conservare log testuali chiari
* evitare che il browser parli direttamente con Proxmox

== Esempio avanzato 3: rete dinamica e validazione ==
Nel progetto VM automatiche la UI gestisce:
* DHCP oppure IP statico
* bridge selezionabile
* VLAN opzionale
* validazione preventiva bridge + VLAN
* ricerca del primo VMID libero

In questo caso pyinfra non decide la rete da solo: riceve i valori gia normalizzati e li passa al backend di provisioning.

== Esempio dry run ==
<pre>
pyinfra inventory.py deploy.py --dry
</pre>

Utile prima di un deploy reale.

== Pattern reali da ricordare ==
* tenere inventory e deploy in Git
* separare logica generale e helper specializzati
* validare input prima di lanciare pyinfra
* non mescolare segreti nei file versionati
* aggiungere sempre un modo semplice per verificare il risultato

== Collegamenti ==
* [[Pyinfra]]
* [[Pyinfra/Deploy automatico VM Proxmox]]
* [[Pyinfra/Implementazione deploy VM linea per linea]]
* [[Confronto Ansible vs Pyinfra]]

Pyinfra

2026-03-29T19:21:07Z

Maintenance script: Espansione

__NOTOC__
= Pyinfra =

'''Pyinfra''' in GazziNet va letto su due livelli:
* come strumento generale di automazione scritto in Python
* come implementazione concreta gia pubblicata su <code>bot.gazzi.net/pyinfra/</code> per creare VM Proxmox via browser

Questa pagina principale e pensata per una persona umana che vuole capire rapidamente:
* che cosa fa pyinfra
* quando usarlo
* dove trovare esempi semplici e avanzati
* dove trovare il runbook reale della web UI pubblicata
* dove trovare la spiegazione tecnica dell'implementazione del deploy automatico VM

I dettagli sensibili non vanno messi in wiki. Password, token, cookie, backend privati e dump runtime restano fuori dalla documentazione pubblica o semi-pubblica.

== In una frase ==
Pyinfra e un motore di automazione che usa Python per descrivere inventory, logica e operazioni di deploy in modo piu programmabile rispetto ai playbook puramente YAML.

== Quando ha senso usarlo ==
Pyinfra e adatto quando:
* vuoi tenere deploy e configurazioni in Git
* preferisci Python per logica, condizioni e riuso
* devi automatizzare server Linux, homelab o ambienti interni
* vuoi una separazione chiara tra form di input, validazione e runner di provisioning

Pyinfra e meno adatto quando:
* il team vuole solo file dichiarativi molto semplici
* nessuno vuole mantenere codice Python
* l'automazione deve essere totalmente guidata da un pannello visuale gia pronto

== Concetti base ==
Tre idee utili da capire subito:

=== 1. Inventory ===
L'inventory descrive i target: host, gruppi e dati associati.

=== 2. Operations ===
Le operations descrivono cosa deve essere applicato ai target, oppure uno stato che vuoi rendere vero.

=== 3. Esecuzione ===
Pyinfra legge inventory e dati, prepara l'ordine delle operazioni, si connette ai target ed esegue le modifiche.

== Nel caso GazziNet ==
Su GazziNet pyinfra non e stato usato come esercizio teorico. E stato integrato in una soluzione completa:
* UI pubblica: <code>https://bot.gazzi.net/pyinfra/</code>
* autenticazione: LDAP
* runner: <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* target: Proxmox
* risultato: creazione controllata di VM con parametri espliciti

== Percorso consigliato di lettura ==
Se parti da zero:
# [[Esempi Pyinfra]]
# [[Pyinfra/Deploy automatico VM Proxmox]]
# [[Pyinfra/Implementazione deploy VM linea per linea]]

Se vuoi solo usare la piattaforma pubblicata:
# [[Pyinfra/Deploy automatico VM Proxmox]]

Se vuoi capire il codice:
# [[Pyinfra/Implementazione deploy VM linea per linea]]

== Mappa delle pagine ==
* [[Esempi Pyinfra]]: guida pratica con esempi base e avanzati di pyinfra.
* [[Pyinfra/Deploy automatico VM Proxmox]]: runbook umano della web UI pubblicata su bot.gazzi.net.
* [[Pyinfra/Implementazione deploy VM linea per linea]]: spiegazione tecnica del codice che realizza il deploy automatico di VM.
* [[Confronto Ansible vs Pyinfra]]: confronto generale di approccio.
* [[Installazione Pyinfra su Fedora]]: installazione CLI in ambiente Fedora.

== Domanda pratica tipica ==
Se devi controllare 10 server:
* sul '''manager''' installi <code>pyinfra</code>, tieni inventory e deploy e da li lanci i job
* sui '''10 server target''' non installi <code>pyinfra</code>, ma devi avere accesso SSH e permessi adeguati

La spiegazione completa con esempi e nella pagina:
* [[Esempi Pyinfra]]

== Esempio minimo per capire la sintassi ==
Inventory:
<pre>
web_servers = [
"web-01.example.net",
"web-02.example.net",
]
</pre>

Deploy:
<pre>
from pyinfra.operations import server

server.shell(
name="Show uptime",
commands=["uptime"],
)
</pre>

Esecuzione:
<pre>
pyinfra inventory.py deploy.py
</pre>

== Idea chiave ==
Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:
* raccoglie i parametri
* valida input e rete
* crea un job locale

Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.

Questa separazione aiuta a mantenere il flusso leggibile:
* frontend e login
* validazione e stato job
* runner pyinfra
* helper Proxmox

== Regole documentali per questa area ==
La wiki deve contenere:
* spiegazioni umane
* runbook
* esempi
* struttura dei file
* procedure di verifica

La wiki non deve contenere:
* password
* token
* cookie di sessione
* segreti runtime
* dump completi di backend interni

== Riferimenti esterni ==
* [https://pyinfra.com/ Sito ufficiale]
* [https://docs.pyinfra.com/en/3.x/ Documentazione ufficiale]
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica WordPress]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]

== Repository ==
Sorgente versionata in:
* <code>scripts-repo/pyinfra-proxmox-webui/</code>

Pagine wiki versionate nello stesso repository:
* <code>scripts-repo/pyinfra-proxmox-webui/wiki/</code>

Pyinfra/Implementazione deploy VM linea per linea

2026-03-29T18:57:47Z

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

__NOTOC__
= Pyinfra/Implementazione deploy VM linea per linea =

Questa pagina documenta l'implementazione del deploy automatico di macchine virtuali pubblicata su <code>bot.gazzi.net/pyinfra/</code>.

Obiettivo della pagina:
* far capire il flusso a una persona umana
* spiegare il ruolo di ogni file
* descrivere il codice in ordine logico
* collegare il comportamento osservabile alle righe principali dell'implementazione

Non vengono riportati segreti runtime.

== Vista d'insieme ==
I file che contano sono tre:
* <code>app.py</code>: web UI, login LDAP, API, job queue
* <code>deploys/create_vm.py</code>: entry point pyinfra
* <code>lib/proxmox_ssh.py</code>: logica concreta di creazione VM su Proxmox

Sequenza completa:
# l'utente invia la form
# <code>app.py</code> valida il payload e crea il job
# il job esegue <code>pyinfra @local deploys/create_vm.py -y</code>
# <code>create_vm.py</code> richiama <code>lib/proxmox_ssh.py</code>
# <code>proxmox_ssh.py</code> esegue i comandi <code>qm</code>, gestisce cloud-init e cleanup

== File 1: deploys/create_vm.py ==
Questo file e volutamente piccolo. Il suo scopo non e contenere logica complessa, ma fare da ponte tra pyinfra e l'helper specializzato.

=== Lettura riga per riga ===
<pre>
#!/usr/bin/env python3
import os
import shlex
from pathlib import Path

from pyinfra.operations import server
</pre>

Spiegazione:
* shebang Python
* import minimi
* import dell'operation <code>server.shell</code>

<pre>
BASE_DIR = Path(__file__).resolve().parents[1]
python_bin = os.environ.get("PYTHON_BIN", str(BASE_DIR / "venv" / "bin" / "python"))
helper = BASE_DIR / "lib" / "proxmox_ssh.py"
cmd = f"{shlex.quote(python_bin)} {shlex.quote(str(helper))}"
</pre>

Spiegazione:
* calcola la base del progetto
* legge il Python del virtualenv da variabile ambiente oppure usa il default
* individua l'helper vero da eseguire
* costruisce un comando shell sicuro con quoting

<pre>
server.shell(
name=f"Create Proxmox VM {os.environ.get('VM_NAME', '')}",
commands=[cmd],
)
</pre>

Spiegazione:
* pyinfra vede una singola operation
* il nome dell'operation include il nome VM per leggibilita
* l'operation esegue localmente il comando helper

Idea pratica:
* pyinfra orchestra
* l'helper specializzato realizza la logica

== File 2: app.py ==
Questo file ha quattro responsabilita:
* leggere la configurazione
* fare autenticazione LDAP
* servire UI e API
* creare e monitorare i job

=== Blocco 1: costanti e caricamento environment ==
Righe utili: <code>16-64</code>

Che cosa succede:
* viene definita la base del progetto
* viene caricato <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* viene inizializzata la directory stato
* vengono lette le variabili principali di app, LDAP e Proxmox
* Flask viene configurato con secret key e cookie di sessione
* vengono preparate strutture dati e lock per i job

Perche e importante:
* tutta la logica runtime dipende da questo blocco
* separa configurazione e codice
* permette di non versionare i segreti

=== Blocco 2: autenticazione e URL dietro proxy ==
Righe utili: <code>67-140</code>

Funzioni:
* <code>now_iso()</code>: timestamp uniforme dei job
* <code>require_token()</code>: token opzionale per API
* <code>forwarded_prefix()</code> e <code>url_with_prefix()</code>: supporto a <code>/pyinfra</code> dietro reverse proxy
* <code>is_authenticated()</code> e <code>require_login()</code>: controllo sessione
* <code>validate_username()</code>: sanifica lo username LDAP
* <code>ldap_authenticate()</code>: bind LDAP con template DN

Traduzione umana:
* l'app sa stare dietro Nginx senza rompere i path
* l'utente deve autenticarsi via LDAP
* eventuali API possono richiedere un token aggiuntivo se configurato

=== Blocco 3: lettura dati da Proxmox ==
Righe utili: <code>121-189</code>

Qui trovi:
* <code>proxmox_run()</code>: apre una connessione SSH a Proxmox per eseguire comandi
* <code>discover_vlans()</code>: parsifica l'output di <code>bridge vlan show</code>
* <code>discover_bridges()</code>: legge i bridge con <code>ip -o link show type bridge</code>
* <code>discover_used_vmids()</code>: legge i VMID esistenti con <code>qm list</code>
* <code>first_free_vmid()</code>: cerca il primo VMID libero da un valore iniziale

Perche serve:
* la UI non usa valori statici
* l'utente puo interrogare Proxmox prima del submit

=== Blocco 4: validazione input ==
Righe utili: <code>192-263</code>

Qui l'app controlla:
* range di interi
* formato nome VM
* formato utente Linux
* lunghezza minima password
* modalita rete
* formato bridge
* VLAN opzionale
* IP, gateway e CIDR se la rete e statica

Risultato:
* l'input viene normalizzato in <code>spec</code>
* i segreti vengono separati in <code>secrets</code>

Questa separazione e importante:
* <code>spec</code> puo essere esposto nel job
* <code>secrets</code> va trattato con piu cautela

=== Blocco 5: costruzione environment job ==
Righe utili: <code>266-290</code>

<code>build_job_env()</code> converte il dizionario del job in variabili ambiente da passare al runner.

Questo blocco e il ponte tra:
* input raccolto dalla UI
* variabili ambiente lette da <code>proxmox_ssh.py</code>

Esempi:
* <code>spec["vmid"]</code> diventa <code>VM_ID</code>
* <code>spec["bridge"]</code> diventa <code>VM_BRIDGE</code>
* la password admin diventa <code>VM_ADMIN_PASSWORD</code>

=== Blocco 6: job queue e logging ==
Righe utili: <code>293-347</code>

Componenti:
* <code>append_job()</code>: inserisce il job nelle strutture in memoria
* <code>write_job_log()</code>: salva il log su file in <code>APP_STATE_DIR</code>
* <code>run_job()</code>: lancia pyinfra in subprocess
* <code>create_job()</code>: impedisce job concorrenti e avvia il thread

Punto chiave:
* <code>active_job_lock</code> fa da semaforo per evitare due creazioni VM contemporanee

Comando usato:
<pre>
pyinfra @local deploys/create_vm.py -y
</pre>

=== Blocco 7: interfaccia HTML ===
Righe utili: <code>350-560</code>

La parte HTML/CSS contiene:
* layout pagina
* campi del form
* sezione job recenti

Campi operativi importanti:
* VMID
* nome VM
* utente sudo
* password sudo
* CPU, RAM, disco
* rete, bridge, VLAN
* gateway, CIDR, IP statico
* checkbox avvio automatico

Nota:
* le righe di stile puro servono a presentazione e leggibilita, non alla logica di deploy

=== Blocco 8: JavaScript della UI ===
Righe utili: <code>563-726</code>

Funzioni principali:
* <code>syncNetworkFields()</code>: disabilita i campi IP/gateway/CIDR quando la rete e DHCP
* <code>renderJobs()</code>: mostra i job recenti con stato, timing e output
* <code>loadVlans()</code>: chiama <code>/api/network/vlans</code>
* <code>loadBridges()</code>: chiama <code>/api/network/bridges</code>
* <code>loadFreeVmid()</code>: chiama <code>/api/proxmox/free-vmid?start=100</code>
* <code>validateNetwork()</code>: chiama <code>/api/network/validate</code> prima del submit
* <code>loadJobs()</code>: ricarica i job recenti
* submit handler della form: costruisce il payload JSON e lo invia a <code>/api/jobs/create-vm</code>

Traduzione pratica:
* il browser non parla direttamente con Proxmox
* parla solo con le API dell'app
* la UI ferma l'utente prima se bridge/VLAN non sono validi

=== Blocco 9: login e API backend ===
Righe utili: <code>733-938</code>

Route principali:
* <code>/api/health</code>
* <code>/login</code>
* <code>/logout</code>
* <code>/api/jobs</code>
* <code>/api/network/vlans</code>
* <code>/api/network/bridges</code>
* <code>/api/network/validate</code>
* <code>/api/proxmox/free-vmid</code>
* <code>/api/jobs/create-vm</code>

Punto critico:
* <code>/api/jobs/create-vm</code> fa il passaggio da richiesta web a job reale

Il flusso della route finale e:
# richiede login
# opzionalmente richiede token
# legge il JSON
# valida il payload
# crea il job
# restituisce <code>202 Accepted</code>

== File 3: lib/proxmox_ssh.py ==
Questo file e il cuore del provisioning.

=== Blocco 1: lettura environment ==
Righe utili: <code>11-29</code>

Funzioni:
* <code>env_required()</code>
* <code>env_int()</code>
* <code>env_bool()</code>

Servono a:
* leggere parametri obbligatori
* convertire interi
* interpretare flag booleani

=== Blocco 2: classe ProxmoxSSH ==
Righe utili: <code>32-75</code>

Questa classe:
* apre la sessione SSH
* esegue comandi
* stampa output e errori nel log del job
* scrive file remoti via SFTP

Perche e utile:
* centralizza tutte le interazioni con Proxmox

=== Blocco 3: attesa guest agent ed esecuzione comandi guest ==
Righe utili: <code>77-116</code>

Funzioni:
* <code>wait_for_guest_agent()</code>: esegue poll su <code>qm agent VMID ping</code>
* <code>guest_exec()</code>: esegue un comando dentro la VM via guest agent e aspetta l'exit status

Uso concreto nel progetto:
* attendere che cloud-init abbia davvero finito prima di fare cleanup

=== Blocco 4: helper di quoting ==
Righe utili: <code>119-124</code>

* <code>q()</code> usa <code>shlex.quote</code> per shell quoting
* <code>jq()</code> usa <code>json.dumps</code> per serializzare stringhe nel cloud-config

Questo evita errori banali di quoting e parsing.

=== Blocco 5: lettura parametri del job ==
Righe utili: <code>127-151</code>

Il file legge dall'environment:
* VMID, nome, utente, password
* CPU, RAM, disco
* rete, bridge, VLAN
* IP, gateway, CIDR
* flag avvio automatico
* storage, immagine cloud-init e default runtime

Qui il job passa da "payload web" a "parametri concreti di provisioning".

=== Blocco 6: costruzione rete ==
Righe utili: <code>153-164</code>

Se la rete e statica:
* richiede IP, gateway e CIDR
* costruisce <code>ipconfig0</code> nel formato Proxmox

Se la rete e DHCP:
* usa <code>ip=dhcp</code>

Poi costruisce <code>net0</code>:
* NIC virtio
* bridge obbligatorio
* firewall abilitato
* eventuale tag VLAN

=== Blocco 7: verifica collisione VMID ==
Righe utili: <code>166-169</code>

Prima di creare la VM, il file esegue:
<pre>
qm config <VMID>
</pre>

Se il comando funziona, il VMID esiste gia e il job viene fermato.

=== Blocco 8: generazione snippet cloud-init ==
Righe utili: <code>171-191</code>

Questo e uno dei punti piu importanti:
* crea un file <code>pyinfra-user-<VMID>.yaml</code>
* lo salva in <code>/var/lib/vz/snippets/</code>
* definisce l'utente richiesto
* assegna gruppi <code>adm</code> e <code>sudo</code>
* imposta shell bash
* abilita sudo senza password
* inserisce la password iniziale
* abilita password auth SSH
* disabilita root

Perche esiste:
* il deploy deve creare un utente iniziale specificato dall'operatore

=== Blocco 9: lista comandi qm ==
Righe utili: <code>193-224</code>

Questo array contiene i passi di creazione macchina:
* <code>qm create</code> con nome, BIOS, machine type, RAM, CPU, NIC e seriale
* <code>qm set --efidisk0</code>
* <code>qm set --scsihw</code>
* <code>qm set --scsi0 import-from=IMAGE</code>
* <code>qm set --ide2 CLOUDINIT</code>
* <code>qm set --boot order=scsi0</code>
* <code>qm set --ciuser</code>
* <code>qm set --ipconfig0</code>
* <code>qm resize</code>

Idea pratica:
* la VM nasce come cloud image Proxmox correttamente preparata

=== Blocco 10: password cloud-init, cicustom e avvio ==
Righe utili: <code>226-238</code>

Passi:
* se c'e una password, esegue <code>qm set --cipassword</code>
* applica lo snippet custom con <code>qm set --cicustom user=...</code>
* se esiste un default <code>PROXMOX_CICUSTOM_USER</code>, lo ignora e lo segnala a log
* se richiesto, avvia la VM con <code>qm start</code>

=== Blocco 11: attesa primo boot e cleanup ==
Righe utili: <code>240-251</code>

Se la VM parte subito:
* aspetta il guest agent
* esegue dentro la VM <code>cloud-init status --wait</code>
* rimuove il riferimento <code>cicustom</code>
* cancella lo snippet da <code>/var/lib/vz/snippets/</code>

Se la VM non parte subito:
* scrive un warning
* lo snippet non puo essere eliminato immediatamente

Questo blocco esiste per ridurre il tempo in cui la password resta scritta nel file cloud-init sul nodo Proxmox.

=== Blocco 12: messaggio finale ==
Riga utile: <code>253</code>

Se tutto va bene, il log termina con il messaggio di creazione VM completata.

== Esempio di flusso completo ==
Caso:
* VMID 120
* nome <code>demo.gazzi.local</code>
* utente <code>gazzinet</code>
* rete DHCP
* bridge <code>vmbr1</code>

Flusso:
# l'utente compila la form
# JavaScript invia JSON a <code>/api/jobs/create-vm</code>
# <code>parse_payload()</code> valida tutti i campi
# <code>create_job()</code> apre il job
# <code>run_job()</code> lancia pyinfra
# <code>create_vm.py</code> richiama l'helper
# <code>proxmox_ssh.py</code> costruisce la VM
# se la VM parte subito, il sistema aspetta cloud-init e rimuove lo snippet

== Cosa leggere se devi fare modifiche ==
Se devi cambiare la UI:
* <code>app.py</code> blocchi HTML e JavaScript

Se devi cambiare validazioni:
* <code>app.py</code> blocchi <code>parse_payload()</code> e API network

Se devi cambiare il provisioning Proxmox:
* <code>lib/proxmox_ssh.py</code>

Se devi cambiare il modo in cui pyinfra lancia l'helper:
* <code>deploys/create_vm.py</code>

== Limiti di questa documentazione ==
Questa pagina e molto piu dettagliata del normale, ma continua a privilegiare:
* chiarezza
* leggibilita umana
* raggruppamento per blocchi logici

Non descrive ogni singola riga di CSS decorativo, perche quella parte non governa il deploy automatico VM. La logica operativa invece e coperta integralmente.

== Collegamenti ==
* [[Pyinfra]]
* [[Esempi Pyinfra]]
* [[Pyinfra/Deploy automatico VM Proxmox]]

Pyinfra

2026-03-29T18:56:31Z

Maintenance script: Fix

__NOTOC__
= Pyinfra =

'''Pyinfra''' in GazziNet va letto su due livelli:
* come strumento generale di automazione scritto in Python
* come implementazione concreta gia pubblicata su <code>bot.gazzi.net/pyinfra/</code> per creare VM Proxmox via browser

Questa pagina principale e pensata per una persona umana che vuole capire rapidamente:
* che cosa fa pyinfra
* quando usarlo
* dove trovare esempi semplici e avanzati
* dove trovare il runbook reale della web UI pubblicata
* dove trovare la spiegazione tecnica dell'implementazione del deploy automatico VM

I dettagli sensibili non vanno messi in wiki. Password, token, cookie, backend privati e dump runtime restano fuori dalla documentazione pubblica o semi-pubblica.

== In una frase ==
Pyinfra e un motore di automazione che usa Python per descrivere inventory, logica e operazioni di deploy in modo piu programmabile rispetto ai playbook puramente YAML.

== Quando ha senso usarlo ==
Pyinfra e adatto quando:
* vuoi tenere deploy e configurazioni in Git
* preferisci Python per logica, condizioni e riuso
* devi automatizzare server Linux, homelab o ambienti interni
* vuoi una separazione chiara tra form di input, validazione e runner di provisioning

Pyinfra e meno adatto quando:
* il team vuole solo file dichiarativi molto semplici
* nessuno vuole mantenere codice Python
* l'automazione deve essere totalmente guidata da un pannello visuale gia pronto

== Concetti base ==
Tre idee utili da capire subito:

=== 1. Inventory ===
L'inventory descrive i target: host, gruppi e dati associati.

=== 2. Operations ===
Le operations descrivono cosa deve essere applicato ai target, oppure uno stato che vuoi rendere vero.

=== 3. Esecuzione ===
Pyinfra legge inventory e dati, prepara l'ordine delle operazioni, si connette ai target ed esegue le modifiche.

== Nel caso GazziNet ==
Su GazziNet pyinfra non e stato usato come esercizio teorico. E stato integrato in una soluzione completa:
* UI pubblica: <code>https://bot.gazzi.net/pyinfra/</code>
* autenticazione: LDAP
* runner: <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* target: Proxmox
* risultato: creazione controllata di VM con parametri espliciti

== Percorso consigliato di lettura ==
Se parti da zero:
# [[Esempi Pyinfra]]
# [[Pyinfra/Deploy automatico VM Proxmox]]
# [[Pyinfra/Implementazione deploy VM linea per linea]]

Se vuoi solo usare la piattaforma pubblicata:
# [[Pyinfra/Deploy automatico VM Proxmox]]

Se vuoi capire il codice:
# [[Pyinfra/Implementazione deploy VM linea per linea]]

== Mappa delle pagine ==
* [[Esempi Pyinfra]]: guida pratica con esempi base e avanzati di pyinfra.
* [[Pyinfra/Deploy automatico VM Proxmox]]: runbook umano della web UI pubblicata su bot.gazzi.net.
* [[Pyinfra/Implementazione deploy VM linea per linea]]: spiegazione tecnica del codice che realizza il deploy automatico di VM.
* [[Confronto Ansible vs Pyinfra]]: confronto generale di approccio.
* [[Installazione Pyinfra su Fedora]]: installazione CLI in ambiente Fedora.

== Esempio minimo per capire la sintassi ==
Inventory:
<pre>
web_servers = [
"web-01.example.net",
"web-02.example.net",
]
</pre>

Deploy:
<pre>
from pyinfra.operations import server

server.shell(
name="Show uptime",
commands=["uptime"],
)
</pre>

Esecuzione:
<pre>
pyinfra inventory.py deploy.py
</pre>

== Idea chiave ==
Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:
* raccoglie i parametri
* valida input e rete
* crea un job locale

Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.

Questa separazione aiuta a mantenere il flusso leggibile:
* frontend e login
* validazione e stato job
* runner pyinfra
* helper Proxmox

== Regole documentali per questa area ==
La wiki deve contenere:
* spiegazioni umane
* runbook
* esempi
* struttura dei file
* procedure di verifica

La wiki non deve contenere:
* password
* token
* cookie di sessione
* segreti runtime
* dump completi di backend interni

== Riferimenti esterni ==
* [https://pyinfra.com/ Sito ufficiale]
* [https://docs.pyinfra.com/en/3.x/ Documentazione ufficiale]
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica WordPress]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]

== Repository ==
Sorgente versionata in:
* <code>scripts-repo/pyinfra-proxmox-webui/</code>

Pagine wiki versionate nello stesso repository:
* <code>scripts-repo/pyinfra-proxmox-webui/wiki/</code>

Pyinfra/Implementazione deploy VM linea per linea

2026-03-29T18:55:31Z

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

__NOTOC__
= Pyinfra/Implementazione deploy VM linea per linea =

Questa pagina documenta l'implementazione del deploy automatico di macchine virtuali pubblicata su <code>bot.gazzi.net/pyinfra/</code>.

Obiettivo della pagina:
* far capire il flusso a una persona umana
* spiegare il ruolo di ogni file
* descrivere il codice in ordine logico
* collegare il comportamento osservabile alle righe principali dell'implementazione

Non vengono riportati segreti runtime.

== Vista d'insieme ==
I file che contano sono tre:
* <code>app.py</code>: web UI, login LDAP, API, job queue
* <code>deploys/create_vm.py</code>: entry point pyinfra
* <code>lib/proxmox_ssh.py</code>: logica concreta di creazione VM su Proxmox

Sequenza completa:
# l'utente invia la form
# <code>app.py</code> valida il payload e crea il job
# il job esegue <code>pyinfra @local deploys/create_vm.py -y</code>
# <code>create_vm.py</code> richiama <code>lib/proxmox_ssh.py</code>
# <code>proxmox_ssh.py</code> esegue i comandi <code>qm</code>, gestisce cloud-init e cleanup

== File 1: deploys/create_vm.py ==
Questo file e volutamente piccolo. Il suo scopo non e contenere logica complessa, ma fare da ponte tra pyinfra e l'helper specializzato.

=== Lettura riga per riga ===
<pre>
#!/usr/bin/env python3
import os
import shlex
from pathlib import Path

from pyinfra.operations import server
</pre>

Spiegazione:
* shebang Python
* import minimi
* import dell'operation <code>server.shell</code>

<pre>
BASE_DIR = Path(__file__).resolve().parents[1]
python_bin = os.environ.get("PYTHON_BIN", str(BASE_DIR / "venv" / "bin" / "python"))
helper = BASE_DIR / "lib" / "proxmox_ssh.py"
cmd = f"{shlex.quote(python_bin)} {shlex.quote(str(helper))}"
</pre>

Spiegazione:
* calcola la base del progetto
* legge il Python del virtualenv da variabile ambiente oppure usa il default
* individua l'helper vero da eseguire
* costruisce un comando shell sicuro con quoting

<pre>
server.shell(
name=f"Create Proxmox VM {os.environ.get('VM_NAME', '')}",
commands=[cmd],
)
</pre>

Spiegazione:
* pyinfra vede una singola operation
* il nome dell'operation include il nome VM per leggibilita
* l'operation esegue localmente il comando helper

Idea pratica:
* pyinfra orchestra
* l'helper specializzato realizza la logica

== File 2: app.py ==
Questo file ha quattro responsabilita:
* leggere la configurazione
* fare autenticazione LDAP
* servire UI e API
* creare e monitorare i job

=== Blocco 1: costanti e caricamento environment ==
Righe utili: <code>16-64</code>

Che cosa succede:
* viene definita la base del progetto
* viene caricato <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* viene inizializzata la directory stato
* vengono lette le variabili principali di app, LDAP e Proxmox
* Flask viene configurato con secret key e cookie di sessione
* vengono preparate strutture dati e lock per i job

Perche e importante:
* tutta la logica runtime dipende da questo blocco
* separa configurazione e codice
* permette di non versionare i segreti

=== Blocco 2: autenticazione e URL dietro proxy ==
Righe utili: <code>67-140</code>

Funzioni:
* <code>now_iso()</code>: timestamp uniforme dei job
* <code>require_token()</code>: token opzionale per API
* <code>forwarded_prefix()</code> e <code>url_with_prefix()</code>: supporto a <code>/pyinfra</code> dietro reverse proxy
* <code>is_authenticated()</code> e <code>require_login()</code>: controllo sessione
* <code>validate_username()</code>: sanifica lo username LDAP
* <code>ldap_authenticate()</code>: bind LDAP con template DN

Traduzione umana:
* l'app sa stare dietro Nginx senza rompere i path
* l'utente deve autenticarsi via LDAP
* eventuali API possono richiedere un token aggiuntivo se configurato

=== Blocco 3: lettura dati da Proxmox ==
Righe utili: <code>121-189</code>

Qui trovi:
* <code>proxmox_run()</code>: apre una connessione SSH a Proxmox per eseguire comandi
* <code>discover_vlans()</code>: parsifica l'output di <code>bridge vlan show</code>
* <code>discover_bridges()</code>: legge i bridge con <code>ip -o link show type bridge</code>
* <code>discover_used_vmids()</code>: legge i VMID esistenti con <code>qm list</code>
* <code>first_free_vmid()</code>: cerca il primo VMID libero da un valore iniziale

Perche serve:
* la UI non usa valori statici
* l'utente puo interrogare Proxmox prima del submit

=== Blocco 4: validazione input ==
Righe utili: <code>192-263</code>

Qui l'app controlla:
* range di interi
* formato nome VM
* formato utente Linux
* lunghezza minima password
* modalita rete
* formato bridge
* VLAN opzionale
* IP, gateway e CIDR se la rete e statica

Risultato:
* l'input viene normalizzato in <code>spec</code>
* i segreti vengono separati in <code>secrets</code>

Questa separazione e importante:
* <code>spec</code> puo essere esposto nel job
* <code>secrets</code> va trattato con piu cautela

=== Blocco 5: costruzione environment job ==
Righe utili: <code>266-290</code>

<code>build_job_env()</code> converte il dizionario del job in variabili ambiente da passare al runner.

Questo blocco e il ponte tra:
* input raccolto dalla UI
* variabili ambiente lette da <code>proxmox_ssh.py</code>

Esempi:
* <code>spec["vmid"]</code> diventa <code>VM_ID</code>
* <code>spec["bridge"]</code> diventa <code>VM_BRIDGE</code>
* la password admin diventa <code>VM_ADMIN_PASSWORD</code>

=== Blocco 6: job queue e logging ==
Righe utili: <code>293-347</code>

Componenti:
* <code>append_job()</code>: inserisce il job nelle strutture in memoria
* <code>write_job_log()</code>: salva il log su file in <code>APP_STATE_DIR</code>
* <code>run_job()</code>: lancia pyinfra in subprocess
* <code>create_job()</code>: impedisce job concorrenti e avvia il thread

Punto chiave:
* <code>active_job_lock</code> fa da semaforo per evitare due creazioni VM contemporanee

Comando usato:
<pre>
pyinfra @local deploys/create_vm.py -y
</pre>

=== Blocco 7: interfaccia HTML ===
Righe utili: <code>350-560</code>

La parte HTML/CSS contiene:
* layout pagina
* campi del form
* sezione job recenti

Campi operativi importanti:
* VMID
* nome VM
* utente sudo
* password sudo
* CPU, RAM, disco
* rete, bridge, VLAN
* gateway, CIDR, IP statico
* checkbox avvio automatico

Nota:
* le righe di stile puro servono a presentazione e leggibilita, non alla logica di deploy

=== Blocco 8: JavaScript della UI ===
Righe utili: <code>563-726</code>

Funzioni principali:
* <code>syncNetworkFields()</code>
disabilita i campi IP/gateway/CIDR quando la rete e DHCP
* <code>renderJobs()</code>
mostra i job recenti con stato, timing e output
* <code>loadVlans()</code>
chiama <code>/api/network/vlans</code>
* <code>loadBridges()</code>
chiama <code>/api/network/bridges</code>
* <code>loadFreeVmid()</code>
chiama <code>/api/proxmox/free-vmid?start=100</code>
* <code>validateNetwork()</code>
chiama <code>/api/network/validate</code> prima del submit
* <code>loadJobs()</code>
ricarica i job recenti
* submit handler della form
costruisce il payload JSON e lo invia a <code>/api/jobs/create-vm</code>

Traduzione pratica:
* il browser non parla direttamente con Proxmox
* parla solo con le API dell'app
* la UI ferma l'utente prima se bridge/VLAN non sono validi

=== Blocco 9: login e API backend ===
Righe utili: <code>733-938</code>

Route principali:
* <code>/api/health</code>
* <code>/login</code>
* <code>/logout</code>
* <code>/api/jobs</code>
* <code>/api/network/vlans</code>
* <code>/api/network/bridges</code>
* <code>/api/network/validate</code>
* <code>/api/proxmox/free-vmid</code>
* <code>/api/jobs/create-vm</code>

Punto critico:
* <code>/api/jobs/create-vm</code> fa il passaggio da richiesta web a job reale

Il flusso della route finale e:
# richiede login
# opzionalmente richiede token
# legge il JSON
# valida il payload
# crea il job
# restituisce <code>202 Accepted</code>

== File 3: lib/proxmox_ssh.py ==
Questo file e il cuore del provisioning.

=== Blocco 1: lettura environment ==
Righe utili: <code>11-29</code>

Funzioni:
* <code>env_required()</code>
* <code>env_int()</code>
* <code>env_bool()</code>

Servono a:
* leggere parametri obbligatori
* convertire interi
* interpretare flag booleani

=== Blocco 2: classe ProxmoxSSH ==
Righe utili: <code>32-75</code>

Questa classe:
* apre la sessione SSH
* esegue comandi
* stampa output e errori nel log del job
* scrive file remoti via SFTP

Perche e utile:
* centralizza tutte le interazioni con Proxmox

=== Blocco 3: attesa guest agent ed esecuzione comandi guest ==
Righe utili: <code>77-116</code>

Funzioni:
* <code>wait_for_guest_agent()</code>
esegue poll su <code>qm agent VMID ping</code>
* <code>guest_exec()</code>
esegue un comando dentro la VM via guest agent e aspetta l'exit status

Uso concreto nel progetto:
* attendere che cloud-init abbia davvero finito prima di fare cleanup

=== Blocco 4: helper di quoting ==
Righe utili: <code>119-124</code>

* <code>q()</code> usa <code>shlex.quote</code> per shell quoting
* <code>jq()</code> usa <code>json.dumps</code> per serializzare stringhe nel cloud-config

Questo evita errori banali di quoting e parsing.

=== Blocco 5: lettura parametri del job ==
Righe utili: <code>127-151</code>

Il file legge dall'environment:
* VMID, nome, utente, password
* CPU, RAM, disco
* rete, bridge, VLAN
* IP, gateway, CIDR
* flag avvio automatico
* storage, immagine cloud-init e default runtime

Qui il job passa da "payload web" a "parametri concreti di provisioning".

=== Blocco 6: costruzione rete ==
Righe utili: <code>153-164</code>

Se la rete e statica:
* richiede IP, gateway e CIDR
* costruisce <code>ipconfig0</code> nel formato Proxmox

Se la rete e DHCP:
* usa <code>ip=dhcp</code>

Poi costruisce <code>net0</code>:
* NIC virtio
* bridge obbligatorio
* firewall abilitato
* eventuale tag VLAN

=== Blocco 7: verifica collisione VMID ==
Righe utili: <code>166-169</code>

Prima di creare la VM, il file esegue:
<pre>
qm config <VMID>
</pre>

Se il comando funziona, il VMID esiste gia e il job viene fermato.

=== Blocco 8: generazione snippet cloud-init ==
Righe utili: <code>171-191</code>

Questo e uno dei punti piu importanti:
* crea un file <code>pyinfra-user-<VMID>.yaml</code>
* lo salva in <code>/var/lib/vz/snippets/</code>
* definisce l'utente richiesto
* assegna gruppi <code>adm</code> e <code>sudo</code>
* imposta shell bash
* abilita sudo senza password
* inserisce la password iniziale
* abilita password auth SSH
* disabilita root

Perche esiste:
* il deploy deve creare un utente iniziale specificato dall'operatore

=== Blocco 9: lista comandi qm ==
Righe utili: <code>193-224</code>

Questo array contiene i passi di creazione macchina:
* <code>qm create</code> con nome, BIOS, machine type, RAM, CPU, NIC e seriale
* <code>qm set --efidisk0</code>
* <code>qm set --scsihw</code>
* <code>qm set --scsi0 import-from=IMAGE</code>
* <code>qm set --ide2 CLOUDINIT</code>
* <code>qm set --boot order=scsi0</code>
* <code>qm set --ciuser</code>
* <code>qm set --ipconfig0</code>
* <code>qm resize</code>

Idea pratica:
* la VM nasce come cloud image Proxmox correttamente preparata

=== Blocco 10: password cloud-init, cicustom e avvio ==
Righe utili: <code>226-238</code>

Passi:
* se c'e una password, esegue <code>qm set --cipassword</code>
* applica lo snippet custom con <code>qm set --cicustom user=...</code>
* se esiste un default <code>PROXMOX_CICUSTOM_USER</code>, lo ignora e lo segnala a log
* se richiesto, avvia la VM con <code>qm start</code>

=== Blocco 11: attesa primo boot e cleanup ==
Righe utili: <code>240-251</code>

Se la VM parte subito:
* aspetta il guest agent
* esegue dentro la VM <code>cloud-init status --wait</code>
* rimuove il riferimento <code>cicustom</code>
* cancella lo snippet da <code>/var/lib/vz/snippets/</code>

Se la VM non parte subito:
* scrive un warning
* lo snippet non puo essere eliminato immediatamente

Questo blocco esiste per ridurre il tempo in cui la password resta scritta nel file cloud-init sul nodo Proxmox.

=== Blocco 12: messaggio finale ==
Riga utile: <code>253</code>

Se tutto va bene, il log termina con il messaggio di creazione VM completata.

== Esempio di flusso completo ==
Caso:
* VMID 120
* nome <code>demo.gazzi.local</code>
* utente <code>gazzinet</code>
* rete DHCP
* bridge <code>vmbr1</code>

Flusso:
# l'utente compila la form
# JavaScript invia JSON a <code>/api/jobs/create-vm</code>
# <code>parse_payload()</code> valida tutti i campi
# <code>create_job()</code> apre il job
# <code>run_job()</code> lancia pyinfra
# <code>create_vm.py</code> richiama l'helper
# <code>proxmox_ssh.py</code> costruisce la VM
# se la VM parte subito, il sistema aspetta cloud-init e rimuove lo snippet

== Cosa leggere se devi fare modifiche ==
Se devi cambiare la UI:
* <code>app.py</code> blocchi HTML e JavaScript

Se devi cambiare validazioni:
* <code>app.py</code> blocchi <code>parse_payload()</code> e API network

Se devi cambiare il provisioning Proxmox:
* <code>lib/proxmox_ssh.py</code>

Se devi cambiare il modo in cui pyinfra lancia l'helper:
* <code>deploys/create_vm.py</code>

== Limiti di questa documentazione ==
Questa pagina e molto piu dettagliata del normale, ma continua a privilegiare:
* chiarezza
* leggibilita umana
* raggruppamento per blocchi logici

Non descrive ogni singola riga di CSS decorativo, perche quella parte non governa il deploy automatico VM. La logica operativa invece e coperta integralmente.

== Collegamenti ==
* [[Pyinfra]]
* [[Esempi Pyinfra]]
* [[Pyinfra/Deploy automatico VM Proxmox]]

Pyinfra/Deploy automatico VM Proxmox

2026-03-29T18:55:31Z

Maintenance script: Aggiunta runbook operativo deploy automatico VM Proxmox

__NOTOC__
= Pyinfra/Deploy automatico VM Proxmox =

Questa pagina descrive la soluzione concreta pubblicata su <code>bot.gazzi.net/pyinfra/</code>. L'obiettivo non e insegnare pyinfra in astratto, ma permettere a una persona umana di capire come e fatta l'automazione, come si usa e come si mantiene.

== Obiettivo ==
Consentire la creazione guidata di VM Proxmox via browser, con:
* autenticazione LDAP
* validazione dei parametri
* job serializzati
* log consultabili
* provisioning reale eseguito via pyinfra

== Cosa vede l'utente ==
La form pubblica consente di inserire:
* VMID
* nome VM
* utente amministrativo iniziale
* password iniziale
* CPU
* RAM
* disco
* rete DHCP o statica
* bridge
* VLAN
* gateway
* CIDR
* scelta se avviare subito la VM

Pulsanti di supporto:
* ricerca del primo VMID libero a partire da <code>100</code>
* elenco bridge disponibili
* elenco VLAN disponibili sul bridge scelto

== Flusso umano ==
Una persona normale puo leggere il sistema cosi:
# apre la pagina
# fa login LDAP
# compila i parametri
# verifica rete e VMID
# preme '''Crea VM'''
# vede partire il job
# osserva il log recenti nella stessa pagina

== Flusso tecnico ==
# Nginx pubblica <code>/pyinfra/</code>
# Flask gestisce login, pagina, API e job
# il job lancia <code>pyinfra @local</code>
# il deploy pyinfra richiama un helper Python
# l'helper apre una sessione SSH verso Proxmox
# Proxmox crea la VM e la configura con cloud-init
# se la VM parte subito, il sistema aspetta il primo boot e pulisce lo snippet cloud-init

== Componenti ==
=== 1. Frontend Flask ===
Serve HTML direttamente dall'app e contiene:
* form
* validazioni lato browser
* chiamate AJAX alle API interne
* lista job recenti

=== 2. Login LDAP ===
L'utente non entra direttamente se non ha credenziali LDAP valide.

=== 3. API interne ===
Le API servono per:
* health check
* elenco job
* lookup bridge
* lookup VLAN
* validazione bridge + VLAN
* ricerca VMID libero
* creazione job

=== 4. Runner pyinfra ===
Pyinfra viene eseguito in locale con inventario implicito <code>@local</code>.

=== 5. Helper Proxmox ===
L'helper Python usa <code>paramiko</code> e comandi <code>qm</code> per creare la VM.

== File importanti ==
Versionati:
* <code>scripts-repo/pyinfra-proxmox-webui/app.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/deploys/create_vm.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/lib/proxmox_ssh.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/systemd/pyinfra-webui.service</code>
* <code>scripts-repo/pyinfra-proxmox-webui/proxy01-bot-pyinfra-location.conf.example</code>
* <code>scripts-repo/pyinfra-proxmox-webui/.env.example</code>

Runtime:
* <code>/opt/pyinfra-webui</code>
* <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* <code>/etc/systemd/system/pyinfra-webui.service</code>
* <code>/var/lib/pyinfra-webui</code>

== Esempio ragionato di environment file ==
Usare placeholder, non segreti reali:

<pre>
APP_HOST=0.0.0.0
APP_PORT=18180
APP_BASE_PATH=/pyinfra
APP_TOKEN=CHANGEME
APP_SECRET_KEY=CHANGEME
APP_STATE_DIR=/var/lib/pyinfra-webui

PROXMOX_SSH_HOST=PROXMOX_HOST
PROXMOX_SSH_PORT=22
PROXMOX_SSH_USER=root
PROXMOX_SSH_PASS=CHANGEME

PROXMOX_IMAGE=/var/lib/vz/template/iso/noble-server-cloudimg-amd64.img
PROXMOX_STORAGE=local
PROXMOX_CLOUDINIT_STORAGE=local
PROXMOX_BRIDGE=vmbr1
PROXMOX_GATEWAY=172.16.1.1
PROXMOX_CPU_TYPE=x86-64-v2-AES
PROXMOX_CIUSER=ubuntu
PROXMOX_CIPASSWORD=CHANGEME
PROXMOX_CICUSTOM_USER=local:snippets/gazzi-ubuntu-user.yaml

LDAP_URI=ldap://LDAP_HOST:389
LDAP_USER_DN_TEMPLATE=uid={username},ou=People,dc=gazzi,dc=local
</pre>

== Cosa significano le variabili ==
* <code>APP_HOST</code> e <code>APP_PORT</code>: bind locale del servizio Flask
* <code>APP_BASE_PATH</code>: prefisso usato quando l'app sta dietro reverse proxy su <code>/pyinfra</code>
* <code>APP_TOKEN</code>: token opzionale per protezione addizionale API
* <code>APP_SECRET_KEY</code>: chiave sessione Flask
* <code>APP_STATE_DIR</code>: directory per log e stato job
* <code>PROXMOX_*</code>: connessione e default di provisioning
* <code>LDAP_*</code>: endpoint e template DN per login utente

== Reverse proxy ==
Snippet di riferimento:
<pre>
location = /pyinfra {
return 301 /pyinfra/;
}

location /pyinfra/ {
proxy_pass http://BOT_GAZZI_LOCAL:18180/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Prefix /pyinfra;
proxy_redirect off;
}
</pre>

== Service ==
<pre>
[Unit]
Description=Pyinfra Proxmox Web UI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pyinfraweb
Group=pyinfraweb
WorkingDirectory=/opt/pyinfra-webui
EnvironmentFile=/etc/pyinfra-webui/pyinfra-webui.env
ExecStart=/opt/pyinfra-webui/venv/bin/python /opt/pyinfra-webui/app.py
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
</pre>

== Deploy iniziale ==
<pre>
sudo mkdir -p /opt/pyinfra-webui /etc/pyinfra-webui /var/lib/pyinfra-webui
sudo chown -R pyinfraweb:pyinfraweb /opt/pyinfra-webui /var/lib/pyinfra-webui

cd /opt/pyinfra-webui
python3 -m venv venv
./venv/bin/pip install -U pip
./venv/bin/pip install -r requirements.txt

sudo install -m 0644 systemd/pyinfra-webui.service /etc/systemd/system/pyinfra-webui.service
sudo systemctl daemon-reload
sudo systemctl enable --now pyinfra-webui.service
</pre>

== Aggiornamento ==
<pre>
cd /opt/pyinfra-webui
./venv/bin/pip install -r requirements.txt
sudo systemctl restart pyinfra-webui.service
</pre>

== Verifiche rapide ==
Applicative:
<pre>
curl -I https://bot.gazzi.net/pyinfra/
curl -sS http://127.0.0.1:18180/api/health
</pre>

Service:
<pre>
systemctl status pyinfra-webui.service
journalctl -u pyinfra-webui.service -n 100 --no-pager
</pre>

Funzionali:
* test login LDAP
* test bridge disponibili
* test VLAN disponibili
* test validazione bridge + VLAN
* test ricerca VMID libero
* test provisioning di una VM reale o di test

== Esempio di percorso reale ==
Caso semplice:
* rete in DHCP
* bridge scelto manualmente
* nessuna VLAN
* VM avviata subito

Caso avanzato:
* rete statica
* bridge scelto da lookup
* VLAN scelta da lookup
* VMID trovato automaticamente
* utente iniziale definito dall'operatore

== Sicurezza ==
Punti importanti:
* non mettere segreti in wiki o Git
* usare sempre HTTPS sul path pubblico
* il job parte solo a richiesta dell'utente autenticato
* la UI accetta un solo job alla volta per ridurre collisioni banali
* lo snippet cloud-init viene rimosso dopo il primo boot solo se la VM parte subito

== Limiti noti ==
* se <code>start_after_create=false</code>, lo snippet cloud-init resta finche la VM non completa il primo avvio
* la validazione VLAN dipende da cio che Proxmox espone in quel momento
* la pagina non sostituisce un orchestratore completo multi-tenant: e un ingresso operativo controllato

== Dove leggere il codice ==
Per la spiegazione dettagliata:
* [[Pyinfra/Implementazione deploy VM linea per linea]]

Per gli esempi generali:
* [[Esempi Pyinfra]]

Esempi Pyinfra

2026-03-29T18:55:31Z

Maintenance script: Espansione esempi Pyinfra con casi base e avanzati

Pyinfra

2026-03-29T18:55:30Z

Maintenance script: Espansione pagina Pyinfra con struttura umana e link di approfondimento

__NOTOC__
= Pyinfra =

'''Pyinfra''' in GazziNet va letto su due livelli:
* come strumento generale di automazione scritto in Python
* come implementazione concreta gia pubblicata su <code>bot.gazzi.net/pyinfra/</code> per creare VM Proxmox via browser

Questa pagina principale e pensata per una persona umana che vuole capire rapidamente:
* che cosa fa pyinfra
* quando usarlo
* dove trovare esempi semplici e avanzati
* dove trovare il runbook reale della web UI pubblicata
* dove trovare la spiegazione tecnica dell'implementazione del deploy automatico VM

I dettagli sensibili non vanno messi in wiki. Password, token, cookie, backend privati e dump runtime restano fuori dalla documentazione pubblica o semi-pubblica.

== In una frase ==
Pyinfra e un motore di automazione che usa Python per descrivere inventory, logica e operazioni di deploy in modo piu programmabile rispetto ai playbook puramente YAML.

== Quando ha senso usarlo ==
Pyinfra e adatto quando:
* vuoi tenere deploy e configurazioni in Git
* preferisci Python per logica, condizioni e riuso
* devi automatizzare server Linux, homelab o ambienti interni
* vuoi una separazione chiara tra form di input, validazione e runner di provisioning

Pyinfra e meno adatto quando:
* il team vuole solo file dichiarativi molto semplici
* nessuno vuole mantenere codice Python
* l'automazione deve essere totalmente guidata da un pannello visuale gia pronto

== Concetti base ==
Tre idee utili da capire subito:

=== 1. Inventory ===
L'inventory descrive i target: host, gruppi e dati associati.

=== 2. Operations ===
Le operations descrivono cosa deve essere applicato ai target, oppure uno stato che vuoi rendere vero.

=== 3. Esecuzione ===
Pyinfra legge inventory e dati, prepara l'ordine delle operazioni, si connette ai target ed esegue le modifiche.

== Nel caso GazziNet ==
Su GazziNet pyinfra non e stato usato come esercizio teorico. E stato integrato in una soluzione completa:
* UI pubblica: <code>https://bot.gazzi.net/pyinfra/</code>
* autenticazione: LDAP
* runner: <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* target: Proxmox
* risultato: creazione controllata di VM con parametri espliciti

== Percorso consigliato di lettura ==
Se parti da zero:
# [[Esempi Pyinfra]]
# [[Pyinfra/Deploy automatico VM Proxmox]]
# [[Pyinfra/Implementazione deploy VM linea per linea]]

Se vuoi solo usare la piattaforma pubblicata:
# [[Pyinfra/Deploy automatico VM Proxmox]]

Se vuoi capire il codice:
# [[Pyinfra/Implementazione deploy VM linea per linea]]

== Mappa delle pagine ==
* [[Esempi Pyinfra]]
Guida pratica con esempi base e avanzati di pyinfra.
* [[Pyinfra/Deploy automatico VM Proxmox]]
Runbook umano della web UI pubblicata su bot.gazzi.net.
* [[Pyinfra/Implementazione deploy VM linea per linea]]
Spiegazione tecnica del codice che realizza il deploy automatico di VM.
* [[Confronto Ansible vs Pyinfra]]
Confronto generale di approccio.
* [[Installazione Pyinfra su Fedora]]
Installazione CLI in ambiente Fedora.

== Esempio minimo per capire la sintassi ==
Inventory:
<pre>
web_servers = [
"web-01.example.net",
"web-02.example.net",
]
</pre>

Deploy:
<pre>
from pyinfra.operations import server

server.shell(
name="Show uptime",
commands=["uptime"],
)
</pre>

Esecuzione:
<pre>
pyinfra inventory.py deploy.py
</pre>

== Idea chiave ==
Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:
* raccoglie i parametri
* valida input e rete
* crea un job locale

Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.

Questa separazione aiuta a mantenere il flusso leggibile:
* frontend e login
* validazione e stato job
* runner pyinfra
* helper Proxmox

== Regole documentali per questa area ==
La wiki deve contenere:
* spiegazioni umane
* runbook
* esempi
* struttura dei file
* procedure di verifica

La wiki non deve contenere:
* password
* token
* cookie di sessione
* segreti runtime
* dump completi di backend interni

== Riferimenti esterni ==
* [https://pyinfra.com/ Sito ufficiale]
* [https://docs.pyinfra.com/en/3.x/ Documentazione ufficiale]
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica WordPress]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]

== Repository ==
Sorgente versionata in:
* <code>scripts-repo/pyinfra-proxmox-webui/</code>

Pagine wiki versionate nello stesso repository:
* <code>scripts-repo/pyinfra-proxmox-webui/wiki/</code>

Pyinfra/Implementazione deploy VM linea per linea

2026-03-29T18:51:30Z

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

__NOTOC__
= Pyinfra/Implementazione deploy VM linea per linea =

Questa pagina documenta l'implementazione del deploy automatico di macchine virtuali pubblicata su <code>bot.gazzi.net/pyinfra/</code>.

Obiettivo della pagina:
* far capire il flusso a una persona umana
* spiegare il ruolo di ogni file
* descrivere il codice in ordine logico
* collegare il comportamento osservabile alle righe principali dell'implementazione

Non vengono riportati segreti runtime.

== Vista d'insieme ==
I file che contano sono tre:
* <code>app.py</code>: web UI, login LDAP, API, job queue
* <code>deploys/create_vm.py</code>: entry point pyinfra
* <code>lib/proxmox_ssh.py</code>: logica concreta di creazione VM su Proxmox

Sequenza completa:
# l'utente invia la form
# <code>app.py</code> valida il payload e crea il job
# il job esegue <code>pyinfra @local deploys/create_vm.py -y</code>
# <code>create_vm.py</code> richiama <code>lib/proxmox_ssh.py</code>
# <code>proxmox_ssh.py</code> esegue i comandi <code>qm</code>, gestisce cloud-init e cleanup

== File 1: deploys/create_vm.py ==
Questo file e volutamente piccolo. Il suo scopo non e contenere logica complessa, ma fare da ponte tra pyinfra e l'helper specializzato.

=== Lettura riga per riga ===
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import os
import shlex
from pathlib import Path

from pyinfra.operations import server
</syntaxhighlight>

Spiegazione:
* shebang Python
* import minimi
* import dell'operation <code>server.shell</code>

<syntaxhighlight lang="python">
BASE_DIR = Path(__file__).resolve().parents[1]
python_bin = os.environ.get("PYTHON_BIN", str(BASE_DIR / "venv" / "bin" / "python"))
helper = BASE_DIR / "lib" / "proxmox_ssh.py"
cmd = f"{shlex.quote(python_bin)} {shlex.quote(str(helper))}"
</syntaxhighlight>

Spiegazione:
* calcola la base del progetto
* legge il Python del virtualenv da variabile ambiente oppure usa il default
* individua l'helper vero da eseguire
* costruisce un comando shell sicuro con quoting

<syntaxhighlight lang="python">
server.shell(
name=f"Create Proxmox VM {os.environ.get('VM_NAME', '')}",
commands=[cmd],
)
</syntaxhighlight>

Spiegazione:
* pyinfra vede una singola operation
* il nome dell'operation include il nome VM per leggibilita
* l'operation esegue localmente il comando helper

Idea pratica:
* pyinfra orchestra
* l'helper specializzato realizza la logica

== File 2: app.py ==
Questo file ha quattro responsabilita:
* leggere la configurazione
* fare autenticazione LDAP
* servire UI e API
* creare e monitorare i job

=== Blocco 1: costanti e caricamento environment ==
Righe utili: <code>16-64</code>

Che cosa succede:
* viene definita la base del progetto
* viene caricato <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* viene inizializzata la directory stato
* vengono lette le variabili principali di app, LDAP e Proxmox
* Flask viene configurato con secret key e cookie di sessione
* vengono preparate strutture dati e lock per i job

Perche e importante:
* tutta la logica runtime dipende da questo blocco
* separa configurazione e codice
* permette di non versionare i segreti

=== Blocco 2: autenticazione e URL dietro proxy ==
Righe utili: <code>67-140</code>

Funzioni:
* <code>now_iso()</code>: timestamp uniforme dei job
* <code>require_token()</code>: token opzionale per API
* <code>forwarded_prefix()</code> e <code>url_with_prefix()</code>: supporto a <code>/pyinfra</code> dietro reverse proxy
* <code>is_authenticated()</code> e <code>require_login()</code>: controllo sessione
* <code>validate_username()</code>: sanifica lo username LDAP
* <code>ldap_authenticate()</code>: bind LDAP con template DN

Traduzione umana:
* l'app sa stare dietro Nginx senza rompere i path
* l'utente deve autenticarsi via LDAP
* eventuali API possono richiedere un token aggiuntivo se configurato

=== Blocco 3: lettura dati da Proxmox ==
Righe utili: <code>121-189</code>

Qui trovi:
* <code>proxmox_run()</code>: apre una connessione SSH a Proxmox per eseguire comandi
* <code>discover_vlans()</code>: parsifica l'output di <code>bridge vlan show</code>
* <code>discover_bridges()</code>: legge i bridge con <code>ip -o link show type bridge</code>
* <code>discover_used_vmids()</code>: legge i VMID esistenti con <code>qm list</code>
* <code>first_free_vmid()</code>: cerca il primo VMID libero da un valore iniziale

Perche serve:
* la UI non usa valori statici
* l'utente puo interrogare Proxmox prima del submit

=== Blocco 4: validazione input ==
Righe utili: <code>192-263</code>

Qui l'app controlla:
* range di interi
* formato nome VM
* formato utente Linux
* lunghezza minima password
* modalita rete
* formato bridge
* VLAN opzionale
* IP, gateway e CIDR se la rete e statica

Risultato:
* l'input viene normalizzato in <code>spec</code>
* i segreti vengono separati in <code>secrets</code>

Questa separazione e importante:
* <code>spec</code> puo essere esposto nel job
* <code>secrets</code> va trattato con piu cautela

=== Blocco 5: costruzione environment job ==
Righe utili: <code>266-290</code>

<code>build_job_env()</code> converte il dizionario del job in variabili ambiente da passare al runner.

Questo blocco e il ponte tra:
* input raccolto dalla UI
* variabili ambiente lette da <code>proxmox_ssh.py</code>

Esempi:
* <code>spec["vmid"]</code> diventa <code>VM_ID</code>
* <code>spec["bridge"]</code> diventa <code>VM_BRIDGE</code>
* la password admin diventa <code>VM_ADMIN_PASSWORD</code>

=== Blocco 6: job queue e logging ==
Righe utili: <code>293-347</code>

Componenti:
* <code>append_job()</code>: inserisce il job nelle strutture in memoria
* <code>write_job_log()</code>: salva il log su file in <code>APP_STATE_DIR</code>
* <code>run_job()</code>: lancia pyinfra in subprocess
* <code>create_job()</code>: impedisce job concorrenti e avvia il thread

Punto chiave:
* <code>active_job_lock</code> fa da semaforo per evitare due creazioni VM contemporanee

Comando usato:
<syntaxhighlight lang="bash">
pyinfra @local deploys/create_vm.py -y
</syntaxhighlight>

=== Blocco 7: interfaccia HTML ===
Righe utili: <code>350-560</code>

La parte HTML/CSS contiene:
* layout pagina
* campi del form
* sezione job recenti

Campi operativi importanti:
* VMID
* nome VM
* utente sudo
* password sudo
* CPU, RAM, disco
* rete, bridge, VLAN
* gateway, CIDR, IP statico
* checkbox avvio automatico

Nota:
* le righe di stile puro servono a presentazione e leggibilita, non alla logica di deploy

=== Blocco 8: JavaScript della UI ===
Righe utili: <code>563-726</code>

Funzioni principali:
* <code>syncNetworkFields()</code>
disabilita i campi IP/gateway/CIDR quando la rete e DHCP
* <code>renderJobs()</code>
mostra i job recenti con stato, timing e output
* <code>loadVlans()</code>
chiama <code>/api/network/vlans</code>
* <code>loadBridges()</code>
chiama <code>/api/network/bridges</code>
* <code>loadFreeVmid()</code>
chiama <code>/api/proxmox/free-vmid?start=100</code>
* <code>validateNetwork()</code>
chiama <code>/api/network/validate</code> prima del submit
* <code>loadJobs()</code>
ricarica i job recenti
* submit handler della form
costruisce il payload JSON e lo invia a <code>/api/jobs/create-vm</code>

Traduzione pratica:
* il browser non parla direttamente con Proxmox
* parla solo con le API dell'app
* la UI ferma l'utente prima se bridge/VLAN non sono validi

=== Blocco 9: login e API backend ===
Righe utili: <code>733-938</code>

Route principali:
* <code>/api/health</code>
* <code>/login</code>
* <code>/logout</code>
* <code>/api/jobs</code>
* <code>/api/network/vlans</code>
* <code>/api/network/bridges</code>
* <code>/api/network/validate</code>
* <code>/api/proxmox/free-vmid</code>
* <code>/api/jobs/create-vm</code>

Punto critico:
* <code>/api/jobs/create-vm</code> fa il passaggio da richiesta web a job reale

Il flusso della route finale e:
# richiede login
# opzionalmente richiede token
# legge il JSON
# valida il payload
# crea il job
# restituisce <code>202 Accepted</code>

== File 3: lib/proxmox_ssh.py ==
Questo file e il cuore del provisioning.

=== Blocco 1: lettura environment ==
Righe utili: <code>11-29</code>

Funzioni:
* <code>env_required()</code>
* <code>env_int()</code>
* <code>env_bool()</code>

Servono a:
* leggere parametri obbligatori
* convertire interi
* interpretare flag booleani

=== Blocco 2: classe ProxmoxSSH ==
Righe utili: <code>32-75</code>

Questa classe:
* apre la sessione SSH
* esegue comandi
* stampa output e errori nel log del job
* scrive file remoti via SFTP

Perche e utile:
* centralizza tutte le interazioni con Proxmox

=== Blocco 3: attesa guest agent ed esecuzione comandi guest ==
Righe utili: <code>77-116</code>

Funzioni:
* <code>wait_for_guest_agent()</code>
esegue poll su <code>qm agent VMID ping</code>
* <code>guest_exec()</code>
esegue un comando dentro la VM via guest agent e aspetta l'exit status

Uso concreto nel progetto:
* attendere che cloud-init abbia davvero finito prima di fare cleanup

=== Blocco 4: helper di quoting ==
Righe utili: <code>119-124</code>

* <code>q()</code> usa <code>shlex.quote</code> per shell quoting
* <code>jq()</code> usa <code>json.dumps</code> per serializzare stringhe nel cloud-config

Questo evita errori banali di quoting e parsing.

=== Blocco 5: lettura parametri del job ==
Righe utili: <code>127-151</code>

Il file legge dall'environment:
* VMID, nome, utente, password
* CPU, RAM, disco
* rete, bridge, VLAN
* IP, gateway, CIDR
* flag avvio automatico
* storage, immagine cloud-init e default runtime

Qui il job passa da "payload web" a "parametri concreti di provisioning".

=== Blocco 6: costruzione rete ==
Righe utili: <code>153-164</code>

Se la rete e statica:
* richiede IP, gateway e CIDR
* costruisce <code>ipconfig0</code> nel formato Proxmox

Se la rete e DHCP:
* usa <code>ip=dhcp</code>

Poi costruisce <code>net0</code>:
* NIC virtio
* bridge obbligatorio
* firewall abilitato
* eventuale tag VLAN

=== Blocco 7: verifica collisione VMID ==
Righe utili: <code>166-169</code>

Prima di creare la VM, il file esegue:
<syntaxhighlight lang="bash">
qm config <VMID>
</syntaxhighlight>

Se il comando funziona, il VMID esiste gia e il job viene fermato.

=== Blocco 8: generazione snippet cloud-init ==
Righe utili: <code>171-191</code>

Questo e uno dei punti piu importanti:
* crea un file <code>pyinfra-user-<VMID>.yaml</code>
* lo salva in <code>/var/lib/vz/snippets/</code>
* definisce l'utente richiesto
* assegna gruppi <code>adm</code> e <code>sudo</code>
* imposta shell bash
* abilita sudo senza password
* inserisce la password iniziale
* abilita password auth SSH
* disabilita root

Perche esiste:
* il deploy deve creare un utente iniziale specificato dall'operatore

=== Blocco 9: lista comandi qm ==
Righe utili: <code>193-224</code>

Questo array contiene i passi di creazione macchina:
* <code>qm create</code> con nome, BIOS, machine type, RAM, CPU, NIC e seriale
* <code>qm set --efidisk0</code>
* <code>qm set --scsihw</code>
* <code>qm set --scsi0 import-from=IMAGE</code>
* <code>qm set --ide2 CLOUDINIT</code>
* <code>qm set --boot order=scsi0</code>
* <code>qm set --ciuser</code>
* <code>qm set --ipconfig0</code>
* <code>qm resize</code>

Idea pratica:
* la VM nasce come cloud image Proxmox correttamente preparata

=== Blocco 10: password cloud-init, cicustom e avvio ==
Righe utili: <code>226-238</code>

Passi:
* se c'e una password, esegue <code>qm set --cipassword</code>
* applica lo snippet custom con <code>qm set --cicustom user=...</code>
* se esiste un default <code>PROXMOX_CICUSTOM_USER</code>, lo ignora e lo segnala a log
* se richiesto, avvia la VM con <code>qm start</code>

=== Blocco 11: attesa primo boot e cleanup ==
Righe utili: <code>240-251</code>

Se la VM parte subito:
* aspetta il guest agent
* esegue dentro la VM <code>cloud-init status --wait</code>
* rimuove il riferimento <code>cicustom</code>
* cancella lo snippet da <code>/var/lib/vz/snippets/</code>

Se la VM non parte subito:
* scrive un warning
* lo snippet non puo essere eliminato immediatamente

Questo blocco esiste per ridurre il tempo in cui la password resta scritta nel file cloud-init sul nodo Proxmox.

=== Blocco 12: messaggio finale ==
Riga utile: <code>253</code>

Se tutto va bene, il log termina con il messaggio di creazione VM completata.

== Esempio di flusso completo ==
Caso:
* VMID 120
* nome <code>demo.gazzi.local</code>
* utente <code>gazzinet</code>
* rete DHCP
* bridge <code>vmbr1</code>

Flusso:
# l'utente compila la form
# JavaScript invia JSON a <code>/api/jobs/create-vm</code>
# <code>parse_payload()</code> valida tutti i campi
# <code>create_job()</code> apre il job
# <code>run_job()</code> lancia pyinfra
# <code>create_vm.py</code> richiama l'helper
# <code>proxmox_ssh.py</code> costruisce la VM
# se la VM parte subito, il sistema aspetta cloud-init e rimuove lo snippet

== Cosa leggere se devi fare modifiche ==
Se devi cambiare la UI:
* <code>app.py</code> blocchi HTML e JavaScript

Se devi cambiare validazioni:
* <code>app.py</code> blocchi <code>parse_payload()</code> e API network

Se devi cambiare il provisioning Proxmox:
* <code>lib/proxmox_ssh.py</code>

Se devi cambiare il modo in cui pyinfra lancia l'helper:
* <code>deploys/create_vm.py</code>

== Limiti di questa documentazione ==
Questa pagina e molto piu dettagliata del normale, ma continua a privilegiare:
* chiarezza
* leggibilita umana
* raggruppamento per blocchi logici

Non descrive ogni singola riga di CSS decorativo, perche quella parte non governa il deploy automatico VM. La logica operativa invece e coperta integralmente.

== Collegamenti ==
* [[Pyinfra]]
* [[Esempi Pyinfra]]
* [[Pyinfra/Deploy automatico VM Proxmox]]

Pyinfra/Deploy automatico VM Proxmox

2026-03-29T18:51:30Z

Maintenance script: Aggiunta runbook operativo deploy automatico VM Proxmox

__NOTOC__
= Pyinfra/Deploy automatico VM Proxmox =

Questa pagina descrive la soluzione concreta pubblicata su <code>bot.gazzi.net/pyinfra/</code>. L'obiettivo non e insegnare pyinfra in astratto, ma permettere a una persona umana di capire come e fatta l'automazione, come si usa e come si mantiene.

== Obiettivo ==
Consentire la creazione guidata di VM Proxmox via browser, con:
* autenticazione LDAP
* validazione dei parametri
* job serializzati
* log consultabili
* provisioning reale eseguito via pyinfra

== Cosa vede l'utente ==
La form pubblica consente di inserire:
* VMID
* nome VM
* utente amministrativo iniziale
* password iniziale
* CPU
* RAM
* disco
* rete DHCP o statica
* bridge
* VLAN
* gateway
* CIDR
* scelta se avviare subito la VM

Pulsanti di supporto:
* ricerca del primo VMID libero a partire da <code>100</code>
* elenco bridge disponibili
* elenco VLAN disponibili sul bridge scelto

== Flusso umano ==
Una persona normale puo leggere il sistema cosi:
# apre la pagina
# fa login LDAP
# compila i parametri
# verifica rete e VMID
# preme '''Crea VM'''
# vede partire il job
# osserva il log recenti nella stessa pagina

== Flusso tecnico ==
# Nginx pubblica <code>/pyinfra/</code>
# Flask gestisce login, pagina, API e job
# il job lancia <code>pyinfra @local</code>
# il deploy pyinfra richiama un helper Python
# l'helper apre una sessione SSH verso Proxmox
# Proxmox crea la VM e la configura con cloud-init
# se la VM parte subito, il sistema aspetta il primo boot e pulisce lo snippet cloud-init

== Componenti ==
=== 1. Frontend Flask ===
Serve HTML direttamente dall'app e contiene:
* form
* validazioni lato browser
* chiamate AJAX alle API interne
* lista job recenti

=== 2. Login LDAP ===
L'utente non entra direttamente se non ha credenziali LDAP valide.

=== 3. API interne ===
Le API servono per:
* health check
* elenco job
* lookup bridge
* lookup VLAN
* validazione bridge + VLAN
* ricerca VMID libero
* creazione job

=== 4. Runner pyinfra ===
Pyinfra viene eseguito in locale con inventario implicito <code>@local</code>.

=== 5. Helper Proxmox ===
L'helper Python usa <code>paramiko</code> e comandi <code>qm</code> per creare la VM.

== File importanti ==
Versionati:
* <code>scripts-repo/pyinfra-proxmox-webui/app.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/deploys/create_vm.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/lib/proxmox_ssh.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/systemd/pyinfra-webui.service</code>
* <code>scripts-repo/pyinfra-proxmox-webui/proxy01-bot-pyinfra-location.conf.example</code>
* <code>scripts-repo/pyinfra-proxmox-webui/.env.example</code>

Runtime:
* <code>/opt/pyinfra-webui</code>
* <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* <code>/etc/systemd/system/pyinfra-webui.service</code>
* <code>/var/lib/pyinfra-webui</code>

== Esempio ragionato di environment file ==
Usare placeholder, non segreti reali:

<syntaxhighlight lang="ini">
APP_HOST=0.0.0.0
APP_PORT=18180
APP_BASE_PATH=/pyinfra
APP_TOKEN=CHANGEME
APP_SECRET_KEY=CHANGEME
APP_STATE_DIR=/var/lib/pyinfra-webui

PROXMOX_SSH_HOST=PROXMOX_HOST
PROXMOX_SSH_PORT=22
PROXMOX_SSH_USER=root
PROXMOX_SSH_PASS=CHANGEME

PROXMOX_IMAGE=/var/lib/vz/template/iso/noble-server-cloudimg-amd64.img
PROXMOX_STORAGE=local
PROXMOX_CLOUDINIT_STORAGE=local
PROXMOX_BRIDGE=vmbr1
PROXMOX_GATEWAY=172.16.1.1
PROXMOX_CPU_TYPE=x86-64-v2-AES
PROXMOX_CIUSER=ubuntu
PROXMOX_CIPASSWORD=CHANGEME
PROXMOX_CICUSTOM_USER=local:snippets/gazzi-ubuntu-user.yaml

LDAP_URI=ldap://LDAP_HOST:389
LDAP_USER_DN_TEMPLATE=uid={username},ou=People,dc=gazzi,dc=local
</syntaxhighlight>

== Cosa significano le variabili ==
* <code>APP_HOST</code> e <code>APP_PORT</code>: bind locale del servizio Flask
* <code>APP_BASE_PATH</code>: prefisso usato quando l'app sta dietro reverse proxy su <code>/pyinfra</code>
* <code>APP_TOKEN</code>: token opzionale per protezione addizionale API
* <code>APP_SECRET_KEY</code>: chiave sessione Flask
* <code>APP_STATE_DIR</code>: directory per log e stato job
* <code>PROXMOX_*</code>: connessione e default di provisioning
* <code>LDAP_*</code>: endpoint e template DN per login utente

== Reverse proxy ==
Snippet di riferimento:
<syntaxhighlight lang="nginx">
location = /pyinfra {
return 301 /pyinfra/;
}

location /pyinfra/ {
proxy_pass http://BOT_GAZZI_LOCAL:18180/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Prefix /pyinfra;
proxy_redirect off;
}
</syntaxhighlight>

== Service ==
<syntaxhighlight lang="ini">
[Unit]
Description=Pyinfra Proxmox Web UI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pyinfraweb
Group=pyinfraweb
WorkingDirectory=/opt/pyinfra-webui
EnvironmentFile=/etc/pyinfra-webui/pyinfra-webui.env
ExecStart=/opt/pyinfra-webui/venv/bin/python /opt/pyinfra-webui/app.py
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

== Deploy iniziale ==
<syntaxhighlight lang="bash">
sudo mkdir -p /opt/pyinfra-webui /etc/pyinfra-webui /var/lib/pyinfra-webui
sudo chown -R pyinfraweb:pyinfraweb /opt/pyinfra-webui /var/lib/pyinfra-webui

cd /opt/pyinfra-webui
python3 -m venv venv
./venv/bin/pip install -U pip
./venv/bin/pip install -r requirements.txt

sudo install -m 0644 systemd/pyinfra-webui.service /etc/systemd/system/pyinfra-webui.service
sudo systemctl daemon-reload
sudo systemctl enable --now pyinfra-webui.service
</syntaxhighlight>

== Aggiornamento ==
<syntaxhighlight lang="bash">
cd /opt/pyinfra-webui
./venv/bin/pip install -r requirements.txt
sudo systemctl restart pyinfra-webui.service
</syntaxhighlight>

== Verifiche rapide ==
Applicative:
<syntaxhighlight lang="bash">
curl -I https://bot.gazzi.net/pyinfra/
curl -sS http://127.0.0.1:18180/api/health
</syntaxhighlight>

Service:
<syntaxhighlight lang="bash">
systemctl status pyinfra-webui.service
journalctl -u pyinfra-webui.service -n 100 --no-pager
</syntaxhighlight>

Funzionali:
* test login LDAP
* test bridge disponibili
* test VLAN disponibili
* test validazione bridge + VLAN
* test ricerca VMID libero
* test provisioning di una VM reale o di test

== Esempio di percorso reale ==
Caso semplice:
* rete in DHCP
* bridge scelto manualmente
* nessuna VLAN
* VM avviata subito

Caso avanzato:
* rete statica
* bridge scelto da lookup
* VLAN scelta da lookup
* VMID trovato automaticamente
* utente iniziale definito dall'operatore

== Sicurezza ==
Punti importanti:
* non mettere segreti in wiki o Git
* usare sempre HTTPS sul path pubblico
* il job parte solo a richiesta dell'utente autenticato
* la UI accetta un solo job alla volta per ridurre collisioni banali
* lo snippet cloud-init viene rimosso dopo il primo boot solo se la VM parte subito

== Limiti noti ==
* se <code>start_after_create=false</code>, lo snippet cloud-init resta finche la VM non completa il primo avvio
* la validazione VLAN dipende da cio che Proxmox espone in quel momento
* la pagina non sostituisce un orchestratore completo multi-tenant: e un ingresso operativo controllato

== Dove leggere il codice ==
Per la spiegazione dettagliata:
* [[Pyinfra/Implementazione deploy VM linea per linea]]

Per gli esempi generali:
* [[Esempi Pyinfra]]

Esempi Pyinfra

2026-03-29T18:51:29Z

Maintenance script: Espansione esempi Pyinfra con casi base e avanzati

Pyinfra

2026-03-29T18:51:29Z

Maintenance script: Espansione pagina Pyinfra con struttura umana e link di approfondimento

__NOTOC__
= Pyinfra =

'''Pyinfra''' in GazziNet va letto su due livelli:
* come strumento generale di automazione scritto in Python
* come implementazione concreta gia pubblicata su <code>bot.gazzi.net/pyinfra/</code> per creare VM Proxmox via browser

Questa pagina principale e pensata per una persona umana che vuole capire rapidamente:
* che cosa fa pyinfra
* quando usarlo
* dove trovare esempi semplici e avanzati
* dove trovare il runbook reale della web UI pubblicata
* dove trovare la spiegazione tecnica dell'implementazione del deploy automatico VM

I dettagli sensibili non vanno messi in wiki. Password, token, cookie, backend privati e dump runtime restano fuori dalla documentazione pubblica o semi-pubblica.

== In una frase ==
Pyinfra e un motore di automazione che usa Python per descrivere inventory, logica e operazioni di deploy in modo piu programmabile rispetto ai playbook puramente YAML.

== Quando ha senso usarlo ==
Pyinfra e adatto quando:
* vuoi tenere deploy e configurazioni in Git
* preferisci Python per logica, condizioni e riuso
* devi automatizzare server Linux, homelab o ambienti interni
* vuoi una separazione chiara tra form di input, validazione e runner di provisioning

Pyinfra e meno adatto quando:
* il team vuole solo file dichiarativi molto semplici
* nessuno vuole mantenere codice Python
* l'automazione deve essere totalmente guidata da un pannello visuale gia pronto

== Concetti base ==
Tre idee utili da capire subito:

=== 1. Inventory ===
L'inventory descrive i target: host, gruppi e dati associati.

=== 2. Operations ===
Le operations descrivono cosa deve essere applicato ai target, oppure uno stato che vuoi rendere vero.

=== 3. Esecuzione ===
Pyinfra legge inventory e dati, prepara l'ordine delle operazioni, si connette ai target ed esegue le modifiche.

== Nel caso GazziNet ==
Su GazziNet pyinfra non e stato usato come esercizio teorico. E stato integrato in una soluzione completa:
* UI pubblica: <code>https://bot.gazzi.net/pyinfra/</code>
* autenticazione: LDAP
* runner: <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* target: Proxmox
* risultato: creazione controllata di VM con parametri espliciti

== Percorso consigliato di lettura ==
Se parti da zero:
# [[Esempi Pyinfra]]
# [[Pyinfra/Deploy automatico VM Proxmox]]
# [[Pyinfra/Implementazione deploy VM linea per linea]]

Se vuoi solo usare la piattaforma pubblicata:
# [[Pyinfra/Deploy automatico VM Proxmox]]

Se vuoi capire il codice:
# [[Pyinfra/Implementazione deploy VM linea per linea]]

== Mappa delle pagine ==
* [[Esempi Pyinfra]]
Guida pratica con esempi base e avanzati di pyinfra.
* [[Pyinfra/Deploy automatico VM Proxmox]]
Runbook umano della web UI pubblicata su bot.gazzi.net.
* [[Pyinfra/Implementazione deploy VM linea per linea]]
Spiegazione tecnica del codice che realizza il deploy automatico di VM.
* [[Confronto Ansible vs Pyinfra]]
Confronto generale di approccio.
* [[Installazione Pyinfra su Fedora]]
Installazione CLI in ambiente Fedora.

== Esempio minimo per capire la sintassi ==
Inventory:
<syntaxhighlight lang="python">
web_servers = [
"web-01.example.net",
"web-02.example.net",
]
</syntaxhighlight>

Deploy:
<syntaxhighlight lang="python">
from pyinfra.operations import server

server.shell(
name="Show uptime",
commands=["uptime"],
)
</syntaxhighlight>

Esecuzione:
<syntaxhighlight lang="bash">
pyinfra inventory.py deploy.py
</syntaxhighlight>

== Idea chiave ==
Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:
* raccoglie i parametri
* valida input e rete
* crea un job locale

Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.

Questa separazione aiuta a mantenere il flusso leggibile:
* frontend e login
* validazione e stato job
* runner pyinfra
* helper Proxmox

== Regole documentali per questa area ==
La wiki deve contenere:
* spiegazioni umane
* runbook
* esempi
* struttura dei file
* procedure di verifica

La wiki non deve contenere:
* password
* token
* cookie di sessione
* segreti runtime
* dump completi di backend interni

== Riferimenti esterni ==
* [https://pyinfra.com/ Sito ufficiale]
* [https://docs.pyinfra.com/en/3.x/ Documentazione ufficiale]
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica WordPress]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]

== Repository ==
Sorgente versionata in:
* <code>scripts-repo/pyinfra-proxmox-webui/</code>

Pagine wiki versionate nello stesso repository:
* <code>scripts-repo/pyinfra-proxmox-webui/wiki/</code>

Pyinfra

2026-03-29T18:43:35Z

Maintenance script: Aggiornamento

__NOTOC__
= Pyinfra =

'''Pyinfra''' in GazziNet non e solo una pagina teorica: al 2026-03-29 e stato usato per pubblicare una web UI operativa che consente di creare VM Proxmox via browser, con autenticazione LDAP e job eseguiti on demand.

Questa pagina raccoglie il runbook sintetico della soluzione realmente messa in esercizio, con focus su deploy, configurazione, uso e verifiche. I dettagli sensibili restano fuori dalla wiki e vanno tenuti nei file runtime dedicati.

== Cosa e stato realizzato ==
* UI pubblica su <code>https://bot.gazzi.net/pyinfra/</code>
* autenticazione LDAP prima dell'accesso alla form
* runner <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* provisioning VM su Proxmox via SSH e comandi <code>qm</code>
* scelta di CPU, RAM, disco, bridge, VLAN, DHCP o IP statico
* scelta di utente e password iniziali della VM
* pulsante per trovare il primo VMID libero a partire da <code>100</code>
* lookup bridge e VLAN direttamente dal nodo Proxmox
* validazione preventiva della coppia <code>bridge + vlan</code>
* cleanup dello snippet cloud-init dopo il primo boot se la VM parte subito

== Architettura logica ==
Flusso sintetico:
# utente apre <code>bot.gazzi.net/pyinfra/</code>
# Nginx su <code>proxy01</code> inoltra verso il servizio su <code>bot.gazzi.local</code>
# l'app Flask autentica l'utente via LDAP
# la UI crea un job locale <code>pyinfra</code>
# il job usa SSH verso Proxmox ed esegue <code>qm create</code> / <code>qm set</code>
# se richiesto, la VM parte subito e viene atteso il completamento di <code>cloud-init</code>

== Parametri gestiti dalla UI ==
* VMID
* nome VM
* utente amministrativo iniziale
* password iniziale
* CPU
* RAM
* disco
* rete: DHCP o IP statico
* bridge Proxmox
* VLAN Proxmox
* gateway
* CIDR
* avvio automatico della VM a fine creazione

Nota pratica:
* se e selezionato '''DHCP''', i campi IP statici vengono disabilitati
* se si usa rete '''statica''', IP, gateway e CIDR diventano obbligatori

== File principali ==
Sorgenti versionati:
* <code>scripts-repo/pyinfra-proxmox-webui/app.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/lib/proxmox_ssh.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/deploys/create_vm.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/systemd/pyinfra-webui.service</code>
* <code>scripts-repo/pyinfra-proxmox-webui/proxy01-bot-pyinfra-location.conf.example</code>
* <code>scripts-repo/pyinfra-proxmox-webui/.env.example</code>

Runtime:
* working directory: <code>/opt/pyinfra-webui</code>
* environment file: <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* service systemd: <code>/etc/systemd/system/pyinfra-webui.service</code>
* state dir: <code>/var/lib/pyinfra-webui</code>

== Esempio environment file ==
Non inserire password o token nella wiki. Usare placeholder e valorizzare i segreti solo nel file runtime.

<syntaxhighlight lang="ini">
APP_HOST=0.0.0.0
APP_PORT=18180
APP_BASE_PATH=/pyinfra
APP_TOKEN=CHANGEME
APP_SECRET_KEY=CHANGEME
APP_STATE_DIR=/var/lib/pyinfra-webui

PROXMOX_SSH_HOST=PROXMOX_HOST
PROXMOX_SSH_PORT=22
PROXMOX_SSH_USER=root
PROXMOX_SSH_PASS=CHANGEME

PROXMOX_IMAGE=/var/lib/vz/template/iso/noble-server-cloudimg-amd64.img
PROXMOX_STORAGE=local
PROXMOX_CLOUDINIT_STORAGE=local
PROXMOX_BRIDGE=vmbr1
PROXMOX_GATEWAY=172.16.1.1
PROXMOX_CPU_TYPE=x86-64-v2-AES
PROXMOX_CIUSER=ubuntu
PROXMOX_CIPASSWORD=CHANGEME
PROXMOX_CICUSTOM_USER=local:snippets/gazzi-ubuntu-user.yaml

LDAP_URI=ldap://LDAP_HOST:389
LDAP_USER_DN_TEMPLATE=uid={username},ou=People,dc=gazzi,dc=local
</syntaxhighlight>

== Service systemd ==
<syntaxhighlight lang="ini">
[Unit]
Description=Pyinfra Proxmox Web UI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pyinfraweb
Group=pyinfraweb
WorkingDirectory=/opt/pyinfra-webui
EnvironmentFile=/etc/pyinfra-webui/pyinfra-webui.env
ExecStart=/opt/pyinfra-webui/venv/bin/python /opt/pyinfra-webui/app.py
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

== Reverse proxy ==
Snippet Nginx di riferimento:

<syntaxhighlight lang="nginx">
location = /pyinfra {
return 301 /pyinfra/;
}

location /pyinfra/ {
proxy_pass http://BOT_GAZZI_LOCAL:18180/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Prefix /pyinfra;
proxy_redirect off;
}
</syntaxhighlight>

== Deploy o aggiornamento ==
Sequenza minima lato host applicativo:

<syntaxhighlight lang="bash">
sudo mkdir -p /opt/pyinfra-webui /etc/pyinfra-webui /var/lib/pyinfra-webui
sudo chown -R pyinfraweb:pyinfraweb /opt/pyinfra-webui /var/lib/pyinfra-webui

cd /opt/pyinfra-webui
python3 -m venv venv
./venv/bin/pip install -U pip
./venv/bin/pip install -r requirements.txt

sudo install -m 0644 systemd/pyinfra-webui.service /etc/systemd/system/pyinfra-webui.service
sudo systemctl daemon-reload
sudo systemctl enable --now pyinfra-webui.service
</syntaxhighlight>

Poi:
* copiare o aggiornare i file dell'app dentro <code>/opt/pyinfra-webui</code>
* aggiornare <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* riavviare il servizio

Comandi utili:
<syntaxhighlight lang="bash">
sudo systemctl restart pyinfra-webui.service
sudo systemctl status pyinfra-webui.service
journalctl -u pyinfra-webui.service -n 100 --no-pager
curl -sS http://127.0.0.1:18180/api/health
</syntaxhighlight>

== Comportamento del provisioning ==
La UI raccoglie i parametri e avvia un job che:
* verifica che il VMID non esista gia
* crea la VM cloud-init con <code>qm create</code> e <code>qm set</code>
* configura <code>net0</code> con bridge ed eventuale tag VLAN
* imposta <code>ipconfig0</code> in DHCP o statico
* genera uno snippet cloud-init per creare l'utente richiesto con sudo
* opzionalmente avvia la VM
* se la VM viene avviata subito, aspetta guest agent e <code>cloud-init status --wait</code>
* rimuove lo snippet cloud-init dopo il primo boot

== Sicurezza ==
Regole da mantenere:
* non scrivere in wiki password, token, cookie o dump di sessione
* non copiare in Git segreti o backend interni inutili
* tenere i segreti in <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* usare HTTPS sul reverse proxy pubblico
* mantenere il controllo umano: il job parte solo a richiesta dell'utente autenticato

Nota importante:
* se <code>start_after_create=false</code>, lo snippet cloud-init non puo essere rimosso subito e va pulito dopo il primo avvio completato

== API utili ==
Endpoint interni esposti dall'app:
* <code>/api/health</code>
* <code>/api/jobs</code>
* <code>/api/jobs/create-vm</code>
* <code>/api/network/bridges</code>
* <code>/api/network/vlans</code>
* <code>/api/network/validate</code>
* <code>/api/proxmox/free-vmid</code>

== Verifiche rapide ==
Verifiche applicative:
<syntaxhighlight lang="bash">
curl -I https://bot.gazzi.net/pyinfra/
curl -sS http://127.0.0.1:18180/api/health
</syntaxhighlight>

Verifiche systemd:
<syntaxhighlight lang="bash">
systemctl status pyinfra-webui.service
journalctl -u pyinfra-webui.service -n 50 --no-pager
</syntaxhighlight>

Verifiche Proxmox lato UI:
* test lookup bridge
* test lookup VLAN
* test validazione <code>bridge + vlan</code>
* test ricerca VMID libero

== Problemi noti ==
* il <code>guid</code> di WordPress o altri metadati editoriali non hanno relazione con questa automazione
* il cleanup automatico dello snippet cloud-init dipende dal primo boot e dalla disponibilita del guest agent
* la VLAN viene validata in base a cio che il nodo Proxmox espone al momento del controllo

== Riferimenti collegati ==
* [[Tips Automation]]
* [[Esempi Pyinfra]]
* [[Confronto Ansible vs Pyinfra]]
* [[Installazione Pyinfra su Fedora]]
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica su WordPress]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]

== Repository ==
Sorgente versionata:
* <code>scripts-repo/pyinfra-proxmox-webui/</code>

Questa pagina wiki va tenuta come documentazione operativa ad alto livello e runbook sintetico. Segreti e dettagli sensibili restano fuori dalla wiki.