L'homelab cresce un pezzo alla volta: una VM per provare un servizio, una regola del firewall aggiunta di sera, un disco sostituito in fretta. Dopo un anno, la configurazione esiste solo nella memoria di chi l'ha fatta, e la memoria non è affidabile. Il giorno in cui qualcosa si rompe, o in cui un familiare deve riavviare il router mentre sei fuori, la documentazione fa la differenza tra dieci minuti e un pomeriggio perso.
Cosa documentare
Non serve un manuale aziendale. Bastano poche categorie di informazioni, aggiornate con costanza.
Inventario dell'hardware
Per ogni dispositivo fisico:
- modello, numero di serie, data e luogo d'acquisto, scadenza della garanzia;
- componenti principali: CPU, RAM, dischi con numero di serie e posizione nello slot;
- indirizzo IP di gestione e indirizzo MAC;
- dove si trova fisicamente e a quale presa o UPS è collegato.
Rete
- elenco delle reti e delle VLAN con scopo, intervallo di indirizzi e gateway;
- piano di indirizzamento: quali indirizzi sono statici, quali assegnati dal DHCP, quali riservati;
- porte dello switch: cosa è collegato a ogni porta e su quale VLAN;
- regole del firewall più importanti, con il motivo per cui esistono.
Servizi
Per ogni servizio:
| Campo | Esempio |
|---|---|
| Nome e scopo | archivio fotografico di famiglia |
| Dove gira | VM «media» sull'host pve1 |
| Come si raggiunge | nome interno, porta, eventuale reverse proxy |
| Dove stanno i dati | percorso sul NAS, volume del container |
| Backup | quale job, ogni quanto, dove |
| Dipendenze | database, storage di rete, DNS locale |
| Aggiornamento | come si fa, cosa controllare prima |
Credenziali
La documentazione non contiene password. Indica solo dove si trovano: per esempio, la voce corrispondente nel gestore di password. Per le credenziali di emergenza, come la chiave di cifratura dei backup, vale la pena prevedere una copia stampata in un luogo sicuro.
Il runbook: istruzioni per il giorno peggiore
Un runbook è una procedura passo per passo per un'operazione specifica, scritta in modo che possa seguirla anche qualcuno che non conosce il sistema, o tu stesso fra un anno sotto stress. I runbook più utili in casa:
- ripristino completo dopo il guasto dell'host: reinstallazione dell'hypervisor, collegamento dello storage, ripristino delle VM dai backup, nell'ordine giusto;
- sostituzione di un disco guasto nel NAS o nel pool;
- cosa fare se manca Internet: quali dispositivi riavviare e in quale ordine, chi chiamare;
- rinnovo di certificati o chiavi con scadenza;
- istruzioni per i familiari: una pagina semplice, stampata, con le due o tre operazioni che possono fare da soli.
Un runbook vale solo se è stato provato. Nel mio lavoro lo verifico eseguendolo davvero almeno una volta, correggendo i passaggi che risultano ambigui.
Gli strumenti
File di testo in un repository
La soluzione più semplice e durevole: file Markdown in una cartella sotto Git. Si leggono con qualsiasi editor, si cercano con grep, conservano la cronologia delle modifiche. Se i file Compose e le configurazioni stanno nello stesso repository, documentazione e configurazione restano vicine.
Wiki self-hosted
Strumenti come BookStack o Wiki.js offrono un'interfaccia web, ricerca e organizzazione per capitoli. Sono comodi se più persone consultano la documentazione. Un rischio da non sottovalutare: se la wiki gira nell'homelab, il giorno del guasto non è raggiungibile. Serve un'esportazione periodica in un formato leggibile offline.
NetBox
NetBox è uno strumento open source nato per documentare reti e data center: rack, dispositivi, cavi, indirizzi IP, VLAN, circuiti. In un homelab può sembrare eccessivo, ma diventa utile quando il numero di indirizzi e porte cresce, perché funziona anche come IPAM, cioè gestione dello spazio di indirizzamento, ed evita di assegnare due volte lo stesso IP.
Schemi di rete
Un disegno vale più di molte righe. Strumenti di diagrammi come draw.io, disponibile anche in versione self-hosted, permettono di rappresentare router, switch, VLAN e host. Lo schema va salvato in un formato modificabile, non solo come immagine, altrimenti non verrà aggiornato.
Come tenerla aggiornata
La documentazione invecchia più in fretta dell'hardware. Alcune abitudini aiutano:
- aggiornare durante il lavoro, non dopo: una riga scritta mentre si configura costa meno di una ricostruzione a memoria;
- un registro delle modifiche, con data e breve descrizione di ogni intervento;
- generare automaticamente ciò che si può: elenchi di VM, indirizzi assegnati dal DHCP, versioni dei container;
- revisione periodica, per esempio ogni trimestre, confrontando la documentazione con la realtà.
Una copia fuori dall'homelab
La documentazione serve soprattutto quando l'homelab non funziona. Deve quindi esistere anche altrove: sul portatile, in un archivio cifrato su un altro dispositivo, e per le pagine essenziali su carta.
In sintesi
- Inventario di hardware, rete e servizi copre la maggior parte delle esigenze.
- Le password non vanno nella documentazione, solo il riferimento a dove si trovano.
- I runbook per ripristino, sostituzione dei dischi e mancanza di Internet vanno scritti e provati.
- File Markdown in Git sono la base più durevole; NetBox aiuta quando reti e indirizzi crescono.
- La documentazione deve essere consultabile anche quando l'homelab è fermo.
