268 lines
16 KiB
Markdown
268 lines
16 KiB
Markdown
# 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 `<subdomain>.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 -- <pfade>` und `git commit -F - -- <pfade>`,
|
||
**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.
|