# ProxDeploy **VMs und LXC-Container auf Proxmox VE ausrollen, per Web oder CLI.** ProxDeploy ist eine selbst gehostete Webanwendung mit einer CLI (`proxdeploy`). Damit wählt man einen von mehreren Proxmox-VE-Servern (8.x/9.x, Einzelhost oder Cluster) und rollt darauf vollständig unattended eine VM oder einen LXC-Container mit Debian oder Ubuntu aus, inklusive Profilen wie `base`, `docker` oder `zabbix-agent`. Weitere Distributionen und Profile sind YAML-Dateien im Katalog, kein Code. > ProxDeploy ist ein unabhängiges Werkzeug und stammt nicht von Proxmox Server Solutions GmbH. > „Proxmox“ ist eine Marke der Proxmox Server Solutions GmbH. ## Stand In Entwicklung. Version und Fortschritt stehen im [CHANGELOG](CHANGELOG.md), der Plan in [docs/architektur.md](docs/architektur.md), die Aufgaben in [docs/issues/](docs/issues/README.md). | Etappe | Inhalt | Stand | |---|---|---| | 1 · v0.1.0 | Server-Verwaltung, Fingerprint-Pinning, Verbindungstest mit Fähigkeitserkennung | ✓ fertig, auf PVE 9.2 geprüft | | 2 · v0.2.0 | Katalog, Template-Bau, Debian-13-VM, Live-Fortschritt, Assistent | ✓ fertig, auf PVE 9.2 geprüft | | 3 · v0.3.0 | LXC, Ubuntu, Profile, Vorlagen, Profile im Template, SSH-Schlüssel | ✓ fertig, auf PVE 9.2 geprüft (Bau-Adresse #021: Abnahme offen) | | 4 · v0.4.0 | CLI `proxdeploy` (Go), API-Tokens | ✓ fertig, auf PVE 9.2 geprüft | | 5 · v0.5.0 | Verlauf, Audit-Log, Rollen, OIDC | ◐ als Nächstes | | 6 · v0.6.0 | Branding, README mit Screenshots, Installer | ○ geplant | ## Was ProxDeploy auf einem Server kann Der Verbindungstest prüft jeden Server und zeigt, welcher Vorgang per API, per SSH oder gar nicht geht. Maßgeblich ist die Proxmox-API (geprüft gegen PVE 8.x und 9.2): - **Template bauen:** per API ab PVE 8.4 (`download-url` + `import-from`), davor per SSH - **VM provisionieren:** über den Guest-Agent, ohne SSH - **LXC provisionieren:** braucht SSH (Proxmox hat keine Exec-API für Container) - **cloud-init-Snippets:** nur per SSH (keine API) Das API-Token braucht eine eigene Rolle; die Befehle stehen in [docs/proxmox-rechte.md](docs/proxmox-rechte.md). ## CLI `proxdeploy` ist ein einzelnes Binary (Linux, macOS, Windows; amd64 und arm64) und spricht nur die REST-API – dieselbe wie die Web-GUI, mit denselben Phasentexten. ```bash proxdeploy login https://proxdeploy.example # fragt Benutzer und Passwort, speichert ein Token proxdeploy servers proxdeploy distros --type lxc proxdeploy profiles proxdeploy vm web01 --server rz1 --distro debian-13 --profile base,docker --ip 10.0.20.15/24 --gw 10.0.20.1 --vlan 20 proxdeploy lxc dns01 --server rz1 --distro ubuntu-24.04 --dry-run proxdeploy template build --server rz1 --distro debian-13 --profile base,docker proxdeploy batch gaeste.yaml proxdeploy status a-7f3k proxdeploy logs a-7f3k --follow proxdeploy history --type lxc --status fehlgeschlagen proxdeploy cleanup a-7f3k # halb angelegten Gast nach Fehlschlag löschen (mit Rückfrage) ``` ``` ⬡ ProxDeploy v0.4 · Server rz1 · Node pve01 · Debian 13 (Template 9013) ✓ Prüfungen VMID 120 frei · local-zfs · vmbr0 VLAN 20 ✓ Klonen full clone 9013 → 120 · Disk auf 40G ✓ cloud-init user florian · SSH-Key · Profile base, docker ✓ Start VM 120 läuft ✓ Guest-Agent antwortet nach 18s ◐ Provisionierung cloud-init läuft … 1m 12s ``` - Was nicht angegeben ist, füllt der Server: Storage, Bridge und Node aus den Server-Einstellungen bzw. dem Verbindungstest, Benutzer = eigener Benutzername, SSH-Schlüssel = die in den Einstellungen hinterlegten. `--preset` belegt aus einer Vorlage vor; Flags gehen vor. - Konfiguration in `~/.config/proxdeploy/config.toml` (Rechte 0600): `url`, `token`, optional `server` als Standard für `--server` und `[instances.]` für weitere Instanzen (`--instance`). `PROXDEPLOY_URL`, `PROXDEPLOY_TOKEN`, `PROXDEPLOY_INSTANCE` gehen vor. - Tokens für Skripte und CI: Web-GUI → Einstellungen → API-Tokens, dann `proxdeploy login --token pd_…`. - Ausgabe: Farben (24-bit, sonst 256) nur im Terminal und ohne `NO_COLOR`/`--no-color`; `--ascii` ersetzt Symbole durch `[OK]`, `[..]`, `[!!]`; `--quiet` zeigt nur die Abschlussbox; `--json` ist maschinenlesbar. Ohne Terminal (Pipe, CI) erscheint jede Phase als eine Zeile, sobald sie fertig ist. - Exit-Codes: `0` Erfolg, `1` Auftrag fehlgeschlagen, `2` Bedienfehler, `3` Verbindung/Anmeldung. - `Strg+C` hängt nur ab – der Auftrag läuft weiter (`proxdeploy status `); abbrechen mit `proxdeploy cancel `. `batch` rollt mehrere Gäste aus; die Schlüssel heißen wie die Flags. Die Datei wird vollständig geprüft, bevor der erste Auftrag startet: ```yaml defaults: server: rz1 distro: debian-13 profile: [base] guests: - name: web01 type: vm profile: [base, docker] ip: 10.0.20.15/24 gw: 10.0.20.1 memory: 4096 - name: mon01 type: lxc profile: [base, zabbix-agent] vars: { zabbix-agent: { server: zbx.example } } ``` Bauen: `cli/bauen.sh 0.4.0` legt die sechs Binaries und `SHA256SUMS` unter `cli/bin/` ab (Go 1.27). ## Anmeldung per OIDC (z. B. authentik) Optional zusätzlich zu lokalen Konten. Beim Identity Provider einen vertraulichen Client anlegen, Redirect-URI `/api/v1/auth/oidc/rueckruf`, Scopes `openid profile email`, den Gruppen-Claim ins ID-Token geben. Dann in der `.env`: ```bash OIDC_AKTIV=true OIDC_ISSUER=https://auth.example/application/o/proxdeploy/ OIDC_CLIENT_ID=… OIDC_CLIENT_SECRET=… OIDC_ANZEIGENAME=authentik OIDC_GRUPPEN_CLAIM=groups OIDC_GRUPPE_ADMIN=proxdeploy-admins OIDC_GRUPPE_OPERATOR=proxdeploy-operators ``` - Ablauf: Authorization Code mit PKCE, State und Nonce; das ID-Token wird gegen die Schlüssel des IdP geprüft. - Die Rolle kommt bei **jeder** Anmeldung aus den Gruppen; wer in keiner der beiden Gruppen ist, kommt nicht hinein. - Neue SSO-Benutzer werden beim ersten Anmelden angelegt. Ein vorhandenes lokales Konto wird **nie** über den Namen übernommen; verknüpfen geht angemeldet unter Einstellungen → „Mit … verknüpfen“. - Gesperrte Konten bleiben gesperrt, auch per SSO. Getestet gegen einen Mock-IdP (`tests/oidc.test.ts`); ein echter IdP folgt beim Feldtest. ## Entwicklung Voraussetzungen: Node 24 (z. B. über nvm), pnpm 12 (corepack), Docker für PostgreSQL. ```bash pnpm install cp .env.example .env # Schlüssel erzeugen: openssl rand -base64 32 / 48, ADMIN_PASSWORT setzen pnpm db:up # PostgreSQL 17 auf 127.0.0.1:5437 (inkl. Testdatenbank) pnpm db:migrate pnpm build && PORT=3310 APP_URL=http://127.0.0.1:3310 pnpm start ``` Prüfen vor jedem Commit: ```bash pnpm lint && pnpm typecheck && pnpm format:pruefen && pnpm test pnpm test:e2e # Browser-Abläufe gegen den gebauten Stand (Desktop und 390 px) pnpm cli:pruefen # openapi.json und Go-Typen aktuell, go vet, go test (Golden-Files) ``` Ändert sich ein Schema der API, erst `pnpm openapi`, dann in `cli/` `go generate ./...` – der Go-Client nutzt die aus `cli/api/openapi.json` erzeugten Typen. Konventionen (deutsche Bezeichner, Schichtung, Versionen) stehen in [CLAUDE.md](CLAUDE.md). ## Betrieb Docker Compose (app, worker, postgres) und ein Installer für einen Debian-LXC auf Proxmox folgen mit Etappe 6. ProxDeploy ist für den Betrieb hinter einem Reverse-Proxy mit TLS gedacht (`TRUST_PROXY=true`, `APP_URL` auf die öffentliche Adresse). ## Lizenz Noch nicht festgelegt.