Der Auslöser: ausgesperrt ohne Runbook

Es begann mit einer harmlosen Aufräumaktion: Ich löschte in einem Web-Interface einen Schwung alter Benachrichtigungen — viele Klicks in kurzer Zeit. Kurz darauf war ich ausgesperrt. Ein verhaltensbasiertes Intrusion-Prevention-System hatte die vielen schnellen Anfragen als Angriffsmuster gewertet und meine öffentliche IP-Adresse gebannt. SSH weg, Web weg.

Das Ärgerliche war nicht der Bann an sich — der war schnell erklärt. Das Ärgerliche war: Ich hatte keine auffindbare Anleitung, wie man ihn wieder löst. Der eine nötige Befehl existierte, irgendwo. Aber unter Zeitdruck, halb ausgesperrt, ist „existiert irgendwo" wertlos.

Die unbequeme Erkenntnis

Beim Nachdenken über eine Dokumentationslösung stolperte ich über eine unbequeme Wahrheit, die die ganze Werkzeugfrage umdreht:

Ein selbstgehostetes Wiki (egal welches) läuft auf demselben Server, hinter derselben Absicherung, die einen gerade aussperrt. Genau dann, wenn man die Anleitung „So entbanne ich mich" braucht, ist sie nicht erreichbar. Dasselbe gilt für jede Weboberfläche, die einen Login verlangt. Die einzige Variante, die im Ernstfall immer funktioniert, ist eine lokale Kopie auf dem eigenen Rechner — offline lesbar, ohne Server, ohne Login.

Kein neues Wiki: dieselben Dateien, drei Brillen

Die Regel Nummer eins in der IT lautet eigentlich: Führe kein neues System ein, wenn ein bestehendes die Aufgabe erfüllt. Ich hatte bereits einen Git-Server. Also wurde die Dokumentation zu dem, was sie sein sollte: ein Ordner mit Markdown-Dateien im Git. Keine neue Datenbank, kein neuer Container, keine zusätzliche Angriffsfläche, kein Lock-in.

Der Clou: ein und dieselben Dateien, gelesen durch drei Brillen — je nach Situation:

Situation	Werkzeug	Warum
Notfall, evtl. ausgesperrt/offline	Volltextsuche im Terminal (z. B. ripgrep)	Millisekunden, ohne Server, ohne Login, auf der lokalen Kopie
In Ruhe lesen, Diagramme ansehen	Die Weboberfläche des Git-Servers	Rendert Markdown und Diagramme hübsch im Browser
Suchen & Zusammenhänge sehen	Ein lokaler Markdown-Editor mit Graph-Ansicht	Zeigt Verknüpfungen zwischen Themen als Netz

Der Editor ist dabei nur eine Brille auf denselben Ordner — kein Server, jederzeit ersetzbar. Und weil alles Markdown ist, bin ich herstellerunabhängig: Der Inhalt lässt sich in Sekunden in ein anderes Werkzeug übernehmen.

Diagramme statt Prosa

„Zusammenhänge verstehen" gelingt mit Text nur mäßig. Deshalb liegen die Architektur-Kapitel als Diagramme direkt im Markdown — als Diagramm-Code (Mermaid), den sowohl die Git-Weboberfläche als auch der lokale Editor nativ rendern. Ein Diagramm im Text hat drei Vorteile gegenüber einem exportierten Bild:

• Es ist versioniert — Änderungen sind im Diff sichtbar.
• Es ist durchsuchbar — die Knoten sind Text.
• Es ist pflegbar — kein externes Zeichenprogramm nötig.

So entstanden fünf Kern-Diagramme: die Dienst-Landschaft, die Netz-Topologie, der Login-Fluss, die gestaffelten Sicherheitsschichten und die wichtigsten Datenflüsse.

Symptom-basierte Runbooks

Die eigentliche Lehre aus dem Aussperr-Vorfall: Man sucht im Ernstfall nicht nach der Ursache, sondern nach dem Symptom — nach dem, was man gerade sieht. Deshalb beginnt jedes Runbook mit einem einheitlichen, suchfreundlichen Kopf:

# Runbook: <Titel>
> SYMPTOM:    wie es sich anfühlt — „komme nicht mehr rein", „404", „Timeout"
> SCHNELL-FIX: der erste Griff / ein Befehl
> URSACHE:    Verweis auf die Tiefe

Damit findet eine Suche nach ausgesperrt oder banned sofort das richtige Dokument — offline, in Millisekunden. Das „So komme ich trotz Sperre wieder rein" (über das interne VPN oder die Server-Konsole des Anbieters) steht dort an erster Stelle. Genau die Lücke, die den ganzen Umbau ausgelöst hat, ist damit geschlossen.

Aufräumen statt anhäufen

Ein Dokumentationssystem ist nur so gut wie seine Ordnung. Über die Zeit hatten sich Dutzende Notizen im Projektwurzelverzeichnis angesammelt — datierte Momentaufnahmen, alte Fix-Berichte, überlappende Status-Dateien. Beim Umbau wanderten die veralteten in ein Archiv, die lebenden in eine klare Struktur. Wichtig dabei: nicht blind verschieben. Erst eine Mapping-Tabelle, dann versionsverwaltete Verschiebungen (die die Historie erhalten), dann ein automatischer Link-Check — damit kein Verweis ins Leere zeigt.

Fazit

Am Ende steht kein neues Werkzeug, sondern eine Haltung: Wissen als schlichte, versionierte Textdateien, die man durch die jeweils passende Brille betrachtet. Das ist robust, offline-fähig, herstellerunabhängig — und im Notfall genau dann verfügbar, wenn eine schicke Weboberfläche unerreichbar wäre.