Add project vision and architecture

vision-and-architecture.md

@@ -0,0 +1,321 @@
+# Stallinux Provisioning Platform
+
+## Vision
+
+Die Stallinux Provisioning Platform soll die automatisierte Bereitstellung und Konfiguration von Linux-Systemen vereinfachen.
+
+Das Ziel ist eine distributionsübergreifende Plattform, die Linux Mint, Fedora und zukünftig weitere Distributionen über denselben Provisionierungsprozess installieren und konfigurieren kann.
+
+Die Plattform soll sowohl im lokalen Netzwerk als auch über das Internet funktionieren.
+
+Ein neues System soll idealerweise nur noch:
+
+1. von einem generischen Bootmedium starten
+2. einen Aktivierungscode erhalten
+3. ein Profil auswählen
+4. automatisch installiert und konfiguriert werden
+
+ohne dass individuelle Installationsmedien erstellt werden müssen.
+
+---
+
+# Grundprinzipien
+
+## Das ISO bleibt generisch
+
+Das Bootmedium enthält möglichst wenig Logik.
+
+Es kennt:
+
+* die Adresse des Aktivierungsdienstes
+* den Aktivierungsprozess
+* die Profilauswahl
+
+Es kennt nicht:
+
+* konkrete Installationsprofile
+* konkrete Kunden
+* konkrete Systeme
+
+Neue Profile sollen ohne Neubau des ISO bereitgestellt werden können.
+
+---
+
+## Profile sind serverseitig
+
+Die eigentliche Installationslogik befindet sich auf dem Server.
+
+Das ISO fragt lediglich:
+
+* Welche Profile stehen zur Verfügung?
+* Welches Profil wurde ausgewählt?
+* Welche Bootstrap-Daten gelten für dieses Profil?
+
+Dadurch können neue Profile jederzeit hinzugefügt werden.
+
+---
+
+## Git ist die Quelle der Wahrheit
+
+Alle relevanten Daten werden versioniert.
+
+Repositories:
+
+* provisioning-server
+* provisioning-client
+* platform-docs
+* profiles
+
+geplant:
+
+* ansible-roles
+* installer-definitions
+
+Git dient als zentrale und nachvollziehbare Quelle für Code, Dokumentation und Konfiguration.
+
+---
+
+## HTTPS First
+
+Alle Kommunikation erfolgt über HTTPS.
+
+Der öffentliche Zugriff erfolgt über Pangolin.
+
+Beispiel:
+
+Provisioning Client
+↓
+HTTPS
+↓
+anode.stallinux.de
+↓
+Provisioning API
+
+---
+
+## Distributionen sind austauschbar
+
+Die Plattform soll nicht auf eine einzelne Linux-Distribution beschränkt sein.
+
+Beispiele:
+
+* Linux Mint
+* Fedora
+* Debian
+* Ubuntu
+
+Der Provisionierungsablauf bleibt gleich.
+
+Lediglich die Installationsdefinitionen unterscheiden sich.
+
+---
+
+## Ansible Pull statt Push
+
+Langfristig sollen installierte Systeme ihre Konfiguration selbst abrufen.
+
+Vorteile:
+
+* keine permanente Erreichbarkeit erforderlich
+* NAT-freundlich
+* Internet-fähig
+* einfacher Betrieb
+
+Zukünftiger Ablauf:
+
+Installation
+↓
+Ansible Pull
+↓
+Git Repository
+↓
+Konfiguration anwenden
+
+---
+
+# Aktuelle Architektur
+
+Provisioning Client
+↓
+Activation API
+↓
+Profile API
+↓
+Bootstrap API
+↓
+Installer
+↓
+Ansible Pull
+
+---
+
+# Aktuelle Komponenten
+
+## anode.stallinux.de
+
+Funktion:
+
+* Aktivierungsserver
+* Profilverwaltung
+* Bootstrap API
+
+Technologie:
+
+* FastAPI
+* Python
+* systemd
+* Pangolin
+
+Aktuelle Endpunkte:
+
+GET /health
+
+POST /api/v1/activate
+
+GET /api/v1/profiles/{id}
+
+GET /api/v1/profiles/{id}/bootstrap
+
+---
+
+## git.stallinux.de
+
+Funktion:
+
+* Quellcodeverwaltung
+* Versionsverwaltung
+* Dokumentation
+* Profile
+
+Technologie:
+
+* Gitea
+
+---
+
+# Profile
+
+Aktuell:
+
+* mint-desktop
+* fedora-workstation
+
+Zukünftig:
+
+* mint-office
+* mint-developer
+* mint-kiosk
+* fedora-cad
+* fedora-kiosk
+* weitere distributionsspezifische Profile
+
+---
+
+# Bootstrap-Konzept
+
+Nach erfolgreicher Aktivierung liefert der Server:
+
+* Profilinformationen
+* Installationsmethode
+* Installer-URL
+* Ansible-Repository
+* SSH-Schlüsselinformationen
+
+Der Client speichert diese Informationen lokal.
+
+Beispiel:
+
+/tmp/provisioning-selection.json
+
+Diese Datei bildet die Übergabe zwischen Aktivierungsphase und Installationsphase.
+
+---
+
+# Langfristige Zielarchitektur
+
+Bootmedium
+↓
+Aktivierungscode
+↓
+Aktivierungsserver
+↓
+Profilauswahl
+↓
+Bootstrap-Konfiguration
+↓
+Automatische Installation
+↓
+Ansible Pull
+↓
+Betriebsbereites System
+
+---
+
+# Geplante Erweiterungen
+
+## Aktivierungscodes
+
+Aktuell:
+
+* ein globaler Aktivierungscode
+
+Später:
+
+* kundenbezogene Aktivierungscodes
+* Ablaufdaten
+* Installationskontingente
+* Aktivierungsstatistiken
+
+---
+
+## Organisationen
+
+Zukünftig sollen Kunden eigene Profile und Installationskontingente verwalten können.
+
+---
+
+## Installer
+
+Geplant:
+
+Linux Mint:
+
+* Autoinstall
+
+Fedora:
+
+* Kickstart
+
+Weitere Distributionen:
+
+* distributionsspezifische Installationsverfahren
+
+---
+
+## Infrastruktur
+
+Mögliche spätere Komponenten:
+
+* Git-basierte Profile
+* Git-basierte Installer
+* Signierte Bootstrap-Daten
+* Telemetrie
+* Inventarisierung
+* automatische Registrierung neuer Systeme
+
+---
+
+# Entwicklungsgrundsatz
+
+Der Server soll möglichst intelligent sein.
+
+Das Bootmedium soll möglichst dumm bleiben.
+
+Neue Funktionen sollen bevorzugt durch:
+
+* neue Profile
+* neue Bootstrap-Daten
+* neue Repositories
+
+realisiert werden und nicht durch Änderungen am Bootmedium.
+