Seminar Kroki – Kompaktseminar: Diagramme, API und Self-Hosting

Der konzentrierte Einstieg für technische Teams

Das Kompaktseminar verbindet die wichtigsten Anwender-, Entwickler- und Betriebsaspekte in einer dreitägigen Lernstrecke. Es richtet sich an Teams, die kurzfristig einen gemeinsamen Kroki-Workflow aufbauen müssen und zunächst keine tiefe Spezialisierung auf einzelne Diagrammsprachen oder Clusterbetrieb benötigen.

Drei Tage sind notwendig, damit Diagrammquellen, API-Nutzung, Dokumentationsintegration und ein eigener Containerbetrieb praktisch zusammengeführt werden können. Der Umfang bleibt bewusst auf einen tragfähigen Kern beschränkt und weist klare Anschlussstellen zu den Fach- und Intensivseminaren aus.

Inhaltsübersicht

• Diagrams as Code und Auswahl geeigneter Diagrammsprachen
• Erste PlantUML-, Mermaid- und GraphViz-Diagramme
• Kroki-API mit GET, POST, Formaten und Optionen
• Quellenstruktur, Versionsverwaltung und Reviews
• AsciiDoc- oder Markdown-Integration
• CLI, Skripte und einfacher CI-Build
• Docker- oder Podman-Self-Hosting mit Companion-Diensten
• Sicherheitsgrundlagen und Teamworkflow

Zielgruppe

Das Seminar richtet sich an gemischte Teams aus Entwicklung, Architektur, technischer Redaktion und Administration. Es eignet sich für Pilotprojekte, interne Evaluierungen und den gemeinsamen Start eines Diagrams-as-Code-Ansatzes.

Voraussetzungen

Erforderlich sind allgemeine IT-Kenntnisse und Grundkenntnisse der Versionsverwaltung. Für den Betriebsanteil sind einfache Kenntnisse zu Kommandozeile und Containern hilfreich. Tiefgehende Programmier- oder Kubernetes-Kenntnisse werden nicht vorausgesetzt.

Lernstrecke Schritt für Schritt

1. Schritt 1: Einsatzszenario und Erfolgskriterien festlegen. Typische Diagramme, Zielgruppen, Dokumentationsorte und Betriebsgrenzen werden gesammelt. Der Pilot erhält einen klaren Umfang.
2. Schritt 2: Diagrams as Code praktisch einordnen. Quelltext, gerenderte Ausgabe, Versionsverwaltung und Review werden als zusammenhängender Lebenszyklus verstanden.
3. Schritt 3: PlantUML-Grundlagen anwenden. Ein Struktur- und ein Ablaufdiagramm werden erstellt, gerendert und anhand gemeinsamer Begriffe überprüft.
4. Schritt 4: Mermaid und GraphViz vergleichen. Ein Prozess und ein Abhängigkeitsgraph werden mit passenden Notationen umgesetzt. Auswahlkriterien werden schriftlich festgehalten.
5. Schritt 5: Kroki per POST und GET ansprechen. Klartext, JSON und eine vorbereitete kodierte Anfrage zeigen die grundlegenden Zugriffsmöglichkeiten.
6. Schritt 6: Ausgabeformate und Optionen nutzen. SVG und Rasterausgabe werden verglichen; ausgewählte Diagrammoptionen werden kontrolliert übergeben.
7. Schritt 7: Quellen im Repository organisieren. Ordner, Dateinamen, Zuständigkeit, Review und generierte Artefakte erhalten einfache, verbindliche Regeln.
8. Schritt 8: Eine Dokumentationsintegration umsetzen. Ein Diagramm wird in AsciiDoc oder Markdown eingebunden. Lokale Vorschau und automatisierter Build werden abgestimmt.
9. Schritt 9: CLI und Skriptaufruf automatisieren. Mehrere Quellen werden mit festen Rückgabecodes und Zielnamen konvertiert. Fehler führen zu verständlichen Meldungen.
10. Schritt 10: Kroki im Container starten. Gateway, Port und Imageversion werden festgelegt. Ein Funktionscheck bestätigt den lokalen Dienst.
11. Schritt 11: Einen Companion-Dienst ergänzen. Mermaid oder BPMN wird als zusätzlicher Container eingebunden und über das Gateway getestet.
12. Schritt 12: Sicherheitsgrundlagen anwenden. Sicherer Betriebsmodus, interne Netze, Reverse-Proxy-Grenze, Größenlimits und kontrollierte Erreichbarkeit werden eingeordnet.
13. Schritt 13: Einen Teamworkflow definieren. Von der Änderung einer Quelle bis zur Freigabe der Dokumentation entsteht ein kurzer, wiederholbarer Ablauf.
14. Schritt 14: Das Pilotprojekt abschließen. Mehrere Diagrammtypen werden in einer Dokumentation gerendert, reviewed und über die lokale Instanz erneut erzeugt.

Praxisaufgaben

• Drei unterschiedliche Diagrammtypen für ein gemeinsames Beispielsystem erstellen.
• Ein Diagramm per API und anschließend per CLI rendern.
• Eine kleine Dokumentationsseite mit versionierter Quelle aufbauen.
• Gateway und einen Companion-Dienst in Containern starten.
• Einen Teamablauf mit Benennung, Review, Build und Freigabe dokumentieren.

Kompetenzziele

• Kroki und Diagrams as Code im Teamkontext einordnen.
• Einfache PlantUML-, Mermaid- und GraphViz-Quellen erstellen.
• API, Ausgabeformate und grundlegende Optionen verwenden.
• Diagramme in Dokumentation und einfache Automatisierung integrieren.
• Eine kleine selbst verwaltete Kroki-Umgebung sicher betreiben.