Ein Freund bat mich kürzlich um meine Meinung zum Thema Software-Verteilung und Dokumentation des Installations- bzw. Bereitstellungsprozesses. Die Gedanken, die ich mir dazu gemacht habe, möchte ich an dieser Stelle mit euch teilen. Dabei schreibe ich aus dem Blickwinkel eines Systemintegrators, der von Dritten erstellte Software integrieren und betreiben muss.
Den Anwendungsentwicklern, Software-Architekten und Produkt-Managern unter euch soll dieser Text als Information dienen, was ich und ggf. weitere Personen meiner Zunft von einer Dokumentation erwarten bzw. wie wir uns Software-Verteilungsprozesse vorstellen.
Als Leser seid ihr alle eingeladen, eure Gedanken ebenfalls zu teilen und eine Diskussion zu diesem Thema zu führen.
Das Szenario
Ich habe bei meinen Gedanken ein Szenario im Kopf, in dem ein Anwendungsentwickler eine Anwendung in einer Sprache seiner Wahl schreibt. Diese Anwendung soll später über ein Web-Frontend erreichbar und nutzbar sein. Die Anwendung benötigt eine Datenbank, um Informationen darin abzulegen. Binärdateien werden ggf. außerhalb der Datenbank in einem Dateisystem gespeichert.
Die Anwendungsentwickler freuen sich, wenn ihre Software einen hohen Verbreitungsgrad erreicht. Dazu muss die dazugehörige Dokumentation folgende Informationen bieten.
Werkzeuge zum Erstellen und Ausführen der Anwendung
- Welcher Compiler ab welcher Version wird benötigt?
- Welche Bibliotheken werden ab welcher Version benötigt?
- Sind abweichende Versionen möglich oder funktioniert nur genau eine?
- Welche Laufzeitumgebung wird benötigt?
- Was ist in welcher Reihenfolge zu tun, um vom Quelltext zu einem ausführbaren Programm zu kommen?
Voraussetzungen zur Integration der Anwendung
- Wird eine Datenbank benötigt?
- Welche Datenbank-Management-Systeme werden unterstützt?
- Ab welcher Version?
- Über welche Rechte muss ein DB-User mindestens verfügen, damit der Anwendungs-Installer die notwendigen Tabellen, Views, etc. erstellen kann?
- Welche Webserver werden unterstützt?
- Welche Protokolle, Parameter bzw. Optionen sind für die Kommunikation mit der Anwendung notwendig?
Ich bin immer enttäuscht, wenn hier auf ein einziges System eingeschränkt wird. Dies limitiert unnötig den Nutzerkreis.
- Wird ein Snakeoil-Zertifikat mitgeliefert oder hat der Systemintegrator dieses beizustellen? Eigene Zertifikate auf Wunsch verwenden zu können ist obligatorisch.
Die bis jetzt genannten Informationen müssen so umfassend sein, dass Paketbetreuer bzw. Software-Paketierer daraus Debian-, Flatpak-, RPM-, Snap-Pakete, Container-Images und Windows-Installer bauen können.
Nehmen die Anwendungsentwickler in Personalunion die Rolle von Software-Paketierern wahr, scheint es dennoch unrealistisch, dass sie allein alle Formate unterstützen können. Sie sollten sich für einige wenige Formate entscheiden, die auf möglichst vielen Plattformen lauffähig sind. In dem von mir gedachten Szenario sind dies OCI-kompatible Container-Images.
Bei einer GUI-Anwendung würde ich mich vermutlich für Flatpak entscheiden. Die Paketierung als DEB oder RPM würde ich auf jeden Fall den Paketbetreuern der jeweiligen Distributionen überlassen.
Systemintegration
Für den Systemintegrator, welcher den Webserver, die Anwendung und die Datenbank zusammenbringt (integriert), muss klar beschrieben werden:
- Gibt es ein fertiges Container-Image? Wo bekommt man es her?
- Optional: Wie erstellt man das Container-Image selbst?
- Welche (Umgebungs-)Variablen gehören zum Image? Welche Werte können diese annehmen?
- Ein Kommunikationsdiagramm, damit der Sysadmin weiß, was wann mit wem spricht und welche Firewall-Regeln evtl. benötigt werden.
Referenzimplementierungen sind ebenfalls schön. Diese sollten für Docker, Docker-Compose, Kube-YAML (K8s) und Podman bereitstehen. Die Doku zum Container-Image muss jedoch so ausgestaltet sein, dass auch ohne Referenzimplementierung die Instanziierung mit den verschiedenen Engines und Orchestrierern gelingen kann.
Was Sysadmins (wie ich) nicht mögen
Ich mag es nicht, wenn in den Abhängigkeiten ein Webserver (Apache, NGINX, lighttpd) oder ein Datenbank-Management-System unnötig hart verdrahtet ist. Gleiches gilt für die Festlegung der zu verwendenden Container-Registries. Ich will dem Installer sagen können, wo er die Images findet und nicht auf den Dockerhub festgelegt werden.
Und ja, mir ist bewusst, dass eine gute Dokumentation genauso viel Aufwand und Pflege bedeutet wie der Quelltext einer Anwendung selbst. Aber ist es eine Alternative, wenn Systemintegratoren die Anwendung nach dem ersten Installationsversuch hassen?
Eure Meinung ist willkommen
Wie steht ihr als Entwickler zum Thema Dokumentation? Was erwartet ihr als Sysadmin und User von ihr?
Stimmt ihr mit mir überein oder habt ihr ganz andere Ansichten dazu? Nutzt gern die Kommentarfunktion und lasst es mich wissen.
Im Rahmen des neuesten Monatsberichts hat Danielle Foré einen Einblick zum aktuellen Status gegeben. So erhielt die derzeit aktuelle Version Elementary OS 6.1 einige Aktualisierungen, Fehlerkorrekturen und Leistungsverbesserungen. Zu den Verbesserungen zählt eine neue Version von Dateien / Files. Hier gab es Fehlerkorrekturen in Verbindung mit Tastaturkurzbefehlen. Die Kamera App unterstützt nun mehr MJPEG Kameras....