proxdeploy/DEVLOG.md

DEVLOG – ProxDeploy

Zeitübersicht

Gesamt: 8 h 14 min (Sitzung 1–4)

Zeiten stammen aus den Git-Commit-Zeitstempeln je Issue; Wartezeit auf Rückmeldungen ist enthalten.

Issue	Zeit
#001 Projekt-Setup	0 h 50 min
#002 Server-Verwaltung	0 h 11 min
#003 Verbindungstest	0 h 25 min
#004 Katalog	0 h 09 min
#005 Adapter und Profile	0 h 20 min
#006 Aufträge und Live-Fortschritt	0 h 15 min
#007 Template-Bau	0 h 12 min
#008 VM ausrollen und Assistent	0 h 36 min
#009 LXC	0 h 31 min
#010 Ubuntu	0 h 05 min
#011 Profil-Editor	0 h 10 min
#012 Vorlagen	0 h 11 min
#022 Profile im Template	0 h 22 min
#015 (Teil) SSH-Schlüssel	0 h 10 min
#021 Template-Bau ohne SSH	0 h 19 min + 0 h 35 min Abnahme
#013 CLI und API-Tokens	0 h 42 min
#014 Verlauf, Wiederholen, Aufräumen	1 h 21 min
#015 Benutzer, Passwort, Audit-Log	0 h 10 min
#016 OIDC	0 h 08 min
#017 Marken-Dateien	0 h 17 min
#018 README	0 h 02 min (parallel zu #019)
#019 Docker und LXC-Installer	0 h 20 min

Meilenstein	Zeit
v0.1.0	1 h 15 min
v0.2.0	1 h 32 min
v0.3.0	1 h 48 min
v0.4.0	0 h 42 min
v0.5.0	1 h 39 min
v0.6.0	0 h 40 min
v0.6.1	0 h 35 min

---

2026-10-12 · Sitzung 4 · 19:50–20:26

Issue: #021 (Abnahme), Vorüberlegung #020 Version: 0.6.1

Erledigt

• Freie Bau-Adresse gesucht (Ping/ARP-Probe vom Testhost, .150–.199 stumm) → 10.0.10.180
• #021 abgenommen: Template 9003 (Debian 12) ohne Node-SSH über die Bau-Adresse gebaut, daraus VM 111 pd-deb12 ohne Node-SSH ausgerollt
• Dabei gefunden und behoben: cloud-init-Laufwerk an ide2 wird vom Debian-12-Cloud-Kernel nicht gesehen → scsi1
• Fehlgeschlagenen ersten Bau mit proxdeploy cleanup aufgeräumt (VM 9003 gestoppt und gelöscht)

Entscheidungen

• cloud-init-Laufwerk an virtio-SCSI für neue Templates; vorhandene (9000–9002) bleiben – deren Kernel kennen SATA.
• Feldtest 8.x (#020) nicht als verschachtelte VM auf pve-demo: 7 GB RAM, VMs liefen dort auf dritter Virtualisierungsebene; braucht einen echten 8.x-Host.

---

2026-10-12 · Sitzung 3 · 14:39–17:40

Issue: #013–#019 Version: 0.4.0, 0.5.0, 0.6.0

Erledigt

• v0.3.0 freigegeben (Abnahme #021 bleibt offen, braucht eine freie IP)

• API-Tokens (pd_…, nur SHA-256), Bearer-Anmeldung, POST /auth/token für proxdeploy login, Verwaltung in den Einstellungen

• Kurze Anfragen: Server füllt Storage, Bridge, Node, Benutzer, Schlüssel; Abschlussbox serverseitig

• OpenAPI aus zod, Go-Typen per oapi-codegen, pnpm cli:pruefen

• CLI proxdeploy in Go 1.27.2 mit allen Befehlen der Vorgabe plus presets, template list, cancel; Ausgabe zeichengenau zum Mockup (Golden-File)

• Abnahme auf pve-demo per batch: pd-cli01 (VM 107, Debian 13 aus Template 9002, docker läuft) und pd-cli02 (CT 108, Ubuntu 24.04) parallel; das Verfolgen überstand einen App-Neustart mitten im Lauf

• 267 Vitest, 20 Playwright-Abläufe, Go-Tests grün

• Etappe 5 (v0.5.0): Verlauf mit Filtern in der URL, Wiederholen, Aufräumen (auf pve-demo: CT 109 nach Abbruch gelöscht, Original „aufgeräumt“); Benutzerverwaltung, Passwort ändern, Audit-Log-Ansicht; OIDC gegen Mock-IdP

• CLI: history und cleanup

• Gefunden: ssh2 erzeugt in ~0,4 % unlesbare ed25519-Schlüssel (war die Ursache des wackligen SSH-Tests) – behoben; „Einstellungen“ fehlte seit v0.3.0 in der Navigation

• 308 Vitest, 26 Playwright-Abläufe grün

• Etappe 6 (v0.6.0): Marken-Dateien per Skript (Texte als Pfade), README mit Banner und Screenshots, Docker Compose (lokal hochgefahren) und LXC-Installer – auf pve-demo in CT 109 installiert, darin Server angelegt, CLI-Login, Dry-Run und ein echter LXC (pd-abnahme, CT 110); Update-Pfad geprüft

• Gefunden: die Übersicht war seit Etappe 1 ein Platzhalter; opentype.js schreibt gelegentlich „NaN“ in Pfade

Entscheidungen

• Anfragen als Map, Antworten typisiert: Go-Structs aus oapi-codegen schickten leere Pflichtfelder und überschrieben Vorlagenwerte.
• [instances.<name>] in der Konfiguration statt profiles – „profile“ ist schon --profile.
• Strg+C hängt nur ab, Abbruch nur mit proxdeploy cancel.
• Ohne Terminal zeilenweise (je Phase eine Zeile), damit CI-Logs lesbar bleiben.
• Aufräumen löscht nur, was die Beschreibung „(Auftrag )“ trägt – deshalb setzt das Klonen die Beschreibung jetzt sofort; Templates nie.
• Sitzungen beenden über Benutzer.sitzungenAb statt einer Sitzungstabelle.
• SSO übernimmt nie ein lokales Konto über den Namen; die Rolle kommt bei jeder Anmeldung aus den Gruppen.
• Migrationen im Betrieb ohne Prisma-CLI, kompatibel zu _prisma_migrations; ein gemeinsames Laufzeit-Paket für Docker und LXC; der worker bekommt nur die Pakete, die er importiert (103 statt 741 MB).
• Gefunden durch Tests: SSE-Daten zeigten in einen wiederverwendeten Puffer (jetzt kopiert); mehrzeilige Proxmox-Parameter brachen die Dry-Run-Zeile (jetzt ⏎).

---

2026-10-12 · Sitzung 2 · 12:48–14:39

Issue: #009–#012, #015 (Teil), #021, #022 Version: 0.3.0-dev

Erledigt

• #009: LXC per pct exec (pd-ct01, Debian 13, docker im unprivilegierten CT) und per SSH in den Container (pd-ct02, Ubuntu 24.04) auf pve-demo
• #010: Ubuntu 24.04 als VM (pd-ubu01, Template 9001 im selben Auftrag gebaut)
• #011: Profil-Editor mit Live-Prüfung und Skriptvorschau
• #012: Vorlagen inkl. „Docker-Host klein“, im Assistenten und per API
• #022 (Wunsch Florian): Profile ins Template einbacken – Template 9002 tpl-debian-13-docker; Provisionierung 141 s → ~30 s
• #015 vorgezogen: SSH-Schlüssel hinterlegen (persönlich/Team), automatisch in jedem Gast
• #021: Template-Bau ohne SSH über Bau-Adresse (Mock-getestet, Abnahme auf pve-demo braucht eine freie IP)
• Florians Fragen beantwortet: was am Template anpassbar ist; Schlüssel/Anwendungen ins Template
• 253 Tests, 18 Playwright-Abläufe; main gepusht

Entscheidungen

• chrony nur in VMs (if: vm): unprivilegierte Container dürfen die Uhr nicht stellen.
• Profile mit {{ guest.* }} laufen beim Deploy erneut, auch wenn eingebacken – sonst fehlt z. B. der Benutzer in der docker-Gruppe (gefunden mit pd-test03).
• SSH-Schlüssel nicht ins Template, sondern in die Verwaltung (SchluesselQuelle) – beim Schlüsselwechsel bleibt es eine Stelle.
• Fähigkeitserkennung korrigiert: Template-Bau per API nur, wenn der Guest-Agent auch hineinkommt.
• Voll-Klon bleibt Standard; der Testhost kopiert zurzeit nur ~3–8 MB/s (Klon 8 min) – Linked Clones als spätere Option notiert.

---

2026-10-12 · Sitzung 1 · 08:45–11:35

Issue: #001 Version: 0.1.0, 0.2.0

Erledigt

• Auftrag gelesen, Rückfragen gestellt: Reverse-Proxy (ja), OIDC (implementieren, vorerst nur lokal testen), Testumgebung (folgt), CLI (Go)
• Umgebung geprüft: Docker 29 vorhanden, Node und Go fehlen → Builds und Tests laufen im Container
• Proxmox-API 8.x/9.x gegen API-Schema 9.2, Quellen der stable-8-Zweige und Release Notes geprüft (Ergebnis: docs/architektur.md Abschnitt 3)
• Image-URLs, Prüfsummen-Dateien, LXC-Template-Namen, Docker- und Zabbix-Repos per Abruf geprüft
• Git-Repository (main), CHANGELOG, DEVLOG, Architekturplan und 20 Issues angelegt
• Plan freigegeben: Ubuntu 26.04 dazu, Templates mit UEFI, Template-VMID = nächste freie im Template-Bereich, Namensabbildung bestätigt
• #003 abgeschlossen: Verbindungstest mit Fähigkeitserkennung und SSH-Host-Key-Pinning; 127 Tests
• Feldtest auf dem Testhost pve-demo (PVE 9.2.2): Rolle/Token nach Doku per SSH angelegt, Fingerprint und Host-Key gegen den Node verglichen, Test mit und ohne SSH – alles wie erwartet
• Meilenstein v0.1.0 abgeschlossen, getaggt und nach Gitea gepusht
• README als Zwischenstand angelegt (Florian: „readme im projekt fehlt“)
• #005 abgeschlossen: Adapter debian, Profil-Engine; base+docker+zabbix-agent echt in Containern auf Debian 12/13 und Ubuntu 22.04/24.04/26.04 inkl. Idempotenz
• #006 abgeschlossen: worker, Phasen, SSE, Live-Ansicht, VMID-Sperre
• #007 abgeschlossen: erstes echtes Template (9000, Debian 13) auf pve-demo in 5 min 26 s
• #008 abgeschlossen: erste echte VMs auf pve-demo – pd-test01 per API (base, docker), pd-test02 über den Assistenten (base, zabbix-agent), per SSH geprüft; 219 Tests, 12 Playwright-Abläufe
• Meilenstein v0.2.0 abgeschlossen, getaggt und gepusht
• #004 abgeschlossen: Katalog mit fünf Distributionen und drei Profilen, Abgleich, Katalogseite; 150 Tests, 12 Playwright-Abläufe
• #002 abgeschlossen: Server-Verwaltung mit Fingerprint-Pinning, Proxmox-Client, Proxmox-Mock (HTTPS, selbst signiert); 99 Tests, 10 Playwright-Abläufe
• Testhost 10.0.10.228 von Florian bereitgestellt (Installation läuft)
• #001 abgeschlossen: Grundgerüst mit Anmeldung, Seitenleiste, beiden Themes; 60 Tests, 8 Playwright-Abläufe (Desktop + 390 px)

Entscheidungen

• VM-Provisionierung immer über den Guest-Agent: funktioniert ohne SSH und liefert Live-Fortschritt. Snippets braucht es nur beim Template-Bau.
• Guest-Agent wird ins Template gebaut: keines der vier Cloud-Images bringt ihn mit, und ohne Agent gibt es bei DHCP keine IP und keine Provisionierung.
• LXC braucht für Profile immer SSH (zum Node oder in den Container): Proxmox hat keine Exec-API für Container.
• Template-Bau per API erst ab PVE 8.4 (download-url mit content=import); davor über SSH.
• Planer und Ausführung getrennt: der Dry-Run zeigt exakt den Plan, den der worker danach abarbeitet.
• CLI in Go mit aus OpenAPI generiertem Client.
• Konfiguration aus Laufzettel übernommen (gleicher Stack, Versionen dort bereits erprobt); Next auf 16.4.0 wie ProxLedger (Sicherheitsstand).
• Sitzungsgeheimnis und Datenschlüssel getrennt (SITZUNG_GEHEIMNIS, PROXDEPLOY_SCHLUESSEL): ein Tausch des Sitzungsgeheimnisses meldet nur alle ab, der Datenschlüssel darf sich nie ändern.
• Amber und Rot im hellen Theme abgedunkelt (#8A5A00, #B91C1C): die Originaltöne erreichen auf #F4F6F8 keine 4,5:1.
• TLS-Pinning über einen eigenen undici-Connector statt rejectUnauthorized: false + Nachprüfen: die Verbindung wird getrennt, bevor das Token gesendet wird. Sitzungs-Cache aus, sonst fehlt bei Wiederaufnahme das Zertifikat.
• Zugang zum Testhost über einen eigenen SSH-Schlüssel (~/.ssh/proxdeploy-testhost), nicht über das root-Passwort: Claude Code verweigert das Anlegen von Zugängen mit Passwort, und ein Schlüssel nur für diesen Host ist ohnehin der sauberere Weg.
• Trockenmodus im Proxmox-Client statt eigenem Planer: Dry-Run und Ernstfall laufen durch dieselben Phasen; Lesendes geht echt an Proxmox, Schreibendes wird aufgezeichnet. So können Plan und Wirklichkeit nicht auseinanderlaufen.
• Guest-Agent wird beim Template-Bau per Vorbereitungsstart eingebaut (vendor-data-Snippet), nicht bei jedem Deployment – Deployments laufen danach ohne SSH.
• Skripte base64 über file-write: Proxmox' eigene Kodierung scheitert an Umlauten (Fund beim ersten echten Deploy).
• Template-Bau ohne SSH (Bau-Adresse) ausgegliedert als #021, damit Etappe 2 nicht wartet.
• Deutsche Bezeichner wie in ProxLedger und Laufzettel; YAML-Schlüssel im Katalog bleiben englisch (Vorgabe).