Seminar Kroki – Docker- und Podman-Self-Hosting

Einen eigenen Diagrammservice reproduzierbar bereitstellen

Self-Hosting schafft Kontrolle über Verfügbarkeit, Datenwege und freigegebene Diagrammtypen. Kroki besteht aus einem Gateway und optionalen Companion-Diensten. Das Seminar setzt diese Architektur mit Docker oder Podman in eine nachvollziehbare, aktualisierbare Betriebsumgebung um.

Zwei Tage sind notwendig, weil neben dem Start eines Containers auch Netzwerkmodell, Companion-Dienste, Konfiguration, Reverse Proxy, Ressourcenbegrenzung, Protokollierung und Updateverfahren praktisch erprobt werden. Das Ergebnis ist keine Einmalinstallation, sondern ein wiederholbarer Betriebsstand.

Inhaltsübersicht

• Kroki-Gateway und optionale Companion-Dienste
• Image-Auswahl, Versionierung und lokale Voraussetzungen
• Containerstart, Portfreigabe und Persistenzbedarf
• Netzwerke und Anbindung von Mermaid, BPMN und Excalidraw
• Umgebungsvariablen und Konfigurationsverwaltung
• Reverse Proxy, TLS-Terminierung und Zugriffsgrenzen
• Ressourcen, Health Checks, Protokolle und Fehlerdiagnose
• Update, Rollback und Betriebsdokumentation

Zielgruppe

Das Seminar richtet sich an Linux-Administratoren, DevOps-Fachkräfte, Plattformteams und technisch verantwortliche Entwickler. Es eignet sich für interne Dokumentationsdienste, Entwicklungsplattformen und abgeschottete Umgebungen, in denen externe Rendering-Dienste nicht verwendet werden sollen.

Voraussetzungen

Erforderlich sind Grundkenntnisse in Linux, Containerkonzepten, Netzwerken und Kommandozeile. Praktische Erfahrung mit Docker oder Podman ist hilfreich. Für Übungen zu Reverse Proxy und Zertifikaten genügen grundlegende Kenntnisse; eine produktive Infrastruktur wird nicht vorausgesetzt.

Lernstrecke Schritt für Schritt

1. Schritt 1: Betriebsanforderungen und Diagrammtypen erfassen. Benötigte Sprachen, erwartete Last, interne Datenklassen und Integrationen werden dokumentiert. Daraus ergibt sich, ob das Gateway allein oder zusätzliche Companion-Dienste erforderlich sind.
2. Schritt 2: Gateway-Image kontrolliert starten. Containername, Imageversion, Portfreigabe und Neustartverhalten werden festgelegt. Ein einfacher API-Test bestätigt Erreichbarkeit, Diagrammtyp und Ausgabeformat.
3. Schritt 3: Containerlaufzeit vergleichen. Docker- und Podman-Befehle werden gegenübergestellt. Rootless-Betrieb, Benutzerkontext, Netzwerkverhalten und Dienstverwaltung werden für die Zielumgebung bewertet.
4. Schritt 4: Companion-Dienste anbinden. Mermaid, BPMN und Excalidraw werden als getrennte Dienste gestartet. Das Gateway erhält eindeutige interne Adressen und die Funktion jedes Endpunkts wird geprüft.
5. Schritt 5: Netzwerke und Namensauflösung gestalten. Interne und veröffentlichte Ports werden getrennt. Nur notwendige Dienste sind erreichbar; Container kommunizieren über klar benannte Netze.
6. Schritt 6: Konfiguration über Umgebungsvariablen verwalten. Listenadresse, sichere Betriebsart, Companion-Adressen und weitere Einstellungen werden in einer versionierbaren, aber geheimnisfreien Konfiguration beschrieben.
7. Schritt 7: Einen Compose- oder Pod-Verbund erstellen. Mehrere Dienste werden gemeinsam gestartet, geprüft und beendet. Abhängigkeiten, Neustarts und eindeutige Imageversionen machen den Aufbau wiederholbar.
8. Schritt 8: Reverse Proxy und TLS-Grenze einrichten. Ein vorgelagerter Proxy übernimmt TLS, Größenbegrenzung und bei Bedarf Authentisierung. Interner Kroki-Verkehr und externe Erreichbarkeit bleiben voneinander getrennt.
9. Schritt 9: Ressourcen und Laufzeitgrenzen setzen. CPU, Arbeitsspeicher, Prozesse und Zeitüberschreitungen werden passend zum Rendering-Aufwand begrenzt. Besonders ressourcenintensive Companion-Dienste werden separat betrachtet.
10. Schritt 10: Health Checks und Protokolle auswerten. Erreichbarkeit, Beispielrendering, Containerstatus und Logmeldungen bilden eine mehrstufige Betriebsprüfung. Fehler werden Gateway, Companion oder Proxy zugeordnet.
11. Schritt 11: Updates mit Rückweg durchführen. Neue Images werden zunächst in einer Testumgebung geprüft. Gesicherte Konfiguration, feste Versionen und ein dokumentierter Rollback verhindern unkontrollierte Betriebswechsel.
12. Schritt 12: Betriebsübergabe dokumentieren. Start, Stopp, Test, Update, Fehlerdiagnose und Verantwortlichkeiten werden in einem kurzen Betriebshandbuch zusammengefasst und praktisch gegengeprüft.

Praxisaufgaben

• Ein minimales Gateway mit festem Image und Funktionsprüfung starten.
• Mermaid- und BPMN-Companion-Dienste in ein internes Containernetz einbinden.
• Eine wiederholbare Mehrcontainer-Konfiguration erstellen.
• Ressourcenbegrenzung, Logauswertung und einen gezielten Dienstausfall testen.
• Ein Update mit Vorprüfung und dokumentiertem Rollback durchführen.

Kompetenzziele

• Kroki-Gateway und Companion-Dienste passend zum Bedarf auswählen.
• Docker- oder Podman-Bereitstellungen reproduzierbar konfigurieren.
• Netzwerke, Ports und Reverse-Proxy-Grenzen sicher strukturieren.
• Ressourcen, Protokolle und Health Checks für den Betrieb nutzen.
• Updates, Rollback und Betriebsübergabe kontrolliert durchführen.