homelab

Infrastruktur-Specs und Runbooks für das eigene Setup — Tailnet, VPS, CachyOS-Desktop, FritzBox.

Markdown ist Source of Truth, HTML wird parallel im alexle135.de-Editorial-Stil gepflegt. Versionierung über git, Auslieferung per Single-File-HTML an Kollegen und Dozenten.

Specs · Konvention · Lokal anzeigen · Spec weitergeben · Design-System · Lizenz

---

Status: Entwurf. Aktuell zwei Specs in v0.1.1 — Implementation steht aus. Repo ist öffentlich, deshalb keine echten IPs, Hostnames oder Secrets in den Specs — nur Platzhalter (${...}). Wer auf /ueber-mich neugierig ist: alexle135.de/ueber-mich.

Was hier liegt

Jeder Infrastruktur-Plan kommt zuerst als Markdown-Spec ins Repo, bevor auf den Maschinen etwas passiert. Die HTML-Version daneben rendert denselben Inhalt im editorial Dark-Theme von alexle135.de — zum Mitlesen im Browser oder als Single-File-HTML zum Verschicken.

Struktur

homelab/
├── index.html              Übersicht (HTML-Build der Specs)
├── assets/                 Design-Tokens, CSS, Fonts, Logo
│   ├── colors_and_type.css
│   ├── doc.css
│   ├── logo.jpg
│   └── fonts/
├── specs/                  Markdown + HTML pro Plan
│   └── YYYY-MM-DD-<slug>-design.{md,html}
└── tools/                  Hilfs-Skripte (z. B. Single-File-Build)

Konvention

• Markdown ist Source of Truth. HTML spiegelt den MD-Stand 1:1.
• Datei-Schema: YYYY-MM-DD-<slug>-design.md
• Frontmatter im MD: title, slug, version, status, date, author, scope, reading_time
• HTML referenziert ../assets/colors_and_type.css und ../assets/doc.css aus specs/

Lokal anzeigen

Statischer Ordner — kein Build, kein Server-Pflicht:

open index.html              # macOS

Für saubere Anker-Links über lokalen HTTP-Server:

python3 -m http.server 8000  # dann http://localhost:8000

Spec an Kollegen weitergeben (Single-File-HTML)

Eine Datei, alles inline — für E-Mail-Anhang, Slack-Upload oder USB:

python3 tools/build-singlefile.py specs/2026-05-20-tailnet-adblock-design.html
# → specs/2026-05-20-tailnet-adblock-design.standalone.html  (~450 KB)

CSS und Geist-Fonts werden base64-eingebettet. Fraunces (Display-Serif) bleibt über Google-Fonts-CDN bezogen — offline fällt es auf den Fallback-Stack (Iowan, Palatino, Georgia) zurück. Details in tools/README.md.

Die generierten *.standalone.html sind in .gitignore und werden nicht ins Repo committed. Auslieferungs-Stände lieber in einen Ordner außerhalb des Repos kopieren und mit Datum benennen.

Aktuelle Specs

Datum	Titel	Version	Status
2026-05-20	Tailnet-Werbeblocker	0.1.1	Entwurf
2026-05-20	Heim-Monitoring-Stack	0.1.1	Entwurf · Tutor-Modus
2026-05-21	DevOps Control Daemon	0.1.1	Entwurf

Lebende Doku

Pfad	Zweck	Version
docs/SETUP.md	IST-Stand: Hosts, Dienste, Volumes	1.0.0
docs/runbooks/homelab-recovery.md	Wiederherstellung nach Total-Verlust	1.0.0

Trennung: Spec beschreibt vorher den Plan, Doku beschreibt jetzt den IST-Stand, Runbook ist die operative Schritt-Anleitung, Journal dokumentiert nachher den Verlauf einer Umsetzung (Soll → Ist → Lernpunkt).

DevOps Console

devops.html ist die zweite Top-Level-Seite neben der editorialen Spec-Übersicht — eine blackbox-style DevOps-Console (Inter + JetBrains Mono, dark) mit Direktlinks und Live-Status-Pings auf alle Tailnet-Dienste (Grafana, Backrest, ntopng, AdGuard Primary

• Fallback). ⌘K für Filter, shift-click oder right-click kopiert die URL, "Copy all URLs" sammelt alle 12 Endpoints in die Zwischenablage.

Erreichbar nur im Tailnet. Die Direkt-Links zeigen auf 100.x.x.x-Adressen; außerhalb des Tailnets sind die Hosts nicht auflösbar und nicht erreichbar.

Design-System

Zwei Looks im selben Repo, bewusst getrennt:

• Specs/Runbooks: dark-first editorial, Fraunces als Display-Serif, Geist Sans und Geist Mono für Text und Tags, Neon-Orange-Akzent (#ff6a00). Theme-Toggle in jedem Spec-HTML.
• DevOps Console (devops.html): blackbox-inspirierter Operator Look — Inter + JetBrains Mono, #060606 Hintergrund, gap-1px Card-Grid, Terminal-Diff-Preview, Live-Heartbeat-Badges. Eigenes Token-Set, kein Theme-Toggle.

Lizenz

• Doku, HTML, CSS, Diagramme: CC BY 4.0 — frei verwendbar mit Quellenangabe (Alexander Schneider, https://alexle135.de).
• Code unter tools/: MIT.

Wer das Layout oder die Specs übernimmt: kurzer Hinweis auf alexle135.de reicht.

---

_{Alexander Schneider · alexle135.de · schneider@alexle135.de}