Lesson 0001 · groupdir-infra

Repo-Gesamtbild

Erste Orientierung: Was steckt in groupdir-infra, und wohin gehört welche Änderung?

Einleitung

groupdir-infra beschreibt die Infrastruktur: öffentliche VPN-Anbindung, Lab-Gateway, internes DNS und Reverse-Proxy. Es mischt zwei Welten: NixOS für die Serverkonfiguration und Terraform (CLI im Repo: tofu) für externe APIs wie Hetzner-DNS und Proxmox.

Voraussetzung: Nix und Flakes wie in Lesson 0000. Du brauchst noch kein tiefes Nix- oder Terraform-Wissen. In dieser Lesson lernst du nur die Landkarte: welche Ordner es gibt, wie sie zusammenhängen, und wo du als Nächstes hinschaust, wenn du etwas ändern willst. Details zu DNS, Plan/Apply und Modulen kommen in den folgenden Lessons.

Wozu die Landkarte?

Viele Dateien sehen ähnlich aus (.nix, .tf). Ohne Überblick landet eine Änderung leicht am falschen Ort, zum Beispiel:

  • einen Lab-Namen nur unter tofu/dns oder direkt in net/dns/groupdir.de.nix eintragen, obwohl Lab-Hosts in net/lab/hosts/ liegen
  • Host-Verhalten in einer einzelnen Host-Datei nachbauen, obwohl es ein wiederverwendbares Modul unter nixos/modules/ gibt
  • annehmen, Änderungen gäbe es nur über die GitLab-Pipeline. Lokal gehen dieselben Schritte mit just und Colmena

Das Repo ist bewusst klein gehalten (README). Mit der Landkarte aus dieser Lesson findest du die richtige Datei in Sekunden.

Drei Ketten, eine Wahrheit

Merksatz: Lab-Hosts stehen in net/lab/hosts/ (IPAM + DNS); WireGuard-Peers in net/wireguard/peers/ (Inventar); die Zone merged Lab-DNS mit öffentlichen Records; Terraform spricht nur mit externen APIs (Hetzner, Proxmox). Siehe auch Glossar: DNS, WireGuard-SoT, lab-ipam.md, wireguard.md.

Ordner → Aufgabe

  • net/lab/hosts/: Lab-LAN-IP + meist *.lab-DNS (just lab-ipam)
  • net/wireguard/: Tunnel-IPAM + Peer-Inventar (just wireguard-ipam; live noch UI)
  • net/dns/groupdir.de.nix: Zone (öffentlich, VPN, SRV/TXT) + Merge der Lab-Records; Felder scope / target
  • nixos/modules/: Module (labEdge.*)
  • nixos/hosts/: Host steckt Module zusammen (vps, lab-gateway, …)
  • deployment.nix: das Host-Inventar (targetHost/targetUser/tags) — flake.nix (nixosConfigurations) und hive.nix (Nodes für Colmena) leiten beide daraus ab
  • tofu/dns, tofu/proxmox: Terraform-Stacks (CLI: tofu)
  • justfile: kanonische lokale Befehle (auch ohne CI)

Typische Änderung → Ort

  1. Neuer Lab-Service mit Hostname → net/lab/hosts/<name>.nix, dann Deploy lab-gateway (operations.md, lab-ipam.md)
  2. Neuer WireGuard-Peer (Inventar) → net/wireguard/peers/<name>.nix (wireguard.md; 0010)
  3. Verhalten aller Hosts (VPN, Users, Proxy) → Modul unter nixos/modules/, Option in Host-Config setzen
  4. Öffentliches DNS bei Hetzner → Record in net/dns/groupdir.de.nix, dann just tofu-dns-generate und lokal plan/apply
Pipeline ist optional für dich. Dieselbe Arbeit läuft lokal: nix develop, dann just-Targets (Terraform-Plan/Validate) bzw. colmena build. Live-Apply gegen echte APIs/Hosts brauchst du fürs Selbststudium nicht. Die Befehle lernst du trotzdem.

Üben: Zuordnung

Ohne nachzuschlagen: Welche Kette? Feedback kommt sofort.

Retrieval

Du legst grafana.lab als internen Namen hinter Caddy an. Wo ist die Quelle?

Du willst einen neuen WireGuard-Peer im Git inventarisieren. Wohin zuerst?

Du willst Hetzner-DNS lokal planen, ohne GitLab-CI. Was stimmt?

Primärquelle

Lies als Nächstes das Repo-README von oben bis „Repository layout“: groupdir-infra/README.md. Für Lab-IPAM/DNS parallel: docs/lab-ipam.md; Zone-Semantik: docs/dns-records.md.

Extern (Vokabular Plan/Apply: Terraform-Begriffe, CLI im Repo: tofu): OpenTofu Getting started.