florian.wildeandClaude Opus 5.5
7beeafd2f6
q35 hängt IDE an den SATA-Controller; der Cloud-Kernel von Debian 12 kennt ihn nicht, cloud-init fand keine Datenquelle. Gefunden bei der Abnahme von #021 auf pve-demo: Template-Bau über die Bau-Adresse und eine Debian-12-VM daraus, beides ohne SSH zum Node. Closes #021 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
234 lines
12 KiB
Markdown
234 lines
12 KiB
Markdown
<p align="center"><img src="public/brand/banner.svg" alt="ProxDeploy – VMs und LXC-Container auf Proxmox VE ausrollen, per Web oder CLI." width="100%"></p>
|
||
|
||
**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.
|
||
|
||
<p align="center"><img src="docs/bilder/live-ansicht.png" alt="Live-Ansicht eines Deployments: Phasen mit Status, Abschlussbox mit IP und SSH-Befehl" width="100%"></p>
|
||
|
||
## 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](docs/bilder/verlauf.png) · [Server mit Verbindungstest](docs/bilder/server.png) · [Katalog](docs/bilder/katalog.png).
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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](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](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.<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:
|
||
|
||
```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 `<APP_URL>/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.
|
||
|
||
## 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](docs/katalog.md#neue-distribution-hinzufügen)
|
||
- **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](docs/katalog.md#eigenes-profil-anlegen)
|
||
|
||
## Stand
|
||
|
||
Version und Änderungen 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, 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.
|
||
|
||
```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).
|
||
|
||
## Lizenz
|
||
|
||
Noch nicht festgelegt.
|