Just-Podman-Toolchain

Viele meiner Projekte nutzen eine maßgeschneiderte Toolchain für das Bauen und Ausführen von Anwendungen. Diese Anleitung soll helfen die Grundlagen der Toolchain zu verstehen und diese in verschiedensten Projekten zu verwenden. Sie basiert auf zwei Open-Source-Programmen:

1. just ist ein Programm zum Ausführen von projektspezifischen Befehlen. Diese Befehle werden in sogenannte Tasks zusammengefasst (z.B. build, run, ...). Alle Tasks werden innerhalb der Datei justfile definiert. Sie können sich ein Task in etwa wie eine Funktion in einer Programmiersprache, welche auch mehrere Befehle kapselt und bei Aufruf ausführt. Der Unterschied ist, dass just Tasks innerhalb des Terminals ausgeführt werden (mit just <task_name>).
2. Podman erlaubt es Programme innerhalb eines Containers auszuführen. Diese Container werden basierend auf einem Image erstellt, welches aus einer Registry aus dem Internet geladen werden (z.B. von docker.io/alpine/curl:8.14.1). Je nach ausgewähltem Image stehen unterschiedliche Programme im Container zur Verfügung. Der Vorteil zu einer lokalen Installation ist es, dass alle Nutzer eine identische Version der Programme (bzw. der Entwicklungsumgebung) erhalten. Dadurch wird die Entwicklung auch unabhängig davon, welches Betriebssystem Sie verwenden. Ein Nachteil an diesem Verfahren ist, dass die benötigten Podman-Befehle sehr lang sein können. Damit Sie nicht jedes Mal einen langen Befehl kopieren müssen, wurden alle notwendigen Befehle mit just gekapselt.

Ziele der Toolchain

Die Toolchain wird sowohl in meinen eigenen Projekten, als auch in vielen meiner Informatik-Module an der Technischen Hochschule Mittelhessen verwendet. Die Toolchain besitzt folgende Ziele:

1. Plattformunabhängigkeit: Viele meiner Projekte werden von Studierenden eingesetzt. Diese nutzen verschiedenste Betriebssysteme und IDEs. Die Toolchain muss nach der Installation ohne Anpassungen auf verschiedensten Systemen funktionieren.
2. Reproduzierbarkeit: Die Toolchain spezifiziert und erzwingt die Versionen der genutzten Software (z.B. Compiler). Dadurch wird sichergestellt, dass keine Probleme durch inkompatible Software-Versionen entstehen.
3. Abstraktion der Toolchain: Die Toolchain wird für verschiedenste Projekte verwendet (z.B. Programmierung in TypeScript, Serverentwicklung mit Java, Abschlussarbeiten in LaTeX). Damit nicht für jedes Projekt eigene Befehle gelernt werden müssen, soll die Toolchain eine einfache und einheitliche Benutzerschnittstelle bieten. Gleichzeitig soll sie jedoch transparent genug sein, dass erfahrene und interessierte Nutzer die darunterliegenden Befehle nachvollziehen und verstehen können.
4. Terminal-basierend: Die primäre Schnittstelle ist das Terminal. Ein Terminal kann in den meisten Editoren und IDEs direkt verwendet werden. Der textbasierte Ansatz ist auch für Menschen mit Seheinschränkung wichtig, damit die Toolchain mit assistiven Technologien nutzbar ist.
5. Sicherheit: Die Entwicklungsumgebung und die ausgeführten Programme sollen keinen Zugriff auf das gesamte System erhalten. Stattdessen steht nur das Projektverzeichnis zur Laufzeit zur Verfügung. Auch der Netzwerkzugriff kann für manche Projekte verweigert werden, um mögliche Risiken zu reduzieren.

Installation

Damit die Toolchain verwendet werden kann muss just und Podman installiert werden. Darüber hinaus empfehle ich den Editor VSCodium (oder VSCode):

just

Die Installation hängt vom Betriebssystem ab. Am einfachsten ist die Installation über das Terminal:

• Unter Windows mit winget: winget install -e Casey.Just
• Unter macOS mit Homebrew (muss installiert sein): brew install just
• Unter Linux mit dem passenden Package Manager, z.B. sudo dnf install just

Nach der Installation müssen alle Terminals neu geladen werden. Schließen Sie dazu alle Terminals (inkl. des Editors oder der IDE) und starten Sie die Programme neu.

Podman

Unter Windows und macOS wird die Installation von Podman Desktop empfohlen. Nach der Installation müssen noch weitere Schritte durchgeführt werden. Insbesondere müssen Sie unter Windows das Windows Subsystem for Linux 2 (WSL2) einrichten.

Auf Linux-Systemen kann Podman CLI installiert werden (z.B. über apt/dnf/...). In diesem Fall gibt es kein GUI Programm und Podman muss über das Terminal bedient werden. Da unter Linux die Einrichtung sehr einfach ist, ist dies die empfohlene Methode. Unter Windows und macOS ist Podman Desktop leichter einzurichten. Aber auch hier ist es möglich nur das CLI zu installieren:

• Windows: winget install -e RedHat.Podman
• macOS: brew install podman

VSCodium (optional)

Die Toolchain ist unabhängig vom verwendeten Editor / IDE. Für den Start wird VSCodium oder Visual Studio Code empfohlen, da die Projekte für diese Editoren bereits die passenden Workspace- und Konfigurationsdateien besitzen.

Unter Windows und macOS können die Installer der Projektwebseiten verwendet werden: VSCodium oder Visual Studio Code. Oder per Terminal:

• Windows: winget install -e VSCodium.VSCodium
• macOS: brew install --cask vscodium

Unter Linux kann der Editor als Flatpak von Flathub installiert werden: flatpak install com.vscodium.codium

Verwendung

Wie öffne ich ein Projekt?

Laden Sie das Projekt-Repository herunter (z.B. als ZIP-Datei oder per Git). Öffnen Sie die .code-workspace-Datei per Doppelklick oder innerhalb Ihres Editors (File → Open Workspace from File...). Dadurch wird auch automatisch das richtige Verzeichnis im Terminal gesetzt. Je nach Projekt werden noch passende VSCodium/VSCode Erweiterungen vorgeschlagen (z.B. EditorConfig). Diese sind empfohlen, aber nicht notwendig.

Bei anderen Editoren und IDEs müssen Sie manuell das Verzeichnis prüfen und eventuell mit cd in das Projektverzeichnis mit der Datei justfile navigieren. Es wird empfohlen den Workspace zu nutzen.

Wie verwende ich die Toolchain?

Das Kompilieren und Ausführen des Projekts geschieht ganz einfach innerhalb des Terminals. Der Befehl just gibt eine Liste mit den im Projekt definierten Tasks aus. Beispiele für häufig definierte Tasks sind:

• just setup zur Installation zusätzlicher Abhängigkeiten, welche im Projekt verwendet werden, aber nicht im Container bereitgestellt werden (z.B. npm-Pakete). Falls vorhanden, muss dieser Befehl nur einmal für jedes neue Projekt ausgeführt werden.
• just build baut das Projekt im Verzeichnis src. Das Resultat wird meist in out oder dist abgelegt.
• just run startet ein gebautes Programm. Jedes Projekt enthält eine Hauptdatei, welche automatisch gestartet wird. Es kann aber auch eine spezifische Datei beim Start angegeben werden, z.B. just run dist/MyOtherFile.js.
• just serve startet den gebauten Webserver. Dieser läuft bis er mit Ctrl+C beendet wird.

Mehrere Befehle können auch nacheinander ausgeführt werden, indem die Tasknamen hintereinander geschrieben werden (z.B. just build run zum Bauen und Ausführen eines Programms).

Testen der Toolchain

Dieses Repository enthält ein Projekt zum Testen der Toolchain. Öffnen Sie das Projekt durch Öffnen von Toolchain.code-workspace in VSCodium. Danach kann durch just test geprüft werden, ob die Toolchain richtig installiert wurde. Der Befehl lädt ein alpine:3.23.0 Image und startet ihn als Container, um einen Text auszugeben.

Behind the Scenes: Wie funktioniert die Toolchain?

Das folgende Diagramm zeigt den Zusammenhang zwischen den Komponenten der Toolchain:

Beim ersten Aufruf von just wird ein Image aus einer Registry im Internet geladen. Dieses Image ist projektspezifisch und enthält relevante Programme zum Bauen und Ausführen dieser Anwendung (z.B. node:25-alpine für TypeScript-Projekte). Daher kann die erste Nutzung der Toolchain je nach Internetverbindung etwas länger dauern. Das Projekt wurde im Vorfeld bereits mit exakt dieser Version des Images getestet. Der Container wird für jeden Aufruf von just neu gebaut, sodass alle Abläufe reproduzierbar sind.

Im Container sind die projektspezifischen Programme enthalten, welche Sie zum Entwickeln von TypeScript-Anwendungen und Server benötigen. Für manche Projekte sind jedoch zusätzliche Abhängigkeiten und Programme notwendig (z.B. Bibliotheken), welche zu speziell für das Image wären. Diese werden mit just setup einmalig lokal in den Projektordner installiert (z.B. tsc bei TypeScript-Projekten).

Das Ausführen der Build-Tools und der Anwendung innerhalb eines Containers hat auch den Vorteil, dass die im Container ausgeführten Programme keinen Zugriff auf Dateien außerhalb des Projektverzeichnisses erhalten. Dies erhöht die Sicherheit und verhindert, dass schädlicher Programmcode (z.B. Code aus dem Internet oder KI-generierter Code) aus Versehen den Computer lahmlegt oder wichtige Dateien löscht.