From 36cb684d8b67e77d6184b134131e7954064df6a9 Mon Sep 17 00:00:00 2001 From: nexxo Date: Thu, 30 Jul 2026 08:58:59 +0200 Subject: [PATCH] Write down what the audits found and what a real run needs Co-Authored-By: Claude Opus 5 --- docs/handoffs/2026-07-30-real-run-handoff.md | 267 +++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 docs/handoffs/2026-07-30-real-run-handoff.md diff --git a/docs/handoffs/2026-07-30-real-run-handoff.md b/docs/handoffs/2026-07-30-real-run-handoff.md new file mode 100644 index 0000000..8f51e21 --- /dev/null +++ b/docs/handoffs/2026-07-30-real-run-handoff.md @@ -0,0 +1,267 @@ +# Handoff — vom grünen Test zum ersten echten Durchlauf + +**Stand:** 2026-07-30, `main` auf `v1.3.44`, **1686 Tests grün.** +**Zweck:** In dieser Nacht wurden Host-Onboarding, VM-Erstellung und der Stripe-Prozess +vollständig geprüft und der größte Teil der Funde behoben. Was bleibt, ist unten +beschrieben. Die Kernaussage in einem Satz: **die Testsuite war grün, und trotzdem +hätte kein Host durchinstalliert und keine VM ausgeliefert werden können.** + +--- + +## 0. Die Lektion, die den ganzen Rest erklärt + +Alle Funde waren gegen eine grüne Suite unsichtbar, und zwar systematisch: + +- `HostOnboardingEndToEndTest` fährt die ganze Pipeline gegen `FakeRemoteShell`, + dessen Standardantwort **Erfolg** ist. Der Test beweist, dass die Zustandsmaschine + richtig durchzählt — über das Verhalten irgendeines Befehls sagt er nichts. +- Rund ein Dutzend Tests schrieben in `config('provisioning.plans.*')`, einen + Schlüssel, den es seit dem Katalog-Umbau nicht mehr gibt (und es existiert ein + Test, der genau das behauptet: `expect(config('provisioning.plans'))->toBeNull()`). + Jede dieser Zeilen war wirkungslos; die Tests waren aus dem falschen Grund grün. +- Mehrere Tests prüften eine Spalte, die der Code eine Zeile vorher selbst + geschrieben hatte. + +**Konsequenz für die nächste Session:** Ein Testlauf ist keine Abnahme. Jeder +Arbeitsblock unten endet mit einem Schritt auf echter Hardware, nicht mit „grün". + +--- + +## 1. Entscheidungen aus dem Brainstorming (verbindlich) + +| Frage | Entscheidung | +|---|---| +| Woher kommt die Software im Gast? | **Vorlage bringt Docker + Compose mit, Nextcloud installiert sich beim ersten Start** aus `NEXTCLOUD_ADMIN_*`, die die Pipeline in die `.env` schreibt. Vorlage bleibt kundenunabhängig, Passwörter werden nie in ein Image gebacken. | +| Proxmox-Version | **PVE 9 auf Debian 13 trixie.** Die Codename-Tabelle in `InstallProxmoxVe` kennt beides; PVE 8/bookworm kann bleiben, getestet und unterstützt wird 9. | +| Traefik | **Systemdienst (Binary + systemd-Unit), pro Host**, installiert *und geprüft* von einem neuen Pipeline-Schritt. Kein Docker auf dem Hypervisor — nftables bleibt einziger Eigentümer der Host-Firewallregeln. | +| `vmbr0` | **Vollautomatisch**, mit Selbstrücknahme-Zeitgeber (siehe Block B). | +| Testumgebung | **Ein dedizierter Server mit Debian 13**, neu aufsetzbar. Kein zweiter Rechner nötig. | +| Testpaket | Eigene Paketfamilie **„Test"**: 20 GB Platte, 1 GB RAM, 1 Kern, 5 GB Kontingent. Nach dem Beweis wieder aus dem Verkauf nehmen. | +| ACME | HTTP-01 pro Host. **Kein** Wildcard/DNS-01 — pro Kunde entsteht genau ein Zertifikat, unabhängig von der Host-Zahl. | + +**Nicht geeignet:** Hetzner Cloud (CPX/CX) — keine verschachtelte Virtualisierung, +also `/dev/kvm` nicht vorhanden, also startet kein Gast. Unabhängig von der Größe. +Bei netcup-VPS ist es produktabhängig; entscheidend ist +`grep -cE 'vmx|svm' /proc/cpuinfo && ls -l /dev/kvm`. + +--- + +## 2. Was heute Nacht behoben und ausgeliefert wurde + +Sechs Commits, `8440266` → `9da1358`, Tag `v1.3.44`. + +### Stripe / Geld +- **Nichts konnte ein Stripe-Abo beenden.** Kündigung und Widerruf schrieben nur + lokale Zustände; Stripe erfuhr nie davon, und die nächste Abbuchung wurde + **als echte Rechnung aus der lückenlosen Serie ausgestellt und versendet** — + monatlich, unbegrenzt, für eine abgeschaltete Leistung. Jetzt: Kündigung zum + Periodenende, Widerruf sofort, und eine Rechnung wird nur noch ausgestellt, wenn + ihr Abrechnungszeitraum **vor** dem Vertragsende begann. +- Kündigung lief auf **Monatstakt auch bei Jahresverträgen** (bis zu elf bezahlte + Monate verloren). Jetzt aus `current_period_end`. +- **Einrichtungsgebühr** wurde überall beworben und **nie berechnet** — jetzt eine + Einmalposition am Checkout, brutto, auf der ersten Rechnung. +- Das Kundenportal zeigte **fünf erfundene Rechnungen**, eine erfundene + Ausgabenkurve und eine erfundene nächste Abbuchung, während die echten Belege + existierten und nirgends im Portal auftauchten. Jetzt die echten. +- **Widerruf erstattet voll** (Ihre Entscheidung), Stornorechnung für **jede** + Abbuchung im Zeitfenster, nicht nur die erste. +- Ein Absturz nach dem Auftrags-Commit ließ einen bezahlten Kauf **dauerhaft + unfakturiert** — `resume()` holt das jetzt nach, idempotent. +- Klick auf „Upgrade" löschte stillschweigend eine vorgemerkte Abstufung und tat + sonst nichts. Behoben. +- **Reverse-Charge-Kunden zahlten 20 % zu viel**: ein Stripe-Preis für alle, also + Bruttobetrag auch für den, dem keine Steuer berechnet wird — und der Beleg wies + den ganzen Betrag als Netto aus. Jetzt **zwei Preise je Paket** (brutto/netto), + Auswahl an der Kasse über `TaxTreatment`. +- **UID-Prüfung gegen VIES** gebaut (vorher setzte niemand `vat_id_verified_at`, + Reverse Charge konnte also nie auslösen). Drei Ergebnisse: bei „Register nicht + erreichbar" wird **nichts** geschrieben. + +### Host-Onboarding +- **Debian-Codename war fest auf `bookworm`** — ein heutiger Server hätte PVE-8-Quellen + gegen Debian 13 bekommen. Jetzt aus `/etc/os-release`, unbekannte Releases brechen ab. +- **WireGuard-Sackgasse:** Die Tunnel-IP wurde gespeichert, bevor der Tunnel bewiesen + war; danach wählte *jeder* Verbindungsversuch inklusive Konsolen-Wiederholung diesen + kaputten Tunnel, und der reparierende Code war unerreichbar. Rettung nur per + Datenbank-Handarbeit. Jetzt gilt der Tunnel erst mit bewiesenem Handshake. +- **wg0 hätte den Neustart nicht sicher überlebt** (`||`-Fallback verdeckte die + fehlende systemd-Aktivierung); **der Neustart konnte eine nicht mehr bootende + Maschine hinterlassen**; **`ConfigureProxmox` tat nichts** (kein `vmbr0`, Datacenter- + Firewall aus → die „nur 80/443"-Regeln der Kunden-VMs waren **wirkungslos**); + der Rolle fehlte **`Sys.Modify`** (jede Kundenbereitstellung wäre am Backup-Schritt + gestorben); nftables verwarf **jedes ICMP** (IPv6 und PMTUD gebrochen); + `api_token_ref` hing an `APP_KEY` statt am `SECRETS_KEY`. +- Neu: **`VerifyVmTemplate`** — ein Host geht nicht mehr auf „aktiv", wenn die + Vorlage fehlt. Vorher starb der erste bezahlte Auftrag *nach* der Zahlung. + +### VM-Erstellung +- **Das 14-tägige Kapazitätsparken war unerreichbar:** Abfrageintervall 120 s gegen + Schritt-Zeitlimit 60 s, also lief jeder Wiedereinstieg in eine Zeitüberschreitung. + Ein bezahlter Auftrag ohne freien Host war nach **sechs Minuten** ein Fehlerfall. + Die ganze Warteschlange war toter Code. +- **Jeder `occ`-Aufruf lief als root** statt `www-data`; Nextcloud verweigert das. + Jetzt ein gemeinsamer Erbauer (`App\Support\NextcloudOcc`) plus ein Test, der + jede neue `docker compose exec`-Stelle außerhalb davon verbietet. +- Ein **einzelner zuckender HTTPS-Test verurteilte eine fertige Cloud** zum Fehlerfall. +- Eine nachgewiesene eigene Domain wurde **nie geroutet**, wenn zufällig ein Neustart + lief; gekaufter Speicher wurde **abgerechnet und nie geliefert**. Der „läuft schon + etwas?"-Schutz fragt jetzt, ob der laufende Lauf die Arbeit **tatsächlich abdeckt**. +- Die `address`-Pipeline lief in der falschen Reihenfolge (Zertifikat vor + vertrauenswürdigem Hostnamen → gültiges Zertifikat auf Nextclouds + „untrusted domain"-Fehlerseite). +- Eine geänderte Gast-IP war **unreparierbar** (502 ohne Weg zurück). +- Der Hetzner-DNS-Abgleich las **nur die erste Seite** → ab ~100 Einträgen ein + **zweiter A-Record** für denselben Namen. + +--- + +## 3. Was noch zu tun ist — vier Blöcke, in dieser Reihenfolge + +### Block A — Goldene VM-Vorlage (kritischer Pfad, blockiert alles) +Es gibt **keine** Vorlage auf `template_vmid 9000`. Ohne sie kann nichts ausgeliefert +werden. Zu tun: +- Debian-13-VM auf dem dedizierten Server, ~20 GB Platte, cloud-init-fähig + (`qemu-guest-agent` **muss** drin sein — `WaitForGuestAgent` hängt daran). +- Docker + Compose, `/opt/nextcloud/` mit `docker-compose.yml`, das + `NEXTCLOUD_ADMIN_USER`/`NEXTCLOUD_ADMIN_PASSWORD`/`MYSQL_PASSWORD` aus `.env` liest + und beim ersten Start selbst installiert. +- **`user: www-data` am `app`-Dienst** — sonst schlagen alle `occ`-Aufrufe fehl. +- Partition als **letzte** auf der Platte, **kein LVM** — `GrowGuestFilesystem` kann + eine nicht-letzte Partition nicht vergrößern und erkennt LVM bewusst nicht + (es würde sonst ein Kontingent über ein nicht gewachsenes Dateisystem schreiben). +- Als Proxmox-Vorlage konvertieren, vmid 9000. +- **Schriftliches Runbook dazu**, versioniert im Repo. Die Vorlage ist ab dann Ihr + wichtigstes Artefakt und gehört nicht in mündliches Wissen. + +### Block B — `vmbr0` vollautomatisch (riskantester Code des Vorhabens) +Eigener Schritt, eigener Abnahmetest. Muster: +1. Aktuelle Netzkonfiguration sichern. +2. Systemd-Timer auf 5 Minuten, der sie zurückspielt und neu startet. +3. Brücke aktivieren. +4. **Von außen** prüfen, ob der Host antwortet. +5. Erst dann den Timer abbestellen. + +Der Schritt muss **erkennen**, was er vorfindet — DHCP auf einer Schnittstelle +(Cloud) gegen geroutete Einzel-IP mit Gateway außerhalb des Subnetzes +(Hetzner-Dedicated) gegen netcup. Eine Brücke, die für den einen Fall richtig ist, +nimmt den anderen vom Netz. `ConfigureProxmox` bricht heute bewusst mit einer +Anleitung ab; dieser Block ersetzt das. + +### Block C — Traefik als Systemdienst +Neuer Schritt zwischen `SecureHostFirewall` und `CompleteHostOnboarding`: +- Binary installieren, systemd-Unit, statische Konfiguration mit `websecure`-Entrypoint + und `letsencrypt`-certResolver, **deren Namen zu dem passen müssen, was + `SshTraefikWriter::render()` schon ausgibt** — hier zuerst nachlesen, nicht raten. +- Dynamisches Verzeichnis anlegen (`TRAEFIK_DYNAMIC_PATH`, Vorgabe + `/etc/traefik/dynamic`), Dateiprovider darauf zeigen. +- **Prüfen, nicht nur installieren:** Dienst läuft, 80/443 belegt, Ping-Endpunkt + antwortet. Ein Host darf nicht „aktiv" werden, wenn das Routing nicht steht. +- ACME braucht Port 80 **erreichbar** — die Firewall öffnet ihn, aber Traefik muss + lauschen, bevor das erste Zertifikat angefordert wird. + +### Block D — Kleinigkeiten und eine kaufmännische Entscheidung +- **Rollen-Konvergenz auf bereits aktiven Hosts.** `Sys.Modify` erreicht sie nicht: + ein abgeschlossenes Onboarding kann nicht wiederholt werden, ein Kommando fehlt. +- **Traffic-Pakete (Ihre Entscheidung):** Der Auftrag ist einmalig, das Feld + `traffic_addons` ist ein *dauerhafter* Zähler. Hochzählen = 1000 GB für immer aus + einer Zahlung; nichts tun = der Kunde zahlte für nichts. Der Code protokolliert + das derzeit laut, statt still eines von beiden zu tun. +- `pveum acl modify … || true` und `pveum user add … || true` verdecken weiter + Fehler — dieselbe Klasse wie der behobene `role add`. +- `VerifyVmTemplate` prüft nur **Existenz**, nicht `template: 1`. +- `applyFirewall()` setzt **nicht** `firewall=1` an `net0` der VM — ohne das greifen + die Gastregeln trotz Datacenter-Firewall nicht. Prüfen, ob die Vorlage es mitbringt. +- `stripe_addon_prices.stripe_price_id` ist **nicht** eindeutig (Plan-Seite schon): + zwei Zeilen könnten einen Preis teilen, Archivieren würde den anderen mitentziehen. +- `clupilot:end-due-services` schließt den **Vertrag** nicht — ein geschenkter Vertrag + bleibt nach Ende der Instanz für immer `active` und zählt in Umsatz/Dashboard mit. +- Eine Abbuchung, die **vor** dem Widerruf entstand und **danach** bezahlt wird, + bekommt einen Beleg, wird aber nicht storniert oder erstattet — ohne Signal. +- `Livewire\Admin\Provisioning::isStale()` erbt das neue 14-Tage-Budget: ein geparkter + Lauf mit totem Worker wird zwei Wochen nicht als hängend gemeldet. + +--- + +## 4. Was gesetzt sein muss, bevor ein echter Lauf Sinn hat + +Auf **diesem** Entwicklungsserver ist alles vorhanden; auf dem Live-Server ist es +ungeprüft. Vor dem Durchlauf einzeln bestätigen — jedes fehlende Stück bricht die +Kette an einer anderen Stelle, und mehrere brechen sie **nach** der Zahlung. + +**Geheimnisse (Vault, Konsole → Integrationen):** +- `ssh.private_key` — ohne: `EstablishSshTrust` scheitert mit einem phpseclib-Parserfehler +- `dns.token` — Hetzner-DNS-Token. Ohne: der A-Record der VM entsteht nicht, der Kunde + hat keine Adresse. **Braucht Schreibrecht auf die Zone.** +- `stripe.secret` und `STRIPE_WEBHOOK_SECRET` — ohne: kein Auftrag entsteht überhaupt +- `monitoring.token` — Uptime-Kuma-Brücke, `RegisterMonitoring` +- `SECRETS_KEY` — **seit heute Nacht auch für `hosts.api_token_ref`.** Fehlt er, ist + jeder Host-Token unlesbar und keine Bereitstellung läuft. +- `VPN_CONFIG_KEY` + +**Einstellungen:** +- `CLUPILOT_DNS_ZONE` = **`clupilot.cloud`** (nicht `.com`). Vorgabe im Code ist + richtig; auf diesem Server stand in der `.env` versehentlich `.com`. +- `CLUPILOT_WG_HUB_PUBKEY`, `CLUPILOT_WG_ENDPOINT`, `CLUPILOT_WG_SUBNET` — und der + **Hub muss laufen und auf 51820/udp erreichbar sein**. Die Hosts sind Initiatoren; + der offene UDP-Port ist eine Anforderung an den Hub, nicht an die Hosts. +- `CLUPILOT_DNS_HOSTS_DIR` — dnsmasq-Verzeichnis für die internen Hostnamen, + geteiltes Volume mit dem `vpn-dns`-Container +- `TRAEFIK_DYNAMIC_PATH` +- **Firmendaten vollständig** (Name, Adresse, PLZ, Ort, UID) **und Steuersatz** — + sonst verweigert `IssueInvoice`, und der Kunde bekommt keinen Beleg +- **Mindestens ein Rechenzentrum** angelegt — `ValidateHostInput` verlangt es +- **Postfächer** eingerichtet — sonst erreicht die Zugangsdaten-Mail den Kunden nicht + +**Betrieb:** +- `queue`, `queue-provisioning`, `scheduler` und `reverb` laufen — die Pipeline ist + warteschlangengetrieben, ohne Worker passiert schlicht nichts +- Stripe-Katalog nach dem Update: `stripe:sync-catalogue` **und** + `stripe:reprice-subscriptions` (je zuerst `--dry-run`). Der Abgleich legt jetzt + **zwei** Preise je Paket an; bis er lief, kann ein geprüfter EU-Firmenkunde nicht + bestellen — das ist Absicht. + +--- + +## 5. Reihenfolge des ersten echten Durchlaufs + +1. Testpaket „Test" in der Konsole anlegen (20 GB / 1 GB / 1 Kern / 5 GB) und veröffentlichen. +2. Abschnitt 4 durchgehen und **jedes** Stück bestätigen. +3. Debian 13 auf dem dedizierten Server, Host in der Konsole anlegen, onboarden. + Erwartung nach Block B/C: läuft bis `active` durch. Ohne Block B bricht es bei + `vmbr0` ab — das ist derzeit gewollt. +4. Vorlage bauen (Block A), `VerifyVmTemplate` muss sie finden. +5. Testpaket kaufen. Erwartung: 16 Schritte bis `CompleteProvisioning`, Nextcloud + erreichbar unter `.clupilot.cloud` mit gültigem Zertifikat, + Speicherkontingent greift, Zugangsdaten-Mail kommt an. +6. Eigene Domain hinterlegen, TXT-Nachweis, prüfen, dass sie **wirklich ausgeliefert** + wird (nicht nur „nachgewiesen"). +7. Kündigen. Prüfen, dass Stripe es erfährt, die Leistung zum Periodenende endet, + Route und DNS-Eintrag verschwinden. +8. Zweiten Kauf als Privatperson, innerhalb 14 Tagen widerrufen. Prüfen: volle + Erstattung, Stornorechnung, Leistung endet. + +Jeder Schritt, der scheitert, ist ein Fund — und der Server darf dabei kaputtgehen, +Debian ist neu eingespielt in Minuten. + +--- + +## 6. Arbeitsweise in dieser Codebasis (für die neue Session) + +- **Eine zweite Claude-Session arbeitet im selben Arbeitsverzeichnis und im selben + Git-Index.** In dieser Nacht hat ein einziges `git commit` ohne Pfadangabe deren + vorgemerkte Dateien mitgenommen und dabei `VERSION` sowie zwei ihrer Dateien + zurückgedreht. **Immer** `git add -- ` und `git commit -F - -- `, + **nie** `git add -A`, `git add .`, `git commit -a` oder ein nacktes `git commit`. +- `pint` nur auf eigene Pfade, **nie** `--dirty` — das Repo ist unter der + Standardvorgabe nicht durchgängig formatiert und würde fremde Dateien umschreiben. +- Regeln R11–R24 in `CLAUDE.md` sind nicht verhandelbar und werden per Test erzwungen. + R22 besonders: eine Prüfrunde, eine Fix-Runde, dann parken. +- Tests laufen auf **SQLite im Speicher** (`phpunit.xml` erzwingt es), gleichzeitige + Läufe kollidieren also nicht, und die Entwicklungsdatenbank wird nie angefasst. +- Bricht die ganze Suite auf einmal zusammen, ist das fast immer eine Datei der + anderen Session mitten im Schreiben — einmal neu laufen lassen, bevor man sucht. +- Push: `git push "https://x-access-token:$TOKEN@git.bave.dev/boban/CluPilotCloud.git" main` + mit `GIT_ACCESS_TOKEN` aus der `.env`; ein einfaches `git push` scheitert. +- Ein Update auf dem Live-Server greift nur bei einem **`v*`-Tag** — `VERSION` anheben, + taggen, Tag mitpushen.