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,15 @@
+node_modules/
+.next/
+out/
+dist/
+coverage/
+*.tsbuildinfo
+next-env.d.ts
+src/generated/
+.env
+.env.*
+!.env.example
+cli/bin/
+playwright-report/
+test-results/
+.DS_Store
@@ -0,0 +1,20 @@
+# Changelog
+
+Alle nennenswerten Änderungen an ProxDeploy werden in dieser Datei dokumentiert.
+
+Das Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.1.0/),
+und dieses Projekt folgt [Semantic Versioning](https://semver.org/lang/de/).
+
+## [Unveröffentlicht]
+
+### Hinzugefügt
+- Architektur- und Umsetzungsplan (`docs/architektur.md`) mit Prüfung der Proxmox-API 8.x/9.x und der Image-Quellen (#001)
+- Issues #001–#020 für die sechs Etappen und den Feldtest (#001)
+
+### Geändert
+
+### Behoben
+
+### Entfernt
+
+### Sicherheit
@@ -0,0 +1,37 @@
+# DEVLOG – ProxDeploy
+
+## Zeitübersicht
+
+**Gesamt:** 0 h 25 min (laufende Sitzung)
+
+Zeiten stammen aus den Git-Commit-Zeitstempeln je Issue; Wartezeit auf Rückmeldungen ist enthalten.
+
+| Issue | Zeit |
+|---|---|
+| #001 Projekt-Setup | 0 h 25 min (laufend) |
+
+| Meilenstein | Zeit |
+|---|---|
+| v0.1.0 | – |
+
+---
+
+## 2026-10-12 · Sitzung 1 · 08:45–laufend
+**Issue:** #001
+**Version:** 0.1.0-dev
+
+### 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
+
+### 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.
+- **Deutsche Bezeichner** wie in ProxLedger und Laufzettel; YAML-Schlüssel im Katalog bleiben englisch (Vorgabe).
@@ -0,0 +1,602 @@
+# ProxDeploy – Architektur- und Umsetzungsplan
+
+Stand: 2026-10-12 · Version 0.1.0-dev · **Entwurf zur Freigabe**
+
+## 1. Überblick
+
+```
+ Browser (Web-GUI)        Terminal (proxdeploy, Go)
+        │  Cookie                 │  Bearer-Token
+        └──────────┬──────────────┘
+                   ▼  REST /api/v1 + SSE
+┌────────────────────────────────────────────────────────────────────────┐
+│ ProxDeploy (Docker Compose oder Debian-LXC), hinter Reverse-Proxy       │
+│  ┌──────────────────────┐   pg-boss    ┌────────────────────────────┐   │
+│  │ app (Next.js)        │──Auftrag────▶│ worker (Node)              │   │
+│  │ UI · REST-API · SSE  │◀─LISTEN/─────│ Engine: Planer, Phasen,    │   │
+│  │ Dry-Run (Planer)     │   NOTIFY     │ Proxmox-Client, Adapter    │   │
+│  └──────────┬───────────┘              └──────┬───────────┬─────────┘   │
+│             └────────── PostgreSQL ───────────┘           │             │
+└───────────────────────────────────────────────────────────┼─────────────┘
+                        HTTPS :8006 (Token, Fingerprint-Pin) │ optional SSH
+                                                             ▼
+                              Proxmox VE 8.x / 9.x (Einzelhost oder Cluster)
+                                     │ Guest-Agent / SSH in den Gast
+                                     ▼
+                                VM oder LXC (Debian, Ubuntu, …)
+```
+
+- **Ein Backend, zwei Oberflächen.** Die Engine (`src/engine/`) ist frameworkfrei und enthält die
+  gesamte Deploy-Logik. Die Web-GUI und die CLI sprechen ausschließlich die REST-API; die GUI hat
+  keinen Sonderweg an der API vorbei (Server Actions rufen dieselben Services wie die Route Handler).
+- **app** liefert UI, REST-API, OpenAPI-Spezifikation und SSE-Ströme. Sie führt nie ein Deployment
+  aus, nur den **Planer** für den Dry-Run (reine Funktion, keine schreibenden Proxmox-Aufrufe).
+- **worker** ist derselbe Codestand als eigener Prozess und arbeitet Aufträge aus der pg-boss-Queue ab.
+  Jede Phasenänderung wird in die DB geschrieben und per `NOTIFY auftrag_<id>` gemeldet; die app hängt
+  sich mit `LISTEN` daran und streamt an alle offenen SSE-Verbindungen. Ein Neuladen der Seite oder ein
+  Wiederverbinden der CLI liest zuerst den Stand aus der DB und setzt dann ab `Last-Event-ID` fort.
+- **PostgreSQL** ist die einzige Datenhaltung (inkl. Queue). Keine Dateien außer dem Katalog im Image.
+
+## 2. Tech-Stack
+
+| Bereich | Wahl | Begründung |
+|---|---|---|
+| Web/API | Next.js 16 (App Router), React 19, TypeScript strict | Vorgabe; wie Laufzettel/ProxLedger |
+| Styling | Tailwind CSS 4, Tokens als CSS-Variablen unter `@theme`, eigene Komponenten | Vorgabe, kein Admin-Template |
+| Schriften | Space Grotesk, JetBrains Mono über `@fontsource-variable`, selbst gehostet | keine Google-Anfragen aus dem Intranet |
+| Icons | Lucide (Stroke) + die Statussymbole ✓ ◐ ✗ ○ als Text | Status nie nur Farbe |
+| DB | PostgreSQL 17, Prisma 7 mit `@prisma/adapter-pg` | Vorgabe |
+| Jobs | pg-boss auf derselben Datenbank | Vorgabe; kein Redis nötig |
+| Validierung | zod (Request, Katalog-YAML, Profil-Editor) | eine Schemaquelle für API, OpenAPI und Katalog |
+| OpenAPI | aus den zod-Schemas erzeugt (`/api/v1/openapi.json`) | Go-Client wird daraus generiert |
+| Auth | `jose` (Sitzungs-Cookie), `openid-client` (OIDC, PKCE), argon2id | wie ProxLedger; kein Auth.js-Beta |
+| SSH | `ssh2` (Node) | Snippets schreiben, `pct exec`, SSH in den Gast |
+| YAML | `yaml` (eemeli) | erhält Kommentare im Profil-Editor |
+| Logs | `pino` (JSON auf stdout), zusätzlich pro Auftrag in der DB | Betrieb + GUI |
+| Tests | Vitest (Engine, API mit echter Test-DB), Playwright (Assistent, Live-Ansicht, 390 px) | |
+| CLI | **Go**, statisches Binary | siehe Abschnitt 9 |
+
+Exakte Versionen werden in #001 gegen npm/Go-Proxy geprüft und **gepinnt** (abgelagerte Fassungen,
+keine RCs) und in `CLAUDE.md` festgehalten.
+
+## 3. Was geht per Proxmox-API, was braucht SSH
+
+Geprüft am 2026-10-12 gegen das API-Schema von PVE 9.2 (`apidoc.js`), die Quellen der Zweige
+`stable-8`/`stable-bookworm` (pve-storage, qemu-server, pve-container) und die Release Notes
+8.0–9.2. Belege stehen in den Issues #005 und #007.
+
+| Fähigkeit | PVE 8.0–8.3 | PVE 8.4+ / 9.x | Weg |
+|---|---|---|---|
+| Cloud-Image herunterladen + Checksumme prüfen (`download-url`, `content=import`, qcow2/raw/vmdk) | **nein** (nur iso/vztmpl, OVA ab 8.2) | ja | API |
+| Disk aus heruntergeladenem Image anlegen (`scsi0: <stor>:0,import-from=<stor>:import/<datei>`) | nur per absolutem Pfad → nur `root@pam` | ja, per Volume-ID | API |
+| Klonen, Konfiguration, cloud-init (`ciuser`, `sshkeys`, `ipconfigN`, `nameserver`, `searchdomain`, `ciupgrade`), Start/Stopp, Template | ja | ja | API |
+| Guest-Agent `exec`, `exec-status`, `file-write` (max. 60 KiB je Aufruf), `network-get-interfaces` | ja (`VM.Monitor`) | ja (`VM.GuestAgent.*` ab 9.0) | API |
+| LXC anlegen (`ssh-public-keys`, `net0` mit `tag`, `unprivileged`, `features: nesting`) | ja | ja | API |
+| LXC-Template-Liste und -Download (`aplinfo`) | ja | ja | API |
+| LXC-IP auslesen (`lxc/{id}/interfaces`) | ja | ja | API |
+| LXC-Features außer `nesting` (`keyctl`, `fuse`, …) | nur `root@pam` per Ticket, **kein Token** | dito | SSH (`pct set`) |
+| **Befehle im LXC ausführen** | **keine API** | **keine API** | SSH (`pct exec` auf dem Node **oder** SSH in den Container) |
+| **cloud-init-Snippets schreiben** (`cicustom`) | **keine API** (Upload nur iso/vztmpl/import) | dito | SSH |
+| Zertifikats-Fingerprint | `nodes/{n}/certificates/info` | dito | API (nach erstem Pin) |
+
+**Folgerungen für die Engine:**
+
+1. **Fähigkeitserkennung pro Server** (`src/engine/proxmox/faehigkeiten.ts`), beim Verbindungstest und
+   vor jedem Auftrag aufgefrischt: PVE-Version je Node, Storages mit Inhaltstyp `import`, `snippets`,
+   `vztmpl`, `images`/`rootdir`, Rechte des Tokens (`GET /access/permissions`), SSH konfiguriert und
+   erreichbar. Daraus ergibt sich pro Server und Vorgang die **Strategie**, die in der GUI sichtbar ist
+   („Template-Bau: per API“ / „braucht SSH, weil PVE 8.3“).
+2. **VM-Provisionierung läuft immer über den Guest-Agent** (Skript per `file-write` in 60-KiB-Stücken,
+   dann `exec` + `exec-status`-Polling). Damit funktioniert sie **ohne SSH** und liefert Live-Fortschritt.
+   Standard-cloud-init von Proxmox liefert nur Benutzer, Keys und Netz; `ciupgrade=0`, Updates macht
+   das Profil `base` (sichtbar als eigene Phase statt stummem Boot-Upgrade).
+3. **Der Guest-Agent ist in keinem der vier Cloud-Images vorinstalliert** (geprüft in den Paketlisten).
+   Deshalb wird er **beim Template-Bau** eingebaut, damit jeder Klon sofort einen Agent hat:
+   - mit SSH zum Node: einmaliger Vorbereitungsstart mit `cicustom: vendor=<snippet>` (installiert
+     `qemu-guest-agent`, `cloud-init clean`, `poweroff`) – funktioniert auch mit DHCP;
+   - ohne SSH: Vorbereitungsstart mit einer **Bau-Adresse** (statische IP aus den Server-Einstellungen)
+     und dem ProxDeploy-Bereitstellungsschlüssel per `sshkeys`, dann SSH **in die VM**, dieselben Schritte.
+   - Danach `cloud-init clean`, Maschinen-ID leeren, als Template markieren.
+4. **LXC-Provisionierung** braucht immer SSH – bevorzugt `pct exec` über SSH zum Node (kein Netzweg
+   zum Container nötig), sonst SSH direkt in den Container (Bereitstellungsschlüssel per
+   `ssh-public-keys`, IP aus Konfiguration bzw. `lxc/{id}/interfaces`). Das `debian`-Standard-Template
+   bringt `openssh-server` mit; der Bereitstellungsschlüssel wird am Ende wieder entfernt.
+5. **Ohne jedes SSH** sind möglich: VM aus vorhandenem oder per API gebautem Template (PVE ≥ 8.4) mit
+   allen Profilen; LXC ohne Profile (nur Anlegen + Start). Die GUI graut nicht Mögliches mit Begründung aus.
+
+**SSH-Zugang** pro Server: ProxDeploy erzeugt ein ed25519-Schlüsselpaar, zeigt den öffentlichen
+Schlüssel samt Einzeiler zum Hinterlegen, pinnt den Host-Key beim ersten Test (Bestätigung durch den
+Admin). Benutzer `root` auf dem Node (für `pct` und `/var/lib/vz/snippets` nötig).
+
+## 4. Proxmox-Rechte (Rolle `ProxDeploy`)
+
+Wird im README ausführlich dokumentiert, inkl. `pveum`-Befehlen.
+
+- **Gemeinsam:** `VM.Allocate VM.Clone VM.Audit VM.Config.Disk VM.Config.CDROM VM.Config.CPU
+  VM.Config.Memory VM.Config.Network VM.Config.HWType VM.Config.Options VM.Config.Cloudinit
+  VM.PowerMgmt VM.Console Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit SDN.Use
+  SDN.Audit Sys.Audit Pool.Audit`
+- **nur 8.x:** `VM.Monitor` (Guest-Agent); vor 8.2 statt `Sys.AccessNetwork` → `Sys.Modify`
+- **8.2+ und 9.x:** `Sys.AccessNetwork` auf `/nodes/<node>` (für `download-url`)
+- **nur 9.x:** `VM.GuestAgent.Audit VM.GuestAgent.Unrestricted` (ersetzt `VM.Monitor`)
+- **optional:** `Datastore.Allocate` (heruntergeladene Images/Templates wieder löschen),
+  `Sys.Modify` (privilegierte Container ab 9.0)
+- ACL: `/vms` oder ein Pool, `/storage/<id>`, `/sdn/zones/localnetwork` (bzw. konkrete Zonen), `/`
+  nur für `Sys.Audit`. Der Verbindungstest gleicht die effektiven Rechte gegen diese Liste ab und
+  nennt fehlende Rechte einzeln.
+
+## 5. Distributionen, Adapter, Profile
+
+### Katalog als Daten
+
+`catalog/distros/*.yaml` und `catalog/profiles/*.yaml` liegen im Repo und im Image. Der worker
+synchronisiert sie beim Start in die DB (Upsert über `id`, Hash der Datei; Aktiv-Schalter und eigene
+Profile bleiben unangetastet). Die **YAML-Schlüssel bleiben englisch** wie in der Vorgabe – sie sind
+ein Austauschformat, kein Code-Bezeichner. Validiert mit zod; ein fehlerhafter Eintrag wird mit
+Dateiname und Pfad gemeldet und übersprungen, nicht der Start abgebrochen.
+
+Mitgeliefert (URLs am 2026-10-12 per Abruf geprüft): Debian 12, Debian 13, Ubuntu 22.04, Ubuntu 24.04.
+Ubuntu 26.04 LTS ist ebenfalls verfügbar (Cloud-Image und LXC-Template) – **Vorschlag: mitliefern**.
+
+- Debian: `cloud.debian.org/images/cloud/<codename>/latest/debian-<n>-genericcloud-amd64.qcow2`,
+  `SHA512SUMS` (Zeilenformat `<hash>␣␣<datei>`), Benutzer `debian`
+- Ubuntu: `cloud-images.ubuntu.com/<codename>/current/<codename>-server-cloudimg-amd64.img` (qcow2),
+  `SHA256SUMS` (Zeilenformat `<hash>␣*<datei>`), Benutzer `ubuntu`
+- LXC: alle `*-standard_*_amd64.tar.zst`; bei mehreren Treffern (Debian 13: `13.1-2` und `13.6-1`)
+  gewinnt die höchste Version (Versionssortierung).
+
+Ergänzende Felder gegenüber der Vorgabe: `codename`, `arch` (vorerst `amd64`), `vm.bios_default`
+(`ovmf`/`seabios`), `vm.template_vmid_offset` (z. B. Debian 13 → 9013), `vm.min_disk_gb`.
+
+### Provisionierungs-Adapter
+
+`src/engine/adapter/schnittstelle.ts` definiert `FamilienAdapter` – jede Methode liefert ein
+**idempotentes Shell-Fragment** (kein Ausführen im Adapter, damit testbar und im Dry-Run anzeigbar):
+
+```ts
+interface FamilienAdapter {
+  familie: string;                        // "debian"
+  aktualisieren(): Skript;
+  paketeInstallieren(pakete: string[]): Skript;
+  dienstAktivieren(name: string, starten?: boolean): Skript;
+  repoHinzufuegen(repo: PaketQuelle): Skript;     // Schlüssel-URL, URIs, Suites, Komponenten
+  zeitzoneSetzen(tz: string): Skript;
+  localeSetzen(locale: string): Skript;
+  tastaturSetzen(layout: string): Skript;
+  benutzerAnlegen(b: Benutzerangaben): Skript;    // inkl. sudo, authorized_keys
+  sshHaerten(o: SshHaertung): Skript;             // PasswordAuthentication no, PermitRootLogin no
+  gastAgentInstallieren(): Skript;
+  automatischeUpdates(an: boolean): Skript;
+  fakten(): Skript;                                // gibt OS-Fakten (codename, ID) als JSON aus
+}
+```
+
+Registriert in `src/engine/adapter/index.ts`. Ein neuer Adapter (`rhel`, `alpine`, `suse`) ist eine
+neue Datei + ein Eintrag in der Registry + Tests; Katalog und Profile verweisen per `family` darauf.
+
+### Profile
+
+Ein Profil ist eine Liste deklarativer **Schritte** je Familie, die der Adapter in Shell übersetzt.
+Für Sonderfälle gibt es `run` (rohes Shell, ausdrücklich nicht portabel). Variablen werden als
+Formularfelder angezeigt und mit `{{ var.name }}` eingesetzt (eigene kleine Template-Funktion,
+nur Ersetzung, keine Logik; Werte werden für Shell gequotet).
+
+```yaml
+id: zabbix-agent
+name: Zabbix Agent 2
+description: Zabbix Agent 2 (7.0 LTS) aus dem offiziellen Repo
+requires: [base]
+variables:
+  - { name: server, label: Zabbix-Server, type: string, required: true }
+  - { name: server_active, label: ServerActive, type: string, default: "{{ var.server }}" }
+lxc: {}                       # z. B. docker: { features: { nesting: true } }
+families:
+  debian:
+    - repo_deb: "https://repo.zabbix.com/zabbix/7.0/{{ os.id }}/pool/main/z/zabbix-release/zabbix-release_latest_7.0+{{ os.id }}{{ os.version_id }}_all.deb"
+    - packages: [zabbix-agent2]
+    - file: { path: /etc/zabbix/zabbix_agent2.d/proxdeploy.conf, content: "Server={{ var.server }}\nServerActive={{ var.server_active }}\nHostname={{ guest.name }}\n" }
+    - service: { name: zabbix-agent2, enable: true, restart: true }
+```
+
+Fehlt `families.<familie>` für die gewählte Distribution, ist das Profil im Assistenten ausgegraut
+(„keine Umsetzung für Familie rhel“). Eigene Profile werden im YAML-Editor angelegt, gegen dasselbe
+zod-Schema geprüft und mit `origin: custom` gespeichert; Katalog-Profile sind schreibgeschützt,
+lassen sich aber als Kopie bearbeiten.
+
+Mitgeliefert: `base`, `docker` (Docker CE, deb822 `docker.sources`, Key `/etc/apt/keyrings/docker.asc`,
+Pakete `docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin`; LXC:
+`nesting=1`), `zabbix-agent` (7.0 LTS; 8.0 hat noch keine Agent-Pakete).
+
+## 6. Engine: Aufträge und Phasen
+
+```
+src/engine/
+  proxmox/       client.ts (fetch + undici, Fingerprint-Pinning), endpunkte/*.ts, faehigkeiten.ts, aufgaben.ts (UPID warten)
+  ssh/           verbindung.ts, node.ts (pct exec, Snippet schreiben), gast.ts
+  katalog/       schema.ts (zod), laden.ts, pruefsumme.ts (beide Zeilenformate)
+  adapter/       schnittstelle.ts, debian.ts, index.ts
+  profile/       aufloesen.ts (Reihenfolge, requires, Variablen), rendern.ts (→ Skript)
+  planer/        vm.ts, lxc.ts, template.ts  → Plan { phasen[], aufrufe[] }  (rein, keine I/O außer Lesen)
+  ablauf/        ausfuehren.ts (Phasen-Runner), ereignisse.ts (Senke-Interface), fehler.ts (Ursache + Hinweis)
+  transport/     gastagent.ts, ssh-node.ts, ssh-gast.ts  → gemeinsames Interface `Ausfuehrer`
+  sperren.ts     VMID-Reservierung
+```
+
+**Planer und Ausführung trennen.** Der Planer bekommt eine validierte Anfrage + einen *lesenden*
+Proxmox-Zugriff + Fähigkeiten und liefert den Plan: die Phasen und je Phase die geplanten
+API-Aufrufe (`POST /nodes/pve01/qemu/9013/clone newid=120 full=1 …`). Der Dry-Run zeigt genau diesen
+Plan; die Ausführung arbeitet ihn ab. So können Dry-Run und Wirklichkeit nicht auseinanderlaufen.
+
+**Phasen** (VM): Prüfungen → Template (übersprungen, wenn vorhanden) → Klonen → Hardware & Disk →
+cloud-init → Start → Guest-Agent → Provisionierung (je Profil eine Unterzeile im Log) → Abschluss.
+LXC: Prüfungen → LXC-Template → Anlegen → Start → Netzwerk → Provisionierung → Abschluss.
+Jede Phase schreibt `status`, `detail` (der Muted-Text der CLI), `dauer`, bei Fehler `ursache` und
+`hinweis`. **Web und CLI rendern nur diese Felder** – kein Text wird in einem Client erfunden.
+
+**VMID-Vergabe ohne Doppelungen:** `pg_advisory_xact_lock(hash(serverId))`, dann nächste freie ID
+aus `/cluster/resources` ∪ Tabelle `VmidReservierung`, Reservierung schreiben, Sperre fällt mit der
+Transaktion. Die Reservierung gilt bis Auftragsende (bzw. Ablauf nach 2 h als Sicherung). Beim
+`create`/`clone` wird ein Konflikt (`already exists`) einmal mit neuer ID wiederholt.
+
+**Fehler und Aufräumen:** Ein Fehler beendet den Auftrag mit Status `FEHLGESCHLAGEN`, die Phase trägt
+Ursache und Lösungshinweis (z. B. „Token fehlt VM.GuestAgent.Unrestricted auf /vms/120 → Rolle
+ergänzen“). Was angelegt wurde, steht in `Auftrag.angelegt` (VMID, heruntergeladene Volumes).
+„Aufräumen“ ist ein eigener Auftrag (`AUFRAEUMEN`), nur nach Bestätigung, und löscht nur, was
+ProxDeploy selbst angelegt hat (geprüft über das Tag `proxdeploy` + Auftrags-ID in der Beschreibung).
+
+**Parallelität:** pg-boss mit konfigurierbarer Parallelität im worker (Standard 4); Template-Bau pro
+Server+Distribution singleton (zweiter Deploy wartet auf denselben Bau statt doppelt zu bauen).
+
+## 7. Datenmodell (Prisma, Entwurf)
+
+Namensabbildung (verbindlich, kommt nach `CLAUDE.md`):
+
+| Vorgabe | Modell / Begriff | Vorgabe | Modell / Begriff |
+|---|---|---|---|
+| User | `Benutzer` | Deployment / Job | `Auftrag` (Art `AUSROLLEN`, `TEMPLATE_BAUEN`, `AUFRAEUMEN`) |
+| API token (CLI) | `ApiToken` | Phase | `Phase` |
+| SSH key | `SshSchluessel` | Job log line | `Logeintrag` |
+| Server | `Server` | VMID lock | `VmidReservierung` |
+| Node | `Knoten` (nur Feldname, kein Modell) | Template (Proxmox) | `Template` |
+| Distribution | `Distribution` | Preset | `Vorlage` |
+| Profile | `Profil` | Audit log | `Protokoll` |
+| Setting | `Einstellung` | Key provider | `SchluesselQuelle` (Interface) |
+
+```prisma
+enum Rolle            { ADMIN OPERATOR }
+enum GastTyp          { VM LXC }
+enum AuftragsArt      { AUSROLLEN TEMPLATE_BAUEN AUFRAEUMEN }
+enum AuftragsStatus   { WARTEND LAEUFT ERFOLGREICH FEHLGESCHLAGEN ABGEBROCHEN AUFGERAEUMT }
+enum PhasenStatus     { OFFEN LAEUFT ERLEDIGT FEHLER UEBERSPRUNGEN }
+enum Herkunft         { KATALOG EIGEN }
+enum Quelle           { WEB CLI API }
+
+model Benutzer {
+  id String @id @default(cuid())
+  benutzername String @unique
+  anzeigename String
+  email String?
+  passwortHash String?             // null bei reinen OIDC-Benutzern
+  oidcSubjekt String? @unique
+  rolle Rolle @default(OPERATOR)
+  aktiv Boolean @default(true)
+  standards Json?                  // persönliche Standardwerte im Assistenten
+  erstelltAm DateTime @default(now())
+  apiTokens ApiToken[]  sshSchluessel SshSchluessel[]  auftraege Auftrag[]  protokoll Protokoll[]
+}
+
+model ApiToken {
+  id String @id @default(cuid())
+  benutzerId String
+  name String
+  praefix String @unique           // "pd_ab12cd34" – erkennbar, Rest nur gehasht
+  hash String                      // SHA-256 des Geheimnisses
+  zuletztGenutztAm DateTime?
+  ablaufAm DateTime?
+  widerrufenAm DateTime?
+  erstelltAm DateTime @default(now())
+}
+
+model SshSchluessel {
+  id String @id @default(cuid())
+  benutzerId String?               // null = für alle sichtbar (Team-Schlüssel)
+  name String
+  oeffentlich String
+  fingerabdruck String             // SHA256:…
+  quelle String @default("lokal")  // Kennung der SchluesselQuelle (später z. B. sshkeyvault)
+  @@unique([benutzerId, fingerabdruck])
+}
+
+model Server {
+  id String @id @default(cuid())
+  name String @unique              // "rz1" – auch CLI-Name
+  url String                       // https://host:8006
+  tokenId String                   // user@realm!tokenid
+  tokenGeheimnis String            // AES-256-GCM, v1:<iv>:<tag>:<daten>
+  tlsPruefen Boolean @default(true)
+  fingerabdruck String?            // SHA-256, gepinnt bei selbst signiertem Zertifikat
+  sshAktiv Boolean @default(false)
+  sshBenutzer String @default("root")
+  sshPort Int @default(22)
+  sshPrivat String?                // verschlüsselt
+  sshOeffentlich String?
+  sshHostSchluessel Json?          // je Node gepinnt
+  templateVmidVon Int @default(9000)
+  templateVmidBis Int @default(9999)
+  gastVmidVon Int @default(100)
+  bauNetz Json?                    // Bridge, VLAN, IP/CIDR, Gateway für Template-Vorbereitung ohne SSH
+  standards Json?                  // Standard-Node, -Storage, -Bridge
+  faehigkeiten Json?               // letzte Erkennung (Version, Storages, Rechte, Strategien)
+  erreichbar Boolean?
+  geprueftAm DateTime?
+  erstelltAm DateTime @default(now())
+}
+
+model Distribution {
+  id String @id                    // "debian-13"
+  name String
+  familie String
+  definition Json                  // validiertes YAML
+  dateiHash String
+  aktiv Boolean @default(true)
+  synchronisiertAm DateTime
+}
+
+model Profil {
+  id String @id                    // "docker"
+  name String
+  beschreibung String?
+  herkunft Herkunft
+  quelltext String                 // YAML wie eingegeben (Kommentare bleiben)
+  definition Json
+  aktiv Boolean @default(true)
+  geaendertVonId String?
+  geaendertAm DateTime @updatedAt
+}
+
+model Template {
+  id String @id @default(cuid())
+  serverId String
+  knoten String
+  vmid Int
+  distributionId String
+  storage String
+  imageQuelle String               // URL + Prüfsumme des Images
+  gebautVonAuftragId String?
+  gebautAm DateTime
+  @@unique([serverId, vmid])
+}
+
+model Vorlage {                    // Preset
+  id String @id @default(cuid())
+  name String @unique              // "docker-host-klein"
+  titel String
+  beschreibung String?
+  gastTyp GastTyp
+  parameter Json                   // Teilmenge der Auftrags-Anfrage
+  erstelltVonId String?
+  geaendertAm DateTime @updatedAt
+}
+
+model Auftrag {
+  id String @id @default(cuid())
+  kurzId String @unique            // "d-7f3k2" für CLI und URLs
+  art AuftragsArt
+  status AuftragsStatus @default(WARTEND)
+  serverId String
+  knoten String?
+  gastTyp GastTyp?
+  vmid Int?
+  name String?
+  distributionId String?
+  profile String[]
+  anfrage Json                     // validierte Anfrage (Grundlage für „Wiederholen“)
+  plan Json                        // Plan zum Zeitpunkt des Starts
+  ergebnis Json?                   // IP, SSH-Befehl, Dauer
+  angelegt Json?                   // was zum Aufräumen gehört
+  fehler Json?                     // { phase, ursache, hinweis }
+  quelle Quelle
+  erstelltVonId String
+  wiederholtVonId String?
+  vorlageId String?
+  erstelltAm DateTime @default(now())
+  gestartetAm DateTime?
+  beendetAm DateTime?
+  phasen Phase[]  log Logeintrag[]
+  @@index([serverId, erstelltAm])  @@index([status])
+}
+
+model Phase {
+  id String @id @default(cuid())
+  auftragId String
+  reihenfolge Int
+  schluessel String                // "klonen"
+  titel String                     // "Klonen"
+  status PhasenStatus @default(OFFEN)
+  detail String?
+  ursache String?
+  hinweis String?
+  gestartetAm DateTime?
+  beendetAm DateTime?
+  @@unique([auftragId, schluessel])
+}
+
+model Logeintrag {
+  id BigInt @id @default(autoincrement())   // auch SSE-Event-ID
+  auftragId String
+  zeit DateTime @default(now())
+  stufe String                     // debug|info|warn|error
+  phase String?
+  nachricht String
+  daten Json?
+  @@index([auftragId, id])
+}
+
+model VmidReservierung {
+  serverId String
+  vmid Int
+  auftragId String
+  ablaufAm DateTime
+  @@id([serverId, vmid])
+}
+
+model Protokoll {                  // Audit-Log, nur anhängen
+  id BigInt @id @default(autoincrement())
+  zeit DateTime @default(now())
+  benutzerId String?
+  quelle Quelle
+  aktion String                    // "Server angelegt", "Ausrollung gestartet"
+  ziel String?                     // "server:rz1", "auftrag:d-7f3k2"
+  details Json?
+  ip String?
+}
+
+model Einstellung { schluessel String @id  wert Json }
+```
+
+Datenbankregeln (CHECK/Trigger, wie in Laufzettel): `Protokoll` nur INSERT, VMID-Bereiche
+`von < bis`, `Auftrag.vmid` innerhalb 100–999999999, ein Template je Server/VMID.
+
+## 8. REST-API (`/api/v1`)
+
+Authentifizierung: Sitzungs-Cookie (Web) **oder** `Authorization: Bearer pd_…` (CLI). Rolle und
+Aktiv-Status werden pro Anfrage aus der DB gelesen. Jede schreibende Anfrage → `Protokoll`.
+Fehler einheitlich `{ fehler: { code, nachricht, hinweis?, felder? } }`.
+
+| Methode + Pfad | Rolle | Zweck |
+|---|---|---|
+| `POST /auth/anmelden`, `POST /auth/abmelden`, `GET /auth/oidc/start`, `GET /auth/oidc/rueckruf` | – | Anmeldung |
+| `GET /ich` | alle | aktueller Benutzer, Rolle, Version |
+| `GET /server` · `POST /server` · `GET/PATCH/DELETE /server/:name` | Admin schreibt | Server |
+| `POST /server/pruefen` | Admin | Verbindungstest ohne Speichern (liefert Fingerprint zum Bestätigen) |
+| `POST /server/:name/test` | alle | Version, Cluster/Nodes, Storages, Bridges, Rechte, Fähigkeiten |
+| `GET /server/:name/ressourcen?knoten=` | alle | Nodes, freie Ressourcen, Storages, Bridges/VLANs/VNets, nächste freie ID |
+| `POST /server/:name/ssh` | Admin | Schlüsselpaar erzeugen/erneuern, Host-Key pinnen |
+| `GET /distributionen?typ=vm\|lxc` · `PATCH /distributionen/:id` | Admin schreibt | Katalog |
+| `GET /profile` · `POST /profile` · `PUT/DELETE /profile/:id` · `POST /profile/pruefen` | Admin schreibt | Profile + Validierung |
+| `GET /server/:name/templates` | alle | Templates je Node |
+| `POST /server/:name/templates` | Admin, Operator | Template bauen → Auftrag |
+| `POST /auftraege/plan` | alle | **Dry-Run**: Plan + CLI-Befehl, nichts wird angelegt |
+| `POST /auftraege` | Operator+ | Ausrollen (VM/LXC) → `202 { id, kurzId }` |
+| `POST /auftraege/stapel` | Operator+ | Batch (YAML/JSON-Liste) |
+| `GET /auftraege?server=&typ=&distribution=&status=&seite=` | alle | Verlauf |
+| `GET /auftraege/:id` | alle | Stand inkl. Phasen + Ergebnis |
+| `GET /auftraege/:id/ereignisse` | alle | **SSE**: `phase`, `log`, `ende`; `Last-Event-ID` |
+| `GET /auftraege/:id/log?ab=` | alle | Detail-Log |
+| `POST /auftraege/:id/wiederholen` · `/abbrechen` · `/aufraeumen` | Operator+ | |
+| `GET/POST/PATCH/DELETE /vorlagen…` | Operator+ | Presets |
+| `GET/POST/DELETE /schluessel…` | eigene | SSH-Public-Keys (über `SchluesselQuelle`) |
+| `GET/POST/DELETE /tokens…` | eigene | CLI-Tokens (Geheimnis nur einmal angezeigt) |
+| `GET/POST/PATCH /benutzer…` | Admin | Benutzer, Rollen |
+| `GET /protokoll?…` | Admin | Audit-Log |
+| `GET/PUT /einstellungen` | Admin | Standardwerte, OIDC, Bereitstellungsschlüssel |
+| `GET /openapi.json`, `GET /gesundheit` | – | Spezifikation, Healthcheck |
+
+## 9. CLI (`cli/`, Go)
+
+**Begründung Go:** ein statisches Binary pro Plattform (linux/darwin/windows × amd64/arm64, ~8 MB,
+keine Laufzeit nötig – passt auf jeden Admin-Rechner und Jump-Host), sehr gute Unterstützung für
+TTY-Erkennung, 24-bit-Farben und SSE. Der Nachteil (keine geteilten TS-Typen) wird durch den aus
+`openapi.json` generierten Client (`oapi-codegen`) aufgefangen; ein CI-Schritt prüft, dass der
+generierte Code aktuell ist. Bibliotheken: `cobra` (Befehle), `BurntSushi/toml`, `golang.org/x/term`.
+
+- Konfig `~/.config/proxdeploy/config.toml` (`url`, `token`, optional `[profiles.<name>]` für mehrere
+  Instanzen), Rechte 0600; `PROXDEPLOY_URL`/`PROXDEPLOY_TOKEN` überschreiben.
+- `login <url>` fragt Benutzername/Passwort ab, legt ein Token an und speichert es (oder `--token`).
+- Ausgabe exakt nach Vorgabe; Renderer in `cli/internal/ausgabe/` mit Golden-File-Tests für Farbe,
+  `--no-color`, `--ascii`, `--quiet`, `--json`, `--dry-run`. Breite der Phasenspalte aus dem längsten
+  Phasennamen, Box-Breite aus dem Inhalt (Unicode-Breite beachtet).
+- Exit-Codes: 0 Erfolg, 1 Auftrag fehlgeschlagen, 2 Bedienfehler, 3 Verbindung/Anmeldung.
+- Die Web-GUI zeigt im letzten Assistentenschritt den passenden CLI-Befehl; erzeugt wird er vom
+  Server (`POST /auftraege/plan` liefert `cliBefehl`), damit beide Seiten dieselben Flags kennen.
+
+## 10. Web-GUI
+
+Seitenleiste mit Wortmarke, Server-Umschalter, Navigation (Übersicht, Ausrollen, Verlauf, Templates,
+Vorlagen, Katalog, Server*, Einstellungen; * nur Admin schreibend). Panel-Karten mit 1-px-Linie,
+Radius 14 px, Tokens aus der Farbtabelle der Vorgabe, dunkel zuerst, helles Theme umschaltbar
+(`data-theme`), Kontrast ≥ 4,5:1 in beiden (wird in Tests geprüft). Statusanzeige als Komponente
+`<Status>` mit Symbol + Farbe + Text.
+
+- **Assistent** `/ausrollen`: Schritte als Route-Segmente mit dem Zustand in der URL (`?s=…`), damit
+  Zurückspringen, Neuladen und Teilen funktionieren; Vorbelegen per `?vorlage=` oder `?wiederholen=`.
+  Am Handy eine Schrittleiste oben, Formular einspaltig.
+- **Live-Ansicht** `/auftraege/[kurzId]`: Terminal-Karte (JetBrains Mono) mit genau dem Aufbau der
+  CLI, darunter ausklappbares Detail-Log, am Ende die Ergebnis-Karte mit Kopieren-Knopf. Fallback auf
+  Polling, falls SSE durch den Proxy geblockt wird.
+
+## 11. Sicherheit
+
+- Secrets (Proxmox-Token, SSH-Private-Keys, OIDC-Client-Secret) mit AES-256-GCM, Schlüssel aus
+  `PROXDEPLOY_SCHLUESSEL` (32 Byte, Base64); Versionspräfix im Chiffrat für spätere Rotation.
+  Geheimnisse verlassen die API nie (nur „gesetzt“/Fingerprint).
+- CLI-Tokens nur gehasht gespeichert; Passwörter argon2id; Anmeldung mit Rate-Limit.
+- TLS zu Proxmox: Standard Systemvertrauen; bei selbst signiertem Zertifikat Pinning des
+  SHA-256-Fingerprints (TOFU **mit** Bestätigung im Formular). Kein globales `NODE_TLS_REJECT_UNAUTHORIZED`.
+- Hinter Reverse-Proxy: `TRUST_PROXY=true` wertet `X-Forwarded-For/Proto` aus; Cookies `Secure`
+  abhängig vom tatsächlichen Schema (Lehre aus ProxLedger 0.11.1); SSE mit `X-Accel-Buffering: no`.
+- Profil-Variablen werden für Shell gequotet; `run`-Schritte nur in Profilen, die ein Admin anlegt.
+- Bereitstellungsschlüssel (für SSH in Gäste) wird nach der Provisionierung aus dem Gast entfernt.
+
+## 12. Betrieb
+
+- `docker-compose.yml`: `app`, `worker`, `postgres`, `migrate` (einmalig `prisma migrate deploy`).
+  Ein gemeinsames Image, Next `output: "standalone"`, Non-root.
+- `deploy/install-lxc.sh`: auf dem Proxmox-Host ausführen → legt Debian-13-LXC an (per `pct`),
+  installiert Node, PostgreSQL, systemd-Units für app und worker, erzeugt `.env` mit Zufallsschlüssel.
+- `.env.example` mit allen Variablen (`DATABASE_URL`, `PROXDEPLOY_SCHLUESSEL`, `SITZUNG_GEHEIMNIS`,
+  `APP_URL`, `TRUST_PROXY`, `OIDC_*`, `WORKER_PARALLEL`, `LOG_LEVEL`, `ADMIN_BENUTZER/PASSWORT` für
+  den ersten Start).
+
+## 13. Dateistruktur
+
+```
+proxdeploy/
+├─ catalog/{distros,profiles}/*.yaml
+├─ cli/                         Go-Modul: cmd/proxdeploy, internal/{api,ausgabe,konfig,befehle}
+├─ src/
+│  ├─ app/(app)/…               Seiten (Übersicht, ausrollen, auftraege, server, templates, vorlagen, katalog, einstellungen)
+│  ├─ app/(auth)/anmelden
+│  ├─ app/api/v1/…              Route Handler (dünn: Recht prüfen, zod, Service)
+│  ├─ components/               UI-Bausteine (Karte, Status, Terminal, Assistent, Formulare)
+│  ├─ engine/                   siehe Abschnitt 6 – frameworkfrei, ohne Prisma-Import
+│  ├─ server/services/          Regeln + Schreiboperationen, rufen Engine und Prisma
+│  ├─ server/queries/           Lesemodelle
+│  ├─ server/auth/              Sitzung, Token, OIDC, Rechte
+│  ├─ worker/                   main.ts, Senke (Ereignisse → DB + NOTIFY), Katalog-Sync
+│  └─ lib/                      kryptografie.ts, formate.ts, logger.ts
+├─ prisma/schema.prisma, migrations/
+├─ public/brand/                Logo-Assets, Favicons, Manifest-Icons
+├─ assets/                      Banner, Avatar (Repo)
+├─ deploy/install-lxc.sh
+├─ tests/                       engine/*, api/*, e2e/*
+├─ docs/architektur.md, docs/issues/
+├─ CHANGELOG.md, DEVLOG.md, CLAUDE.md, README.md, .env.example
+└─ docker-compose.yml, Dockerfile
+```
+
+## 14. Etappen und Meilensteine
+
+| Version | Etappe | Issues | Test gegen echten Proxmox |
+|---|---|---|---|
+| v0.1.0 | 1 – Server-Verwaltung + Verbindungstest | #001–#003 | Verbindungstest, Fähigkeiten, Rechte |
+| v0.2.0 | 2 – Katalog, Template-Bau, Debian-13-VM, Live-Fortschritt | #004–#008 | Template bauen, VM ausrollen, Fehler + Aufräumen |
+| v0.3.0 | 3 – LXC, Ubuntu, Profile, Presets | #009–#012 | LXC mit/ohne SSH, docker/zabbix |
+| v0.4.0 | 4 – CLI | #013 | alle Befehle gegen die laufende Instanz |
+| v0.5.0 | 5 – Verlauf, Audit, Rollen, OIDC | #014–#016 | – |
+| v0.6.0 | 6 – Branding, README, Installer | #017–#019 | Installer in echtem LXC |
+| v1.0.0 | Feldtest 8.x + 9.x, Feinschliff | #020 | vollständig |
+
+Bis die Testumgebung steht, entwickle ich gegen einen **Proxmox-Mock** (`tests/proxmox-mock/`, ein
+kleiner HTTP-Server mit Zustand, der die benutzten Endpunkte inkl. UPID-Tasks nachbildet). Die
+Abnahme jeder Etappe gegen echten Proxmox wird nachgeholt und im DEVLOG vermerkt; ohne sie wird die
+Version nicht als abgeschlossen markiert.
+
+## 15. Offene Punkte
+
+1. **Ubuntu 26.04** zusätzlich mitliefern? (Vorschlag: ja)
+2. **Standard-BIOS** für Templates: OVMF (UEFI, braucht EFI-Disk) oder SeaBIOS? (Vorschlag: OVMF,
+   pro Distribution überschreibbar)
+3. **Template-VMID-Schema**: feste Zuordnung je Distribution (Debian 13 → 9013, Ubuntu 24.04 → 9024)
+   plus Node-Versatz im Cluster mit lokalem Storage (pve02 → 9113)? (Vorschlag: ja)
+4. **Domain** für `APP_URL` und OIDC-Redirect – kann später in `.env` gesetzt werden.
@@ -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 | – |