nixos-config/docs/intent/gitserver-pinix.md

# Intent: Persönlicher Gitserver auf pinix

## Ziel

pinix soll einen kleinen, persönlichen Gitserver für ausgewählte Projekte
bereitstellen. Die gemeinsame Plattform unter `0ff.space` bleibt auf blunix:
Forgejo, XMPP, Websites, GoToSocial und Headscale werden durch diesen Intent
nicht verschoben.

Der persönliche Gitserver wird unter
`git.lukasrosier.com` erreichbar sein. Der Name wird ausschließlich im
**eigenen Tailnet von pinix** aufgelöst und erreicht (Headscale auf pinix,
`head.lukasrosier.com`), mit einem eigenen Adressbereich. Er ist weder
öffentlich noch über das Tailnet von blunix erreichbar.

## Geplanter Umfang

- cgit als schlanke Weboberfläche zum Lesen von Git-Repositories, installiert
  über das Upstream-NixOS-Modul `services.cgit` und auf Code-Ansicht und
  Download reduziert (siehe „Oberfläche“),
- Git-Zugriff über SSH,
- nur ein Benutzer mit Schreibzugriff: Lukas,
- zunächst die Repositories `nixos-config` und `dashboard`,
- Bare-Repositories auf pinix als lokale Spiegel bzw. persönliche Ablage,
- HTTPS über Traefik auf pinix und das pinix-Zertifikatsmodell
  (`*.lukasrosier.com`); internes Routing nach dem Muster von blunix, mit
  Unbound an der Stelle von AdGuardHome (siehe „Erreichbarkeit im
  pinix-Tailnet“).

Die initiale Spiegelung von Forgejo auf blunix erfolgt manuell. Eine
automatische Aktualisierung über Forgejo-Webhooks wird später als eigener
Schritt ergänzt.

## Oberfläche

cgit bleibt, weil es leichtgewichtig ist; die Standardoberfläche zeigt aber
mehr, als hier gebraucht wird. Die Weboberfläche dient genau zwei Zwecken:

1. **Code lesen:** Repository-Liste → Repository mit Dateibaum und README;
   einzelne Dateien lesbar dargestellt, auf Wunsch als Rohdatei (`plain`).
2. **Herunterladen:** Snapshot-Archive (`tar.gz`, `zip`) für Branches und
   Tags direkt aus der Ansicht.

cgit selbst hat keinen Download-Tab — Snapshot-Links stehen nur auf der
Commit-Seite und bei Tags. Ein kleines Inline-Skript in `head.html` hängt
deshalb `tar.gz`/`zip` für den gewählten Branch an die Tab-Leiste und zeigt
die SSH-Clone-URL darunter an. Ohne JavaScript bleibt cgit voll benutzbar,
nur diese Leiste fehlt.

Alles andere tritt zurück: Statistiken, Commit-Graph, Blame, Datei-Zähler im
Log und Side-by-Side-Diffs werden in der cgitrc abgeschaltet. Log-, Commit-
und Diff-Seiten bleiben per URL erreichbar, stehen aber nicht mehr prominent
in der Navigation.

**Schlank ohne Python:** Es werden keine Python-basierten Filter eingesetzt
— kein Syntax-Highlighting über Pygments, kein Markdown-Rendering. Dateien
erscheinen als schlichter, sauber gesetzter Text. Die README wird als
vorformatierter Text angezeigt; falls cgit sie ohne Filter nicht lesbar
ausgibt, übernimmt das ein kleiner Shell-Filter (HTML-Escaping + `<pre>`),
der nur Werkzeuge aus coreutils/sed nutzt.

Das cgit-Paket aus nixpkgs bringt seine Python-Filter (Pygments, Markdown,
docutils) selbst in die Closure mit, auch wenn sie nicht konfiguriert sind.
Ein Build-Override in `gitserver/default.nix` entfernt sie; am C-Code ändert
sich nichts.

### Umsetzung ohne Eingriff in cgit selbst

cgit erzeugt sein HTML im C-Code. Dieser wird **nicht** gepatcht oder
geforkt; die Vereinfachung läuft ausschließlich über die vorgesehenen
Stellschrauben, damit nixpkgs-Updates ohne Nacharbeit durchlaufen:

- `services.cgit.<name>.settings` (cgitrc): Funktionen abschalten, Snapshots
  aktivieren, README-Datei festlegen,
- ein eigenes Stylesheet (`css`), das die Oberfläche ruhig und schlicht
  macht und nicht benötigte Navigation ausblendet,
- `head-include`, `header` und `footer` für kleine HTML-Anpassungen, etwa
  direkte Links auf Dateibaum und Downloads.

Stylesheet und HTML-Schnipsel liegen als Dateien im Repo neben dem Modul
(z. B. `hosts/pinix/localServices/cgit/`), nicht als Strings im Nix-Code.

`services.cgit` bindet cgit über nginx und fcgiwrap an und aktiviert nginx
mit Standard-Listen auf Port 80, den Traefik auf pinix bereits belegt. nginx
lauscht daher nur auf `127.0.0.1` an einem freien Port; Traefik bleibt der
einzige Eingang.

## Erreichbarkeit im pinix-Tailnet

Das Muster ist dasselbe wie auf blunix:

| | blunix | pinix |
| --- | --- | --- |
| Interne Route | Traefik-Entrypoint `web-internal` | Traefik-Entrypoint `web-internal` |
| Internes DNS | AdGuardHome-Rewrite | Unbound-`local-data` |
| Tailnet | Headscale auf blunix, `100.64.0.0/10` | Headscale auf pinix, eigener Bereich |

### Eigener Adressbereich

Das pinix-Tailnet bekommt den bereits in
`hosts/pinix/localServices/tailnet-dns.nix` vorgesehenen Bereich:

- IPv4 `100.96.0.0/24`,
- IPv6 `fd7a:115c:a1e0:96::/64`.

Stand 14.09.2026 (live geprüft): Headscale auf pinix vergibt aus
`100.96.0.0/24` und `fd7a:115c:a1e0:96::/64`. Die Hauptknoten sind
`pinix` (`100.96.0.4`), `tnix` (`100.96.0.5`) und `blunix`
(`100.96.0.6`); alle gehören zum Headscale-Nutzer `lukas`. Der technische
Knoten `pinix-dns` belegt `.1` unter einem eigenen Maschinenkonto. Die alte
isolierte `tnix`-Registrierung `.2` wurde nach der Migration gelöscht.

Der iPhone-Knoten ist als `localhost-1` unter `lukas` mit `.2` registriert;
der alte `localhost`-Eintrag unter `admin` wurde entfernt. `headscale nodes
backfillips` verschiebt bestehende Adressen nicht; die Migration erfolgte
durch Löschen und Neuregistrieren.

Das blunix-Headscale vergibt faktisch nur aus `100.64.0.x`; eine
Überschneidung mit `100.96.0.0/24` entsteht nicht, solange das so bleibt.
Den blunix-Bereich formal einzuschränken ist nicht Teil dieses Intents.

### Wo der pinix-Knoten lebt

Beide Tailnets liegen innerhalb der Tailscale-Adressbereiche. Auf pinix
bleibt deshalb die technische DNS- und Service-Instanz in einem eigenen
Netzwerk-Namespace: `tailscaled-pinix` und `unbound-pinix` bilden dort den
Knoten `pinix-dns` (`100.96.0.1`, `fd7a:115c:a1e0:96::1`). Das normale
`tailscaled` im Host-Namespace ist dagegen als `pinix` unter `lukas` im
gemeinsamen pinix-Tailnet angemeldet. Auf tnix gibt es keine zweite isolierte
Tailscale-Instanz mehr.

### Traefik wie auf blunix

Auf blunix bindet `web-internal` an die Tailnet-Adresse. Auf pinix liegt die
Tailnet-Adresse im Namespace, Traefik im Host-Namespace; beide sind über das
bestehende veth-Paar verbunden (`fd42:7069:6e69:78::1` Host,
`fd42:7069:6e69:78::2` Namespace).

- **Entrypoint:** `web-internal` bindet an
  `[fd42:7069:6e69:78::1]:8443`. Diese Adresse ist nur aus dem Namespace
  erreichbar. Ein eigener Port ist nötig, weil `websecure` auf `:443` aller
  Adressen hört (live geprüft) — so bleibt `websecure` **unverändert**, der
  öffentliche Eingang und der Headscale/Dex-Bootstrap aus dem Namespace
  werden nicht angefasst.
- **Router:** `git.lukasrosier.com` hängt ausschließlich an `web-internal`,
  nach dem `mkRoute`-Muster aus
  `hosts/blunix/localServices/traefik/routes-internal.nix`; Backend ist das
  lokale nginx.
- **Weiterleitung im Namespace:** Eingehendes TCP 443 auf der pinix-Tailnet-
  Adresse wird auf `[fd42:7069:6e69:78::1]:8443` weitergeleitet, TCP 22 auf
  `[fd42:7069:6e69:78::1]:22` (sshd für Git). Die Quelle wird dabei auf
  `fd42:7069:6e69:78::2` umgeschrieben, damit Antworten des Hosts nicht in
  dessen blunix-Tailnet-Routen laufen. Weitergeleitet werden genau diese
  zwei Ports; der Namespace bleibt ansonsten ohne Forwarding, kein
  Subnet-Router, kein Exit-Node.
- **Firewall Host:** `pdns-host` erlaubt zusätzlich TCP 8443 und 22.

Damit ändert sich die Rolle des Namespace-Knotens gegenüber
`docs/pinix-tailnet-dns.md` („kein Proxy“): Er leitet genau diese zwei Ports
weiter. Die Doku wird bei der Umsetzung nachgezogen.

**Nur IPv6:** Das veth-Paar ist IPv6-only, eine Weiterleitung von IPv4 auf
IPv6 gibt es nicht. `git.lukasrosier.com` bekommt deshalb im pinix-Tailnet
nur einen AAAA-Eintrag. Das passt zur IPv6-Richtung von pinix
(`docs/roadmap.md`). Falls ein Client ohne IPv6 im Tailnet dazukommt, wird
das veth-Paar um IPv4 ergänzt.

### DNS wie AdGuardHome, mit Unbound

- **Eintrag:** `unbound-pinix` erhält
  `local-data: "git.lukasrosier.com. AAAA fd7a:115c:a1e0:96::1"` — das
  Gegenstück zum AdGuard-Rewrite auf blunix.
- **Verteilung:** Headscale auf pinix verteilt `unbound-pinix` per Split-DNS
  nur für `git.lukasrosier.com` an die Clients. Ein Split für ganz
  `lukasrosier.com` würde bei einem Ausfall von `unbound-pinix` auch
  `head.`/`dex.` unauflösbar machen und Clients von Headscale abschneiden.
- **Zertifikat:** `git.lukasrosier.com` liegt unter dem vorhandenen
  Wildcard-Zertifikat `*.lukasrosier.com` (`acme.nix`).

Außerhalb des pinix-Tailnets zeigt `git.lukasrosier.com` über die
öffentliche Zone weiter auf blunix, wo kein Router existiert (404).

### Aktueller Zugriff

Die Hauptgeräte können sich über ihre gemeinsamen Tailnet-Adressen direkt
untereinander verbinden. `git.lukasrosier.com` wird über den technischen
Knoten `pinix-dns` aufgelöst und leitet TCP 443 und 22 zum internen Traefik
und zum Git-SSH-Dienst auf pinix weiter. Der technische Knoten bleibt dabei
ein eigener Headscale-Knoten; die Geräte des Nutzers teilen ausschließlich
den Headscale-Nutzer `lukas`.

## Umsetzungsstand 14.09.2026

Umgesetzt und auf pinix per `switch` aktiv: eigener Adressbereich,
`pinix-dns` als `.1`, die drei Hauptknoten unter dem Headscale-Nutzer
`lukas` (`pinix` `.4`, `tnix` `.5`, `blunix` `.6`), Weiterleitung 443/22 im
Namespace, `web-internal` auf `:8443`, Split-DNS, cgit ohne Python und Git
über SSH. `nixos-config` und `dashboard` sind manuell von Forgejo gespiegelt
(nur Branches und Tags). Der direkte Zugriff aus dem normalen tnix-Host-Netz
auf `https://git.lukasrosier.com` wurde nach der Bereinigung der alten
isolierten tnix-Instanz geprüft.

Der iPhone-Knoten ist jetzt `localhost-1` unter dem Nutzer `lukas` (`.2`).
Der alte `admin`-Eintrag wurde nach der erfolgreichen Neuanmeldung gelöscht.

Die alte isolierte tnix-Registrierung (`.2`) und die dazugehörige zweite
Tailscale-Instanz wurden entfernt. Der direkte Zugriff nutzt jetzt das
gemeinsame Tailnet; `hosts/tnix/pinixnet.nix` ist nicht mehr erforderlich.

Ebenfalls nachgezogen: tnix ↔ `pinix-dns` lief über das DERP-Relay `fra`
(~100 ms), weil der Namespace-Knoten nach außen nur als pinix' maskierte
öffentliche IPv6 erschien. Eine Portweiterleitung von UDP 41642 in den
Namespace (`tailnet-dns.nix`) macht die Verbindung direkt (1 ms).
Entschieden am 14.09.2026: cgit auf pinix bleibt vorerst **eigenständig**.
Kein automatischer Abgleich mit Forgejo; die Spiegelung von blunix
(Ausbauschritt 2) ist bis auf Weiteres zurückgestellt.

Nachgezogen am 14.09.2026: Die bisher pausierte Restic-Sicherung auf pinix
ist wieder aktiv und umfasst zusätzlich `/var/lib/git`. Der erste Lauf wurde
sofort ausgeführt und als Snapshot `e3d7ebe3` verifiziert; er enthält
`dashboard.git` und `nixos-config.git`. Das Restic-Repository liegt lokal
unter `/backup`. Die vorhandene tnix-Kopie dieses Verzeichnisses auf einem
externen Medium (`backup-pi`) bleibt ein manueller Schritt; ein getesteter
Restore und eine automatische Ausführung dieser Off-Host-Kopie sind damit
noch nicht Teil dieses Nachtrags.

## Besitz- und Schreibmodell

Forgejo auf blunix bleibt für die bisherigen gemeinsamen Projekte und deren
normale Zusammenarbeit maßgeblich. Für die ersten beiden Repositories wird
vor der technischen Umsetzung festgelegt, ob pinix ausschließlich eine
read-only Kopie von Forgejo erhält oder ob einzelne persönliche Repositories
auf pinix führend werden.

Bis diese Frage entschieden ist, darf kein automatischer bidirektionaler
Abgleich eingerichtet werden. Dadurch werden divergierende Schreibstände und
unbeabsichtigte Überschreibungen vermieden.

## Bewusste Nicht-Ziele

- kein zweites Forgejo auf pinix,
- kein Patch oder Fork des cgit-C-Codes und kein eigenes Web-Frontend,
- kein Python in der cgit-Closure (keine Pygments-/Markdown-Filter),
- keine Erreichbarkeit über das Tailnet von blunix, keine Einträge in
  AdGuardHome oder Traefik auf blunix,
- kein zusätzlicher DNS-Dienst (z. B. AdGuardHome) auf pinix,
- keine Änderung an Traefiks öffentlichem Entrypoint `websecure`,
- keine öffentliche Registrierung oder Mehrbenutzerverwaltung,
- keine Webhook-Annahme im ersten Umsetzungsschritt,
- keine Verlagerung der bestehenden `0ff.space`-Dienste von blunix,
- kein öffentlicher Internetzugriff ohne spätere ausdrückliche Entscheidung.

## Spätere Ausbauschritte

1. Repositories initial anlegen und den gewünschten Spiegelungsmodus
   festlegen.
2. Webhook von Forgejo zu einem kleinen, abgesicherten Pull-Dienst auf pinix
   einrichten. Der Weg von Forgejo (blunix) zu pinix ist dabei neu zu
   klären, weil der Gitserver nicht im blunix-Tailnet hängt.
3. Repositories und Branches für den Spiegel explizit in einer deklarativen
   Konfiguration oder einer geschützten Allowlist festhalten.
4. Optional einzelne persönliche Repositories als führende Schreibkopie auf
   pinix betreiben.
5. Erst danach prüfen, ob eine öffentliche cgit-Ansicht oder weitere kleine
   persönliche Dienste wie snac2 sinnvoll sind.

## Akzeptanzkriterien für die Umsetzung

- Headscale auf pinix vergibt ausschließlich aus `100.96.0.0/24` und
  `fd7a:115c:a1e0:96::/64`; keine Registrierung trägt noch eine
  `100.64.0.0/10`-Adresse außerhalb davon.
- `git.lukasrosier.com` funktioniert von einem Client im pinix-Tailnet über
  HTTPS.
- Clients im pinix-Tailnet lösen `git.lukasrosier.com` über `unbound-pinix`
  auf `fd7a:115c:a1e0:96::1` auf; Eintrag und Split-DNS sind deklarativ im
  Repo festgehalten.
- Der Traefik-Router für `git.lukasrosier.com` hängt nur an `web-internal`
  auf `[fd42:7069:6e69:78::1]:8443`.
- Aus dem blunix-Tailnet ist `git.lukasrosier.com` nicht erreichbar, und
  auf blunix existiert weder ein Traefik-Router noch ein AdGuard-Rewrite
  dafür.
- Headscale, Dex und der öffentliche IPv6-Eingang auf pinix funktionieren
  unverändert; `websecure` ist nicht angefasst.
- Der Namespace leitet nur TCP 443 und 22 weiter und ist ansonsten weder
  Router noch Proxy.
- cgit zeigt die beiden ausgewählten Repositories an.
- cgit ist über `services.cgit` deklariert; eigenes CSS und HTML-Schnipsel
  liegen als Dateien im Repo.
- Die cgit-Closure enthält kein Python.
- Ein Repository zeigt Dateibaum und README; Dateien sind lesbar und als
  Rohdatei abrufbar.
- Snapshots als `tar.gz` und `zip` lassen sich für Branches und Tags
  herunterladen.
- Statistiken, Commit-Graph und Blame sind abgeschaltet; die Navigation
  zeigt nur, was zum Lesen und Herunterladen nötig ist.
- nginx ist nicht von außen erreichbar, nur Traefik nimmt Verbindungen an.
- SSH akzeptiert Git-Operationen nur für den vorgesehenen Benutzer und
  Schlüssel, und nur über den Weg aus dem pinix-Tailnet.
- Ein Zugriff außerhalb des pinix-Tailnets ist nicht möglich, auch nicht
  direkt gegen die öffentliche IPv6-Adresse von pinix mit passendem
  `Host`-Header.
- Es gibt keinen automatischen Schreib- oder Synchronisationsdienst, bevor
  der führende Datenbestand geklärt ist.