proxdeploy/README.md

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 – mit Profilen wie base, docker oder zabbix-agent. Distributionen und Profile sind YAML-Dateien im Katalog, kein Code.

ProxDeploy ist ein unabhängiges Werkzeug und stammt nicht von der Proxmox Server Solutions GmbH. „Proxmox“ ist eine Marke der Proxmox Server Solutions GmbH.

Was es kann

• Assistent in neun Schritten – Server, Typ, Distribution, Name, Ressourcen, Netzwerk (DHCP/statisch, VLAN), Zugang (SSH-Schlüssel), Profile mit Variablen – und am Ende ein Dry-Run mit allen geplanten Proxmox-Aufrufen und dem passenden CLI-Befehl.
• Live-Fortschritt je Phase (Server-Sent Events), in Web und CLI mit denselben Texten; bei Fehlern Ursache und Lösungshinweis, danach auf Wunsch Aufräumen des halb angelegten Gasts.
• Templates aus offiziellen Cloud-Images (Prüfsumme geprüft, UEFI, Guest-Agent eingebaut), auf Wunsch mit eingebackenen Profilen – ein Docker-Host ist dann in Sekunden statt Minuten fertig.
• Ohne SSH zum Node per API und Guest-Agent; mit SSH zusätzlich LXC-Provisionierung und cloud-init-Snippets. Was ein Server kann, zeigt der Verbindungstest.
• Verlauf mit Filtern und Wiederholen, Vorlagen („Docker-Host klein“), hinterlegte SSH-Schlüssel, Rollen Admin/Operator, Audit-Log, Anmeldung lokal oder per OIDC.
• CLI als einzelnes Binary für Linux, macOS und Windows – mit Batch-Dateien für viele Gäste.

Übersicht	Assistent mit Dry-Run	Am Handy

Weitere Ansichten: Verlauf · Server mit Verbindungstest · Katalog. Erzeugt mit scripts/screenshots.ts aus dem gebauten Stand.

Installation

ProxDeploy braucht PostgreSQL und läuft als zwei Prozesse (app und worker). Es gehört hinter einen Reverse-Proxy mit TLS; dann TRUST_PROXY=true und APP_URL auf die öffentliche Adresse setzen.

Docker Compose

git clone https://git.wilde-server.de/florian.wilde/proxdeploy.git && cd proxdeploy
cp .env.example .env
#   POSTGRES_PASSWORT=$(openssl rand -hex 24)
#   PROXDEPLOY_SCHLUESSEL=$(openssl rand -base64 32)   ← sichern! ohne ihn sind Tokens und Schlüssel verloren
#   SITZUNG_GEHEIMNIS=$(openssl rand -base64 48)
#   APP_URL=https://proxdeploy.example
#   ADMIN_PASSWORT=…                                    ← erster Admin, nur beim allerersten Start
docker compose up -d --build

Compose startet postgres, spielt mit migrate die Datenbank ein und startet dann app (Port 3000 auf 127.0.0.1) und worker. Aktualisieren: git pull && docker compose up -d --build.

In einem Debian-LXC auf dem Proxmox-Host

scripts/paket-bauen.sh 0.6.0 --tar                    # im Repository: proxdeploy-0.6.0.tar.gz
scp proxdeploy-0.6.0.tar.gz deploy/install-lxc.sh deploy/im-container.sh root@pve01:/root/
ssh root@pve01 ./install-lxc.sh --paket proxdeploy-0.6.0.tar.gz --url https://proxdeploy.example

Der Installer legt einen unprivilegierten Debian-13-Container an (DHCP auf vmbr0; --ip, --gw, --vlan, --storage, --ctid u. a. siehe --help), installiert Node.js 24 (Prüfsumme geprüft) und PostgreSQL, richtet systemd-Dienste ein und zeigt am Ende Adresse und das Passwort des ersten Admins. Aktualisieren mit ./install-lxc.sh --aktualisieren <ctid> --paket proxdeploy-0.6.1.tar.gz – die letzten drei Fassungen bleiben unter /opt/proxdeploy/versionen/.

Erste Schritte

1. Token in Proxmox: eigenen Benutzer und die Rolle ProxDeploy anlegen, Token ohne Privilege Separation – die Befehle für 8.x und 9.x stehen in docs/proxmox-rechte.md.
2. Server anlegen: URL, Token, Zertifikat bestätigen (Fingerprint-Pinning für selbst signierte Zertifikate), „Verbindung testen“. Optional SSH-Zugang zum Node hinterlegen.
3. SSH-Schlüssel unter Einstellungen hinterlegen – sie kommen automatisch in jeden Gast.
4. Ausrollen: fehlt das Template, baut ProxDeploy es vorher (oder unter „Templates“).

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.

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.

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.<name>] 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 <url> --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 <id>); abbrechen mit proxdeploy cancel <id>.

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:

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 <APP_URL>/api/v1/auth/oidc/rueckruf, Scopes openid profile email, den Gruppen-Claim ins ID-Token geben. Dann in der .env:

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.

Katalog erweitern

• Neue Distribution: eine YAML-Datei unter catalog/distros/ – Image-URL, Prüfsummen-Quelle, Standardbenutzer, LXC-Template-Muster. Für eine neue Familie (z. B. rhel mit dnf) kommt ein Adapter unter src/engine/adapter/ dazu. → docs/katalog.md
• Eigenes Profil: in der Web-GUI unter Katalog → „Profil anlegen“ (YAML mit Live-Prüfung und Skriptvorschau) oder als Datei unter catalog/profiles/. → docs/katalog.md

Stand

Version und Änderungen stehen im CHANGELOG, der Plan in docs/architektur.md, die Aufgaben in docs/issues/.

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, Template-Bau ohne SSH	✓ fertig, auf PVE 9.2 geprüft
4 · v0.4.0	CLI proxdeploy (Go), API-Tokens	✓ fertig, auf PVE 9.2 geprüft
5 · v0.5.0	Verlauf, Aufräumen, Audit-Log, Benutzer, OIDC	✓ fertig (Aufräumen auf PVE 9.2 geprüft, OIDC gegen Mock-IdP)
6 · v0.6.0	Branding, README mit Screenshots, Docker Compose, LXC-Installer	✓ fertig, Installer auf PVE 9.2 geprüft

Entwicklung

Voraussetzungen: Node 24 (z. B. über nvm), pnpm 12 (corepack), Docker für PostgreSQL.

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:

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.

Lizenz

Noch nicht festgelegt.