docs: Architekturplan, Issues und Projektorganisation anlegen

Plan für ProxDeploy zur Freigabe: Architektur (app, worker, Postgres), Prisma-Entwurf, REST-API, Dateistruktur und sechs Etappen. Die Proxmox-API wurde gegen das Schema von PVE 9.2 und die Quellen der 8er-Zweige geprüft. Daraus folgt die Fähigkeitserkennung pro Server: Template-Bau per API erst ab 8.4, Snippets und LXC-Exec nur per SSH. Refs #001 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 09:05:57 +02:00
commit 6c16d56960
25 changed files with 1153 additions and 0 deletions
@@ -0,0 +1,27 @@
+# #001 Projekt-Setup
+**Status:** offen
+**Meilenstein:** v0.1.0
+**Labels:** chore, infrastruktur
+**Geschätzt:** 4 h   **Tatsächlich:** –
+
+## Ziel
+Lauffähiges Grundgerüst mit Projektorganisation, Design-Tokens und Prüfwerkzeugen.
+
+## Aufgaben
+- [ ] Git, `.gitignore`, CHANGELOG, DEVLOG, Issues, `docs/architektur.md`, `CLAUDE.md` mit Namensabbildung
+- [ ] Next.js 16, TypeScript strict, Tailwind 4 mit Tokens aus der Farbtabelle (dunkel + hell)
+- [ ] Prisma 7 + Docker-Compose für Entwicklung (Postgres), Vitest mit Test-DB, ESLint/Prettier
+- [ ] Versionen exakt pinnen und begründen; Build/Tests laufen in Docker (lokal kein Node)
+- [ ] Grundlayout: Seitenleiste mit Wortmarke, Server-Umschalter, Theme-Umschalter, `<Status>`-Komponente
+- [ ] Lokale Anmeldung (erster Admin aus `.env`), Sitzungs-Cookie, `/api/v1/gesundheit`
+- [ ] pino-Logger (JSON), `.env.example`
+
+## Akzeptanzkriterien
+- [ ] `lint`, `typecheck`, `test`, `build` grün im Container
+- [ ] Anmeldung funktioniert im gebauten Stand; keine Secrets im Repo
+
+## Abhängigkeiten
+–
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,26 @@
+# #002 Server-Verwaltung und Verschlüsselung
+**Status:** offen
+**Meilenstein:** v0.1.0
+**Labels:** feature, sicherheit
+**Geschätzt:** 6 h   **Tatsächlich:** –
+
+## Ziel
+Proxmox-Server anlegen, bearbeiten, löschen; Geheimnisse verschlüsselt.
+
+## Aufgaben
+- [ ] AES-256-GCM-Helfer mit Versionspräfix, Tests (falscher Schlüssel, manipulierte Daten)
+- [ ] Modell `Server`, Services, REST `/api/v1/server`, Formular mit Token-ID/Secret
+- [ ] TLS: Fingerprint holen (`POST /server/pruefen`), anzeigen, bestätigen, pinnen
+- [ ] Proxmox-Client mit undici-Agent und Fingerprint-Vergleich, UPID-Warten
+- [ ] SSH optional: Schlüsselpaar erzeugen, Einzeiler anzeigen, Host-Key pinnen
+- [ ] Protokolleintrag je Änderung
+
+## Akzeptanzkriterien
+- [ ] Secret erscheint nie in API-Antworten oder Logs
+- [ ] Falscher Fingerprint → klare Fehlermeldung, keine Verbindung
+
+## Abhängigkeiten
+#001
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,25 @@
+# #003 Verbindungstest und Fähigkeitserkennung
+**Status:** offen
+**Meilenstein:** v0.1.0
+**Labels:** feature, proxmox
+**Geschätzt:** 6 h   **Tatsächlich:** –
+
+## Ziel
+Button „Verbindung testen“ zeigt Version, Cluster/Nodes, Storages, Bridges/VLANs und was per API bzw. nur per SSH geht.
+
+## Aufgaben
+- [ ] `/version`, `/cluster/status`, `/cluster/resources`, `/nodes/{n}/storage`, `/nodes/{n}/network`, SDN-VNets
+- [ ] Rechte über `/access/permissions` gegen Rolle (8.x/9.x-Variante) abgleichen, fehlende einzeln nennen
+- [ ] Fähigkeiten: download-url import (≥ 8.4), import-from per Volume, Snippets-Storage, SSH erreichbar
+- [ ] Übersichtsseite mit Serverstatus und freien Ressourcen; Serverdetail mit Nodes/Storages/Bridges
+- [ ] Proxmox-Mock für Tests (8.3, 8.4, 9.2 als Varianten)
+
+## Akzeptanzkriterien
+- [ ] Gegen echten Proxmox geprüft (sobald Testumgebung da ist)
+- [ ] Tests decken 8.3 (SSH nötig), 8.4 und 9.2 ab
+
+## Abhängigkeiten
+#002
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,24 @@
+# #004 Katalog: Distributionen und Profile als Daten
+**Status:** offen
+**Meilenstein:** v0.2.0
+**Labels:** feature, katalog
+**Geschätzt:** 5 h   **Tatsächlich:** –
+
+## Ziel
+YAML-Katalog laden, validieren, in die DB synchronisieren, in der GUI ansehen und deaktivieren.
+
+## Aufgaben
+- [ ] zod-Schemas für `catalog/distros` und `catalog/profiles`
+- [ ] Debian 12/13, Ubuntu 22.04/24.04 (URLs/Prüfsummen geprüft am 2026-10-12)
+- [ ] Prüfsummen-Parser für beide Zeilenformate; LXC-Musterauflösung mit Versionssortierung
+- [ ] Sync beim worker-Start (Upsert, Aktiv-Schalter bleibt), fehlerhafte Datei überspringen + melden
+- [ ] Katalog-Seite (Distributionen, Profile, aktiv/inaktiv)
+
+## Akzeptanzkriterien
+- [ ] Unit-Tests für Schema, Sync und Muster
+
+## Abhängigkeiten
+#001
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,23 @@
+# #005 Adapter debian und Profil-Engine
+**Status:** offen
+**Meilenstein:** v0.2.0
+**Labels:** feature, engine
+**Geschätzt:** 6 h   **Tatsächlich:** –
+
+## Ziel
+Interface `FamilienAdapter`, Umsetzung `debian`, Profil `base` wird zu einem idempotenten Skript.
+
+## Aufgaben
+- [ ] Interface + Registry; `debian`-Adapter (apt, systemd, deb822, locale, keyboard, sshd_config.d)
+- [ ] Profilauflösung (requires, Reihenfolge, Variablen, Shell-Quoting)
+- [ ] Profil `base` (Updates, Guest-Agent, Europe/Berlin, de_DE.UTF-8, Tastatur de, unattended-upgrades, sudo-User, SSH-Härtung, chrony, fail2ban optional)
+- [ ] Snapshot-Tests der erzeugten Skripte; shellcheck auf die Ausgabe
+
+## Akzeptanzkriterien
+- [ ] Neues Profil/neuer Adapter braucht keine Änderung an Engine-Code
+
+## Abhängigkeiten
+#004
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,25 @@
+# #006 Aufträge, Phasen, worker und Live-Fortschritt
+**Status:** offen
+**Meilenstein:** v0.2.0
+**Labels:** feature, engine
+**Geschätzt:** 8 h   **Tatsächlich:** –
+
+## Ziel
+Hintergrund-Jobs mit Phasen in der DB, live per SSE in der Web-GUI.
+
+## Aufgaben
+- [ ] pg-boss im worker, Modelle `Auftrag`, `Phase`, `Logeintrag`, `VmidReservierung`
+- [ ] Phasen-Runner mit Ereignis-Senke (DB + NOTIFY), Fehler mit Ursache + Hinweis
+- [ ] SSE-Endpunkt mit Last-Event-ID, Polling-Fallback
+- [ ] VMID-Vergabe mit Advisory-Lock, Test mit parallelen Aufträgen
+- [ ] Live-Ansicht als Terminal-Karte, Detail-Log, Ergebnis-Karte
+
+## Akzeptanzkriterien
+- [ ] Zwei parallele Aufträge bekommen nie dieselbe VMID (Test)
+- [ ] Neuladen der Seite mitten im Auftrag zeigt den vollständigen Stand
+
+## Abhängigkeiten
+#003
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,25 @@
+# #007 Template-Bau für VMs
+**Status:** offen
+**Meilenstein:** v0.2.0
+**Labels:** feature, proxmox
+**Geschätzt:** 8 h   **Tatsächlich:** –
+
+## Ziel
+Cloud-Image laden, Prüfsumme prüfen, VM anlegen, Disk importieren, Guest-Agent einbauen, als Template markieren.
+
+## Aufgaben
+- [ ] Weg A (≥ 8.4): `download-url` (content=import, checksum) + `import-from` per Volume-ID
+- [ ] Weg B (SSH): Download + Prüfung auf dem Node, Import per `qm importdisk`/`import-from`
+- [ ] Hardware: q35, OVMF+EFI-Disk oder SeaBIOS, virtio-scsi-single, discard/ssd/iothread, CPU host, serielle Konsole, agent=1, cloud-init-Laufwerk
+- [ ] Guest-Agent einbauen: Snippet (SSH) oder Bau-Adresse + SSH in die VM
+- [ ] Template-Übersicht je Server/Node, VMID-Bereich konfigurierbar
+- [ ] Singleton je Server+Distribution
+
+## Akzeptanzkriterien
+- [ ] Debian-13-Template auf echtem Proxmox gebaut (8.x und 9.x, sobald verfügbar)
+
+## Abhängigkeiten
+#005, #006
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,24 @@
+# #008 Deploy-Assistent und VM ausrollen
+**Status:** offen
+**Meilenstein:** v0.2.0
+**Labels:** feature
+**Geschätzt:** 10 h   **Tatsächlich:** –
+
+## Ziel
+Debian-13-VM aus Template vollständig unattended, Assistent mit Dry-Run und CLI-Befehl.
+
+## Aufgaben
+- [ ] Planer VM (Phasen + geplante API-Aufrufe), `POST /auftraege/plan`
+- [ ] Ausführung: Klonen, Disk vergrößern, cloud-init (sshkeys korrekt kodiert, ciupgrade=0), Start, Agent, Provisionierung per Agent
+- [ ] Fehlendes Template → automatisch bauen anbieten
+- [ ] Assistent mit 9 Schritten, URL-Zustand, Handy-tauglich
+- [ ] Aufräumen nach Bestätigung
+
+## Akzeptanzkriterien
+- [ ] VM mit base-Profil per SSH erreichbar; Fehlerfall zeigt Ursache + Hinweis
+
+## Abhängigkeiten
+#007
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,21 @@
+# #009 LXC-Container ausrollen
+**Status:** offen
+**Meilenstein:** v0.3.0
+**Labels:** feature, proxmox
+**Geschätzt:** 8 h   **Tatsächlich:** –
+
+## Ziel
+LXC aus Proxmox-Template, Provisionierung per pct exec (SSH zum Node) oder SSH in den Container.
+
+## Aufgaben
+- [ ] aplinfo prüfen/herunterladen, Planer LXC, Swap, unprivilegiert, Features (nesting per API, keyctl nur per SSH)
+- [ ] Transport `ssh-node` (pct exec) und `ssh-gast` (Bereitstellungsschlüssel, danach entfernen)
+
+## Akzeptanzkriterien
+- [ ] LXC mit base auf echtem Proxmox, einmal mit und einmal ohne Node-SSH
+
+## Abhängigkeiten
+#008
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,21 @@
+# #010 Ubuntu 22.04 und 24.04
+**Status:** offen
+**Meilenstein:** v0.3.0
+**Labels:** feature, katalog
+**Geschätzt:** 3 h   **Tatsächlich:** –
+
+## Ziel
+Ubuntu als VM und LXC über den debian-Adapter.
+
+## Aufgaben
+- [ ] Unterschiede im Adapter (Codename-Ermittlung, Locale-Paket, unattended-upgrades)
+- [ ] ggf. Ubuntu 26.04 (offener Punkt)
+
+## Akzeptanzkriterien
+- [ ] Je eine Ubuntu-VM und ein Ubuntu-LXC ausgerollt
+
+## Abhängigkeiten
+#009
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,22 @@
+# #011 Profile docker und zabbix-agent, Variablen, Editor
+**Status:** offen
+**Meilenstein:** v0.3.0
+**Labels:** feature
+**Geschätzt:** 6 h   **Tatsächlich:** –
+
+## Ziel
+Kombinierbare Profile mit Variablen; eigene Profile im YAML-Editor.
+
+## Aufgaben
+- [ ] docker (deb822, nesting bei LXC automatisch), zabbix-agent (7.0 LTS, Server/ServerActive)
+- [ ] Variablen als Formularfelder; Ausgrauen ohne Umsetzung für die Familie
+- [ ] YAML-Editor mit Validierung und Fehlerstelle
+
+## Akzeptanzkriterien
+- [ ] docker run hello-world im ausgerollten Gast erfolgreich
+
+## Abhängigkeiten
+#005
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,20 @@
+# #012 Vorlagen (Presets)
+**Status:** offen
+**Meilenstein:** v0.3.0
+**Labels:** feature
+**Geschätzt:** 3 h   **Tatsächlich:** –
+
+## Ziel
+Gespeicherte Kombinationen, im Assistenten mit einem Klick vorbelegbar.
+
+## Aufgaben
+- [ ] CRUD, „aus diesem Auftrag als Vorlage speichern“, Beispiel „Docker-Host klein“
+
+## Akzeptanzkriterien
+- [ ] `--preset` in API und Assistent identisch aufgelöst
+
+## Abhängigkeiten
+#008
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,23 @@
+# #013 CLI proxdeploy (Go)
+**Status:** offen
+**Meilenstein:** v0.4.0
+**Labels:** feature, cli
+**Geschätzt:** 12 h   **Tatsächlich:** –
+
+## Ziel
+Alle Befehle aus der Vorgabe, Ausgabe exakt im Format der Vorgabe.
+
+## Aufgaben
+- [ ] OpenAPI aus zod, Go-Client per oapi-codegen, Prüfung auf Aktualität
+- [ ] login, servers, distros, profiles, vm, lxc, template build, batch, status, logs --follow
+- [ ] Renderer: Farbe 24-bit/256/aus, --ascii, --quiet, --json, --dry-run; Golden-Tests
+- [ ] Release-Builds für linux/darwin/windows × amd64/arm64
+
+## Akzeptanzkriterien
+- [ ] Ausgabe entspricht zeichengenau dem Mockup (Golden-File)
+
+## Abhängigkeiten
+#008, #012
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,21 @@
+# #014 Verlauf und Wiederholen
+**Status:** offen
+**Meilenstein:** v0.5.0
+**Labels:** feature
+**Geschätzt:** 4 h   **Tatsächlich:** –
+
+## Ziel
+Alle Aufträge filterbar, mit gleichen Parametern wiederholen.
+
+## Aufgaben
+- [ ] Filter Server/Typ/Distribution/Status, Seitenblättern
+- [ ] Wiederholen (neue VMID/Name abfragen)
+
+## Akzeptanzkriterien
+- [ ] Filter bleiben in der URL
+
+## Abhängigkeiten
+#008
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,22 @@
+# #015 Rollen, Benutzer, Tokens, Audit-Log
+**Status:** offen
+**Meilenstein:** v0.5.0
+**Labels:** feature, sicherheit
+**Geschätzt:** 6 h   **Tatsächlich:** –
+
+## Ziel
+Admin/Operator serverseitig erzwungen, jede Aktion protokolliert.
+
+## Aufgaben
+- [ ] Rechte-Tabelle, strukturelle Prüfung aller Route Handler (Test)
+- [ ] Benutzerverwaltung, CLI-Tokens, SSH-Keys über `SchluesselQuelle`
+- [ ] Audit-Log-Ansicht mit Filter
+
+## Akzeptanzkriterien
+- [ ] Operator kann keine Server/Katalog/Benutzer ändern (Tests)
+
+## Abhängigkeiten
+#001
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,20 @@
+# #016 Anmeldung per OIDC
+**Status:** offen
+**Meilenstein:** v0.5.0
+**Labels:** feature, sicherheit
+**Geschätzt:** 4 h   **Tatsächlich:** –
+
+## Ziel
+Optionale OIDC-Anmeldung (z. B. authentik), Rollen über Gruppen-Claim.
+
+## Aufgaben
+- [ ] openid-client mit PKCE, Discovery, Gruppen → Rolle, Konto-Verknüpfung
+
+## Akzeptanzkriterien
+- [ ] Tests gegen einen Mock-IdP (echter IdP später)
+
+## Abhängigkeiten
+#015
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,21 @@
+# #017 Branding-Assets
+**Status:** offen
+**Meilenstein:** v0.6.0
+**Labels:** design
+**Geschätzt:** 4 h   **Tatsächlich:** –
+
+## Ziel
+Alle Logo-Varianten, Banner, Favicons, Manifest-Icons nach Vorgabe.
+
+## Aufgaben
+- [ ] symbol(-light), icon-small, avatar, logo(-light), banner 1280×640
+- [ ] Favicon 16/32, Apple-Touch-Icon, Manifest-Icons per Skript aus SVG
+
+## Akzeptanzkriterien
+- [ ] Darstellung in beiden Themes geprüft
+
+## Abhängigkeiten
+#001
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,21 @@
+# #018 README und Dokumentation
+**Status:** offen
+**Meilenstein:** v0.6.0
+**Labels:** doku
+**Geschätzt:** 4 h   **Tatsächlich:** –
+
+## Ziel
+README mit Banner, Screenshots, Installation, CLI, Proxmox-Rechten, neuer Distribution, eigenem Profil.
+
+## Aufgaben
+- [ ] Screenshots aus dem gebauten Stand
+- [ ] Hinweis: unabhängiges Tool, nicht von Proxmox Server Solutions
+
+## Akzeptanzkriterien
+- [ ] Anleitungen einmal Schritt für Schritt nachvollzogen
+
+## Abhängigkeiten
+#013
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,21 @@
+# #019 Docker-Image und LXC-Installer
+**Status:** offen
+**Meilenstein:** v0.6.0
+**Labels:** infrastruktur
+**Geschätzt:** 6 h   **Tatsächlich:** –
+
+## Ziel
+Produktionsbetrieb per Docker Compose oder in einem Debian-LXC.
+
+## Aufgaben
+- [ ] Dockerfile (standalone, non-root), Compose mit migrate
+- [ ] `deploy/install-lxc.sh` (auf dem Proxmox-Host), Update-Pfad
+
+## Akzeptanzkriterien
+- [ ] Installer in echtem LXC durchgelaufen
+
+## Abhängigkeiten
+#001
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,21 @@
+# #020 Feldtest 8.x und 9.x, Version 1.0.0
+**Status:** offen
+**Meilenstein:** v1.0.0
+**Labels:** test
+**Geschätzt:** 6 h   **Tatsächlich:** –
+
+## Ziel
+Vollständiger Durchlauf gegen echte Proxmox-Hosts beider Hauptversionen.
+
+## Aufgaben
+- [ ] Matrix: VM/LXC × Debian/Ubuntu × mit/ohne SSH × 8.x/9.x
+- [ ] Gefundene Fehler als eigene Issues
+
+## Akzeptanzkriterien
+- [ ] Alle Kombinationen grün oder mit Begründung ausgeschlossen
+
+## Abhängigkeiten
+alle
+
+## Notizen / Entscheidungen
+–
@@ -0,0 +1,26 @@
+# Issue-Übersicht
+
+Details und Architektur: [../architektur.md](../architektur.md). Zeiten werden aus dem [DEVLOG](../../DEVLOG.md) übernommen.
+
+| Nr. | Titel | Status | Meilenstein | Geschätzt | Tatsächlich |
+|---|---|---|---|---|---|
+| [#001](001-projekt-setup.md) | Projekt-Setup | offen | v0.1.0 | 4 h | – |
+| [#002](002-verschluesselung-server.md) | Server-Verwaltung und Verschlüsselung | offen | v0.1.0 | 6 h | – |
+| [#003](003-verbindungstest.md) | Verbindungstest und Fähigkeitserkennung | offen | v0.1.0 | 6 h | – |
+| [#004](004-katalog.md) | Katalog: Distributionen und Profile als Daten | offen | v0.2.0 | 5 h | – |
+| [#005](005-adapter-profile.md) | Adapter debian und Profil-Engine | offen | v0.2.0 | 6 h | – |
+| [#006](006-auftraege-sse.md) | Aufträge, Phasen, worker und Live-Fortschritt | offen | v0.2.0 | 8 h | – |
+| [#007](007-template-bau.md) | Template-Bau für VMs | offen | v0.2.0 | 8 h | – |
+| [#008](008-vm-ausrollen.md) | Deploy-Assistent und VM ausrollen | offen | v0.2.0 | 10 h | – |
+| [#009](009-lxc.md) | LXC-Container ausrollen | offen | v0.3.0 | 8 h | – |
+| [#010](010-ubuntu.md) | Ubuntu 22.04 und 24.04 | offen | v0.3.0 | 3 h | – |
+| [#011](011-profile-docker-zabbix.md) | Profile docker und zabbix-agent, Variablen, Editor | offen | v0.3.0 | 6 h | – |
+| [#012](012-vorlagen.md) | Vorlagen (Presets) | offen | v0.3.0 | 3 h | – |
+| [#013](013-cli.md) | CLI proxdeploy (Go) | offen | v0.4.0 | 12 h | – |
+| [#014](014-verlauf.md) | Verlauf und Wiederholen | offen | v0.5.0 | 4 h | – |
+| [#015](015-rollen-audit.md) | Rollen, Benutzer, Tokens, Audit-Log | offen | v0.5.0 | 6 h | – |
+| [#016](016-oidc.md) | Anmeldung per OIDC | offen | v0.5.0 | 4 h | – |
+| [#017](017-branding.md) | Branding-Assets | offen | v0.6.0 | 4 h | – |
+| [#018](018-readme.md) | README und Dokumentation | offen | v0.6.0 | 4 h | – |
+| [#019](019-installer.md) | Docker-Image und LXC-Installer | offen | v0.6.0 | 6 h | – |
+| [#020](020-feldtest.md) | Feldtest 8.x und 9.x, Version 1.0.0 | offen | v1.0.0 | 6 h | – |