Proxmox-Dokumentation: So hältst du dein Homelab nachvollziehbar

Wer ein Homelab betreibt, kennt den Moment: Man öffnet die Proxmox-Oberfläche nach ein paar Monaten und sieht eine VM mit dem Namen „test", von der niemand mehr weiß, warum sie existiert. Beim Aufsetzen war alles klar. Man wusste, warum die MTU auf dem zweiten Interface 9000 beträgt, welcher Container die Reverse-Proxy-Konfiguration trägt und warum die Backup-Retention genau so gesetzt ist. Monate und ein paar Upgrades später sind diese Details nicht mehr offensichtlich.

Dieser Text beantwortet eine konkrete Aufgabe: Wie du die Dokumentation für dein Proxmox-Setup so organisierst, dass sie dich Monate später noch rettet, wenn etwas kaputt ist. Der Kern der Antwort ist weniger ein bestimmtes Werkzeug als eine Haltung. Dokumentiere das „Warum" dort, wo das „Was" ohnehin schon liegt. Halte es in Klartext statt in einer Datenbank. Und prüfe es mit einem Test, der wehtut: einer Wiederherstellung, bei der man so tut, als wäre alles weg.

Konkret bedeutet das drei Ebenen, die im Folgenden nacheinander aufgebaut werden. Erstens die Konfiguration, die Proxmox ohnehin speichert und die du nur lesbar machen musst. Zweitens ein Notizfeld pro VM oder Container für den Zweck der Maschine. Drittens ein Git-Repository mit Markdown für alles, was Proxmox nicht selbst weiß: Abhängigkeiten, Entscheidungen und die Wiederherstellung.

Kurzantwort

Wie du dein Proxmox-Homelab so dokumentierst, dass du Monate später noch verstehst, was du gebaut hast – Notizen, Konfiguration und Restore-Test. Kurz gesagt: ki tools praxis ist vor allem dann relevant, wenn du schnell verstehen willst, was konkret dahinter steckt, welche Grenzen es gibt und welche Entscheidung daraus folgt. Die Details, Quellen und Einschränkungen stehen in den folgenden Abschnitten.

Was Proxmox schon für dich festhält

Die gute Nachricht zuerst: Ein Teil deiner Dokumentation existiert bereits, und zwar in Klartext. Proxmox VE speichert nahezu seine gesamte Konfiguration als Dateien in einem eigenen Dateisystem, dem Proxmox Cluster File System, kurz pmxcfs. Es ist unter /etc/pve eingehängt und wird in einem Cluster über corosync in Echtzeit auf alle Nodes repliziert 1.

Jede VM hat ihre eigene Konfigurationsdatei. Für eine VM mit der ID 100 liegt sie unter /etc/pve/nodes/<node>/qemu-server/100.conf, für einen Container entsprechend unter /etc/pve/nodes/<node>/lxc/100.conf 1. Diese Dateien sind keine versteckte Datenbank, sondern lesbarer Text: Festplatten, Netzwerkgeräte, CPU- und Speicherwerte, die Startreihenfolge. Wer wissen will, wie eine Maschine tatsächlich konfiguriert ist, muss nicht durch die GUI klicken:

cat /etc/pve/nodes/$(hostname)/qemu-server/100.conf

Der Wert dieser Dateien für die Dokumentation liegt darin, dass sie immer den Ist-Zustand zeigen, nicht einen Stand von vor drei Monaten. Sie lügen nicht, weil Proxmox sie selbst pflegt. Was sie nicht enthalten, ist der Grund für eine Einstellung. Dass die MTU 9000 beträgt, steht dort. Warum sie 9000 beträgt, steht nirgends.

Damit ist die erste Ebene klar: Bevor du irgendetwas Neues aufschreibst, mach dir bewusst, dass die Konfiguration bereits dokumentiert ist. Du musst sie nur kennen und sichern, nicht duplizieren.

Das Notizfeld: die kürzeste Dokumentation, die es gibt

Jede VM und jeder Container hat in Proxmox ein Beschreibungsfeld. Es erscheint in der Weboberfläche im Reiter „Summary" und ist der schnellste Ort, um festzuhalten, was eine Maschine tut und warum sie existiert. In der GUI klickt man in das Feld „Notes" und tippt direkt hinein.

Dasselbe geht über die Kommandozeile, und genau das macht es automatisierbar:

qm set 100 --description "Pi-hole DNS fürs LAN, VLAN 20, IP 10.0.20.2"

Proxmox speichert diese Beschreibung nicht irgendwo abseits, sondern als Kommentar in derselben Konfigurationsdatei 2. Die manuelle Beschreibung zur Option lautet im Proxmox-Handbuch wörtlich, sie werde in der Summary der Weboberfläche angezeigt und als Kommentar in der Konfigurationsdatei gespeichert 2. Das hat zwei Folgen, die für die Dokumentation entscheidend sind. Erstens wandert die Notiz mit, wenn man die Konfigurationsdatei sichert oder auf einen anderen Node verschiebt. Zweitens ist sie Teil des Backups: Proxmox-Vollbackups enthalten immer die VM- beziehungsweise Container-Konfiguration samt aller Daten 3.

Für einen Container heißt der Befehl entsprechend pct set 100 --description "...". Die Eigenschaft funktioniert für QEMU-VMs und LXC-Container gleich, nur das Werkzeug davor unterscheidet sich.

Was gehört in dieses Feld? Die Antwort auf die Frage, die man sich in sechs Monaten stellt: Was ist das, und wovon hängt es ab? Ein Zweizeiler reicht. Funktion, Netzwerk, die wichtigste Abhängigkeit. Eine gute Notiz beantwortet drei Punkte und lässt den Rest weg:

Pi-hole – DNS und Werbeblocker fürs gesamte LAN
Netz: VLAN 20, statisch 10.0.20.2, Gateway 10.0.20.1
Hängt ab von: nichts, muss vor allen anderen Containern starten

Wer es ausführlicher mag, kann eine kleine Systemübersicht einfügen, etwa CPU, Speicher und die zuletzt eingespielte Kernel-Version. Das Feld ist kein Wiki, aber es ist der Ort, an dem die Antwort auf „Warum existiert diese VM?" am nächsten an der VM selbst liegt. Genau diese Nähe ist sein Vorteil: Die Notiz ist da, wo man hinschaut, wenn man sich die Maschine anschaut.

ki tools praxis – Illustration 2

Warum eine zweite Ebene nötig ist

Die Konfigurationsdatei beantwortet das „Was", das Notizfeld beantwortet knapp das „Warum". Beides zusammen deckt den Alltag ab: nachschlagen, welche IP eine Maschine hat oder welchen Zweck sie erfüllt. Was beide nicht abdecken, sind die Zusammenhänge, die quer über Maschinen hinweg laufen.

Ein Beispiel: Ein Container läuft nur, weil ein anderer Container die Datenbank bereitstellt, die wiederum auf einem NFS-Share liegt, der auf dem NAS mit einer bestimmten Berechtigung eingerichtet ist. Diese Kette steht in keiner einzelnen Konfigurationsdatei. Sie existiert nur in deinem Kopf, solange du sie nicht aufschreibst. Und genau diese Art Wissen geht als Erstes verloren, gerade nach Upgrades, bei denen man Einstellungen ändert, ohne die alte Begründung mitzunehmen.

Der zweite Fall ist der Ernstfall: Alles ist aus, und du musst von Null wiederherstellen. In dem Moment brauchst du keine Erklärung der Architektur, sondern eine Reihenfolge. Was zuerst, was als Zweites, wo liegen die Backups, welche Schlüssel und Passwörter gehören wohin. Das ist kein Wissensproblem, sondern ein Ablaufproblem, und es braucht einen eigenen Ort.

Deshalb ist die zweite Ebene nicht „noch mehr Notizen", sondern ein getrenntes Dokument für die Dinge, die Proxmox nicht selbst weiß. Abhängigkeiten. Entscheidungen. Wiederherstellung. Diese drei Dinge haben gemeinsam, dass sie sich nicht aus einer einzelnen Konfigurationsdatei ablesen lassen und dass sie genau dann gebraucht werden, wenn der bequeme Weg über die Oberfläche nicht mehr funktioniert.

Ein Ordner, ein Git-Repository

Die einfachste Form, die langfristig funktioniert, ist ein Git-Repository mit Markdown-Dateien. Das ist kein besonderes Werkzeug, sondern der kleinste gemeinsame Nenner: Klartext, versionskontrolliert, offline lesbar und mit jedem Editor zu öffnen 5.

Der Vorteil gegenüber einem selbst gehosteten Wiki ist genau der, der in der Praxis zählt. Wenn dein Server komplett ausfällt, ist ein Wiki, das auf diesem Server läuft, vermutlich mit ausgefallen. Ein Markdown-Repository liegt dagegen zusätzlich in einem entfernten Git-Repository und ist vom Handy aus lesbar, auch wenn zu Hause nichts mehr läuft 5.

Eine Struktur, die sich bewährt hat, trennt nach Zweck statt nach Technik:

homelab-docs/
  README.md              # Übersicht und Schnelleinstieg
  netzwerk/
    topologie.md         # Netzplan und VLANs
    ip-tabelle.md        # statische IP-Zuordnung
    firewall.md          # Firewall-Regeln
  dienste/
    inventar.md          # was wo läuft
    proxmox.md           # Cluster- und Node-Notizen
  ablauf/
    backup-restore.md    # Wiederherstellung Schritt für Schritt
    neue-vm.md           # Checkliste für neue Maschinen
  diagramme/
    netzwerk.drawio      # editierbare Netzpläne

Die drei Dateien, die man als Minimum pflegen sollte, sind die Netzwerkkarte samt IP-Tabelle, das Service-Inventar und ein Recovery-Runbook 5. Sie decken die drei Fragen ab, die ohne Dokumentation am schlimmsten fehlen: „Wo finde ich etwas im Netz?", „Was läuft wovon abhängig?" und „Alles ist kaputt, wie komme ich zurück?".

Die Gewohnheit ist der schwierigste Teil. Wer sich vornimmt, „später zu dokumentieren", tut es nicht. Notizen entstehen am besten während des Bauens, nicht danach: ein Editor neben dem Terminal, in den man schreibt, was man gerade ändert und warum. Rauer Text ist besser als keiner. Poliert werden kann später, oder auch nicht 5.

Was hineingehört und was nicht

Nicht alles gehört in die eigene Doku. Ein nützlicher Kompass ist das Diátaxis-Framework, das technische Dokumentation in vier Modi unterteilt: Tutorials, How-to-Guides, Referenz und Erklärung. Jeder Modus beantwortet ein anderes Bedürfnis, nämlich lernen, erledigen, nachschlagen oder verstehen 4. Der Wert für ein Homelab liegt weniger in den vier Schubladen als in der Grundidee dahinter: Ein Dokument, das „wie" und „warum" mischt, wird für beide Zwecke schlechter.

Übertragen auf Proxmox heißt das: Die Referenz, also die exakten Einstellungen, liegt bereits in /etc/pve und im Notizfeld. Das eigene Markdown-Repository ist für die Erklärung und die Anleitung zuständig, also dafür, warum eine Entscheidung so getroffen wurde und wie man einen Ablauf durchführt. Wer versucht, jede Einstellung zusätzlich ins Wiki zu kopieren, pflegt zwei Quellen, und eine davon wird veralten 5.

Als Faustregel hilft der Test „ändert es sich, wenn sich die Konfiguration ändert?". Was direkt aus der Konfiguration ableitbar ist, gehört nicht dupliziert. Was unabhängig von jeder einzelnen Datei gültig bleibt, gehört aufgeschrieben. Eine Architekturentscheidung überlebt einzelne Versionen; die Liste der offenen Ports eines Containers nicht. Die Entscheidung gehört ins Repository, die Portliste nicht, weil Proxmox sie schon kennt.

Die vier Modi lassen sich im Alltag konkret zuordnen. Die Checkliste „neue VM aufsetzen" ist ein How-to, also eine Anleitung mit sichtbarem Ergebnis pro Schritt. Die VLAN- und IP-Tabelle ist Referenz, eine reine Liste ohne Erklärung. Der Absatz „warum wir für den Speicher ZFS mit zwei SSDs statt einer einzelnen großen Platte gewählt haben" ist Erklärung. Diese Trennung klingt nach Theorie, verhindert aber den häufigsten Fehler: ein einziges Dokument, das gleichzeitig Anleitung, Nachschlagewerk und Begründung sein will und am Ende keines davon richtig ist 4.

Veraltete Dokumentation ist manchmal schlimmer als gar keine, weil sie den Anschein erweckt, sie sei aktuell 5. Ein Review im Quartal, bei dem man durch das Inventar geht, Aktualisierungen vornimmt und Streichungen einträgt, hält den Bestand ehrlich. Das ist keine Nebensache, sondern Teil der Pflege, genauso wie das Einspielen von Updates.

Der Test, der zählt: das Restore

Dokumentation beweist ihren Wert erst in dem Moment, in dem sie dich durch eine Wiederherstellung führt. Deshalb ist der einzige verlässliche Test der, bei dem man so tut, als wäre alles weg.

Der Ablauf ist konkret. Man erstellt mit vzdump ein Vollbackup einer VM, zum Beispiel:

vzdump 100 --mode snapshot --storage backup --compress zstd

Proxmox-Backups sind immer Vollbackups, die Konfiguration und Daten gemeinsam enthalten 3. Beim Backup-Job lässt sich zusätzlich eine Notiz hinterlegen, die zusammen mit dem Backup gespeichert wird 3. Anschließend stellt man das Archiv auf einem Testsystem oder in einer leeren Umgebung wieder her und geht dabei ausschließlich das eigene Recovery-Runbook durch. Für die Wiederherstellung aus der Kommandozeile gibt es qmrestore, für Container pct restore.

Wenn das Runbook dabei versagt, ist das kein Misserfolg des Tests, sondern der Zweck des Tests. Lücken zeigen sich nicht beim Schreiben, sondern beim Durchführen. Ein fehlender Schlüssel. Eine vergessene Reihenfolge. Ein Dienst, der vor einem anderen hochgefahren werden muss. All das steht nicht in der Konfiguration und taucht nur auf, wenn man es wirklich tut.

Der Test ist erst beendet, wenn die wiederhergestellte Maschine nicht nur existiert, sondern antwortet. Bei einem DNS-Container heißt das: ein paar Anfragen gegen ihn stellen und prüfen, dass sie aufgelöst werden. Bei einem Dienst mit Weboberfläche: die Seite aufrufen und schauen, dass sie nicht nur einen Fehler zeigt. Erst dieses Nachprüfen macht aus dem Runbook eine Anleitung, der man im Ernstfall vertraut, statt einer Sammlung von Schritten, die in der Theorie funktionieren müssten.

Zwei Dinge sollte man zusätzlich sichern. Zum einen die pmxcfs-Datenbank unter /var/lib/pve-cluster/config.db, die man bei einem Hardwareausfall auf einen neuen Host übertragen kann, um die Cluster-Konfiguration mitzunehmen 1. Zum anderen die Sicherungswerkzeuge selbst: Wenn das Runbook beschreibt, wie man mit Proxmox Backup Server wiederherstellt, sollte dieser Server nicht auf genau der Hardware liegen, die gerade ausgefallen ist.

Der Restore-Test ist der Unterschied zwischen einer Dokumentation, die sich gut liest, und einer, die funktioniert. Er kostet Zeit, aber er ist der einzige Beleg dafür, dass die Notizen nicht nur gesammelt, sondern tatsächlich nutzbar sind.

KI-Tools selbst hosten und dabei dokumentieren

Ein wachsender Teil der Homelab-Praxis ist das Selbsthosten von KI-Modellen: lokale Modelle statt gehosteter Dienste, etwa über Ollama, llama.cpp oder vLLM in einer eigenen VM mit GPU-Passthrough. Für die Dokumentation ändert das zwei Dinge.

Erstens wird die Dokumentation wichtiger, nicht unwichtiger. Ein selbst gehostetes KI-Setup besteht aus mehr beweglichen Teilen als ein Abo: Modell-Dateien mit Versionsstand, Treiber, VRAM-Zuteilung, der Dienst, der das Modell lädt, und oft ein Reverse Proxy davor. Jeder dieser Teile lässt sich einzeln kaputt machen, und keiner davon lässt sich mit einem Klick neu installieren. Wer hier nur die Konfiguration speichert, aber nicht festhält, welches Modell warum ausgewählt wurde, steht beim nächsten Update vor demselben „Warum war das so?"-Problem wie bei jeder anderen VM. Insofern ist das Selbsthosten eines lokalen KI-Modells keine Ausnahme, sondern ein besonders gutes Beispiel dafür, warum die zweite Dokumentationsebene nötig ist.

Zweitens können lokale KI-Tools in der Praxis beim Dokumentieren helfen, wenn man ihre Grenze kennt. Ein lokales Modell kann aus einem Export der Konfigurationsdateien und der Shell-Historie einen brauchbaren Entwurf für ein Runbook oder ein Inventar erzeugen. Das ist eine echte Erleichterung, weil es das leere Blatt füllt und aus rohem Material eine erste Gliederung macht. Aber der Entwurf ist nicht die Wahrheit. Ein Modell kann eine Einstellung überzeugend falsch beschreiben, einen Pfad erfinden oder eine Abhängigkeit behaupten, die so nie existiert hat. Deshalb gilt für KI-unterstützte Dokumentation dieselbe Regel wie für jeden anderen Entwurf: gegen den Ist-Zustand prüfen, bevor es ins Repository geht.

Wer beides kombiniert, bekommt einen Ablauf, der sich selbst trägt. Das selbst gehostete Modell erzeugt den ersten Entwurf, der Mensch verifiziert die konkreten Werte gegen /etc/pve und das Notizfeld, und die geprüfte Fassung landet im Git-Repository. Die KI ist dann ein Werkzeug unter mehreren, kein Ersatz für das Nachsehen.

Ein Minimum, das trägt

Du brauchst kein perfektes System, sondern eines, das du tatsächlich benutzt. Ein unordentliches Markdown-Repository, das du aktuell hältst, ist wertvoller als ein aufwendig aufgesetztes Wiki, das seit sechs Monaten veraltet ist 5.

Der konkrete nächste Schritt ist klein und prüfbar: Lege das Repository an, fülle die drei Minimum-Dateien, schreibe für die wichtigste VM eine Beschreibung ins Notizfeld und führe einmal einen Restore-Test durch. Erst wenn dieser Test dich tatsächlich zurückbringt, ist die Dokumentation mehr als ein gutes Gefühl.

Was dieses Vorgehen nicht löst, ist die Pflege über die Zeit. Keine Konfigurationsdatei und kein Werkzeug hält die Gewohnheit aufrecht. Die bleibt eine bewusste Entscheidung beim nächsten Umbau: den Editor offen lassen und das „Warum" mitschreiben, statt es wieder nur im Kopf zu behalten.

Passende Produktrecherchen

Wenn du die praktische Seite vertiefen möchtest, findest du hier passende Suchpfade zum Vergleichen. Keine Kaufpflicht, keine Rangliste, sondern thematisch passende Produktrecherchen:

Hinweis: Als Amazon-Partner verdient kalika.de an qualifizierten Verkäufen. Für dich ändert sich der Preis nicht.

Quellen

[1] Proxmox Cluster File System (pmxcfs) – Proxmox VE Wiki

[2] qm.conf(5) – Proxmox VE Manual

[3] Backup and Restore – Proxmox VE Wiki

[4] Diátaxis – A systematic framework for technical documentation authoring

[5] Documenting Your Home Lab Setup Effectively – HomeLab Starter ki tools praxis – Illustration 3

Weiterführende Artikel

Entscheidungshilfe: Wann ist das sinnvoll?

Eher sinnvoll, wenn du ki tools praxis nicht nur als Nachricht lesen willst, sondern eine praktische Einordnung brauchst: Was ändert sich, wen betrifft es und welche nächsten Schritte sind realistisch?

Eher abwarten, wenn die Quellenlage noch dünn ist, wichtige technische Details fehlen oder der Nutzen nur aus Hersteller- oder Projektversprechen besteht. Dann ist Beobachten besser als vorschnelles Umstellen.

Worauf du achten solltest: konkrete Verfügbarkeit, nachvollziehbare Kosten, offene Einschränkungen, Sicherheits- oder Datenschutzfolgen und belastbare Quellen statt bloßer Ankündigungen.

Transparenzhinweis

Dieser Beitrag wurde mit Unterstützung künstlicher Intelligenz erstellt und automatisiert auf Quellen, Fakten und Qualitätskriterien geprüft.