Proxmox AIS
Webtool für kontrollierte Proxmox-Neuinstallationen und wiederaufnehmbare Postinstallation auf Basis des Feinkonzepts. Ein FastAPI-Dienst bündelt Inventar, versionierte Profile und Bash-Module, Installationsfreigaben, ISO-Registrierung, Laufprotokolle und Auditdaten. SQLite und unveränderliche Artefakte liegen in einem persistenten Datenverzeichnis; der Schlüssel für verschlüsselte Geheimnisse liegt separat.
Unabhängigkeitshinweis: Proxmox AIS ist ein unabhängiges Projekt und steht in keiner Verbindung zur Proxmox Server Solutions GmbH oder den Entwicklern von Proxmox Virtual Environment.
Status: erste Implementierung für die Laborabnahme. Es ist noch kein echter Proxmox-ISO-Build auf Hardware oder in einer VM abgenommen. Die Kompatibilitätsmatrix trennt Softwaretests von noch offenen Installationstests. Freigaben können Datenträger überschreiben lassen; für die erste Abnahme ausschließlich dedizierte Testsysteme verwenden.
Lokal starten
Python 3.12 oder neuer wird benötigt. Die Anwendung selbst läuft unter Windows und Linux; der Host-Runner benötigt Proxmox/Linux mit systemd, Python und Bash.
PowerShell:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
$env:PUBLIC_URL = "http://127.0.0.1:8080"
$env:SECURE_COOKIES = "false"
.\.venv\Scripts\proxmox-ais.exe init --username admin
.\.venv\Scripts\proxmox-ais.exe serve
Linux/macOS:
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
export PUBLIC_URL=http://127.0.0.1:8080
export SECURE_COOKIES=false
.venv/bin/proxmox-ais init --username admin
.venv/bin/proxmox-ais serve
init fragt das Passwort zweimal verdeckt ab, speichert einen scrypt-Hash und
legt secrets/master.key mit restriktiven Rechten an. Anschließend
http://127.0.0.1:8080 öffnen. Es gibt keine mitgelieferten Zugangsdaten.
Die HTTP-Einstellungen sind ausschließlich für die lokale Entwicklung gedacht.
Optional config/app.example.toml kopieren und dessen Pfad über APP_CONFIG
setzen. Umgebungsvariablen überschreiben TOML-Werte. Weitere Einstellungen
und TLS-Konfiguration stehen in der Betriebsanleitung.
Registry-Container deployen
Auf dem Zielserver werden Docker Engine, das Compose-Plugin und ein HTTPS-Reverse-Proxy benötigt. Die Anwendung wird als fertiges Image aus der Container Registry der Gitea-Instanz heruntergeladen. Quellcode und Build-Werkzeuge werden für das Deployment nicht benötigt.
compose.yaml und die Umgebungsvorlage
in dasselbe Verzeichnis auf dem Zielserver kopieren; die Vorlage dort als .env
speichern. PUBLIC_URL auf die erreichbare HTTPS-URL der Anwendung setzen.
Die vollständige PROVISIONER_IMAGE=…@sha256:…-Zeile aus deploy.env im Artefakt
container-deploy eines erfolgreichen container-publish-Jobs in .env übernehmen. Alternativ
einen bereits veröffentlichten Versionstag aus der Projektregistry verwenden.
Compose benötigt ausdrücklich PROVISIONER_IMAGE; ein lokaler Build ist nicht
Teil dieser Deployment-Konfiguration.
Im Deployment-Verzeichnis ausführen. Für ein privates Gitea-Paket beim Login den
eigenen Gitea-Benutzernamen und einen Personal Access Token mit
read:package als Passwort verwenden. Bei einem öffentlichen Paket entfällt
der Login. Details stehen unter Registry-Anmeldung.
# Nur für ein privates Paket; GITEA_USERNAME ersetzen:
docker login gitlab.bartelluis.de --username GITEA_USERNAME
docker compose config --quiet
docker compose pull provisioner
# Nur bei der ersten Inbetriebnahme:
docker compose run --rm --no-deps --volume proxmox-ais-keys:/run/secrets:rw provisioner init --username admin
docker compose up -d --no-build --wait
docker compose ps
Der HTTPS-Reverse-Proxy leitet auf 127.0.0.1:8080 weiter. Nur init bindet das
Schlüsselvolume schreibbar ein; im Regelbetrieb läuft das Image als UID/GID 10001
mit schreibgeschütztem Dateisystem. Die Daten liegen in proxmox-ais-data, der
Master-Key getrennt in proxmox-ais-keys.
Die Deployment-Anleitung beschreibt Image-Auswahl, Erstinitialisierung, Updates, Rollback und die Prüfung des laufenden Containers.
Gitea Actions CI/CD
Das Projekt liegt auf Gitea.
Der Gitea-Actions-Workflow prüft Python und JavaScript, baut das Image
und testet HTTPS, Anmeldung und Datenerhalt beim Neustart im gehärteten Container.
Bei aktivierter Veröffentlichung (PUBLISH_IMAGES=true) veröffentlichen
Standardbranch-Pushes sha-<Commit> und edge in
gitlab.bartelluis.de/bartelluis/proxmox-ais-server; Release-Tags wie v0.1.0
zusätzlich die passende Versionsnummer. Feature-Branches und Pull Requests
werden ohne Registry-Push geprüft.
Gitea benötigt einen registrierten, erreichbaren Linux-amd64-Runner. Das
Runner-Label ist über AIS_RUNNER_LABEL wählbar und lautet standardmäßig
ubuntu-latest. Die Build-Umgebung benötigt Python 3.13, Node.js 24 und
Docker/Buildx. Für die Veröffentlichung werden die Variable REGISTRY_USERNAME
und das Secret REGISTRY_TOKEN mit write:package eingerichtet. Standardbranch
und Release-Tags in Gitea schützen, bevor PUBLISH_IMAGES aktiviert wird.
Runner-Einrichtung, Schutzregeln und Artefakte stehen in der
Gitea-Anleitung.
Die Pipeline liefert das getestete Image und dessen Digest in deploy.env.
Die Installation auf dem Zielserver folgt der Deployment-Anleitung.
Erster Installationslauf
- Als Administrator weitere Benutzer anlegen. Rollen sind
reader,operator,author,adminunddeveloper. - Standortbezogenen Installer-Gruppentoken erzeugen und den einmal angezeigten Token sicher speichern. Er ist Bestandteil des Installationsmediums.
- ISO-Build, SHA-256, Assistant-Version und Zertifikatsfingerprint erfassen. Das Medium erst nach bestandenem Labortest freigeben.
- Root-Zugang als Geheimnis speichern, Installationsprofil und
Postinstallationsprofil anlegen. Module enthalten
check,applyundverify; Veröffentlichungen benötigen einen Testnachweis. Standardmäßig muss eine andere Person als der Autor veröffentlichen. - Host mit UUID, Seriennummer und MAC-Adressen, FQDN, Standort, Profilversionen und Medium erfassen. Vorschau und geprüfte Zielgeräte kontrollieren.
- Eine zeitlich begrenzte Freigabe mit FQDN-Bestätigung und ausdrücklicher Datenträgerbestätigung erteilen. Erst anschließend vom vorbereiteten Medium booten.
- Laufstatus und redigierte Logs verfolgen. Der Lauf gilt erst nach erfolgreichen Pflichtprüfungen als abgeschlossen.
Die ISO-Anleitung beschreibt den offiziellen Assistant;
der API-Ablauf zeigt konkrete Requests. Die vollständigen
Schemas stehen nach Anmeldung am laufenden Dienst unter /openapi.json; ein
generierter Stand liegt in docs/openapi.json.
Prüfen und sichern
.venv/bin/python -m pytest
.venv/bin/proxmox-ais backup ./backups/first-snapshot
Unter PowerShell entsprechend .\.venv\Scripts\python.exe -m pytest und
.\.venv\Scripts\proxmox-ais.exe backup .\backups\first-snapshot verwenden.
Der Testbericht beschreibt die ausgeführten Prüfungen.
Die Sicherung verwendet die SQLite-Backup-API und enthält Artefakte, verschlüsselte Geheimnisse, ausgewählte Betriebseinstellungen und SHA-256-Prüfsummen. Den Entschlüsselungsschlüssel separat sichern. Restore funktioniert ausschließlich offline in ein leeres Datenverzeichnis und sperrt alte Maschinenberechtigungen. Details stehen in Betrieb und Wiederherstellung.
Umfang und Grenzen
ISO-Erstellung erfolgt auf einer getrennten Build-Maschine. BMC-Steuerung, PXE, Clusterbeitritt, Ceph, dauerhafte Konfigurationsverwaltung und zusätzliche destruktive Storage-Module gehören nicht zu dieser Version. Die Kapazitäten von 100 Hosts und zehn parallelen Installationen sind Planungsziele, keine bereits gemessenen Leistungswerte. Gemeinsame ISO-Tokens plus gemeldete Hardwaremerkmale setzen ein kontrolliertes Provisionierungsnetz voraus.