Seminar Kroki – Intensivseminar: Komplettprogramm für Diagramme, Integration und Betrieb

Vom Diagrammtext bis zum belastbaren Plattformbetrieb

Das Komplettprogramm bündelt die fachlichen, technischen und organisatorischen Aspekte eines Kroki-Einsatzes. Es beginnt bei reproduzierbaren Diagrammquellen und führt über API, Dokumentationsintegration und Automatisierung bis zu einem abgesicherten, beobachtbaren und skalierbaren Eigenbetrieb.

Fünf Seminartage sind erforderlich, weil mehrere Diagrammfamilien praktisch verglichen, ein Dokumentationsworkflow aufgebaut und zusätzlich Betriebs-, Sicherheits- und Governance-Aufgaben umgesetzt werden. Die komprimierte Lernstrecke vermittelt den Gesamtzusammenhang; Spezialseminare bleiben für vertiefte Produktivprojekte sinnvoll.

Inhaltsübersicht

• Grundprinzipien von Diagrams as Code und Kroki-Architektur
• Diagrammsprachen für Architektur, Prozesse, Daten, Netzwerke und Visualisierung
• HTTP-API, Kodierung, Formate, Optionen und reproduzierbare Aufrufe
• Integration in AsciiDoc, Markdown, GitLab und Sphinx
• CLI-, Skript- und CI/CD-Automatisierung
• Docker- und Podman-Betrieb einschließlich Komponentenplanung
• Sicherheit, Konfiguration, Härtung und kontrollierte Freigaben
• Kubernetes, Skalierung, Monitoring, Migration und Governance

Zielgruppe

Das Intensivseminar richtet sich an technische Redakteure, Softwareentwickler, Architekten, DevOps- und Plattformteams sowie technische Projektleitungen, die Kroki als gemeinsamen Diagrammservice einführen oder einen bestehenden Einsatz vereinheitlichen.

Voraussetzungen

Erforderlich sind sichere Grundlagen im Umgang mit Textdateien und Versionsverwaltung. Grundkenntnisse in HTTP, Kommandozeile, Containern und YAML sind hilfreich. Für die Kubernetes-Übungen werden elementare Kenntnisse zu Pods, Services und Konfiguration erwartet.

Lernstrecke Schritt für Schritt

1. Schritt 1: Zielbild und Referenzprozess festlegen Ein gemeinsamer Dokumentationsfall wird abgegrenzt. Diagrammarten, Zielgruppen, Ablageorte, Ausgabeformate, Freigaben und Betriebsanforderungen werden als messbares Zielbild beschrieben.
2. Schritt 2: Kroki-Komponenten und Datenfluss modellieren Gateway, Diagramm-Engines, Client, Dokumentationswerkzeug, Cache, Netzwerkpfade und Ausgabeziele werden in einem nachvollziehbaren Datenfluss angeordnet.
3. Schritt 3: Diagrammquellen reproduzierbar strukturieren Dateinamen, Verzeichnisse, Zeichensätze, Metadaten, Versionierung und Trennung von Quelltext und erzeugten Artefakten werden als belastbare Basis eingerichtet.
4. Schritt 4: Sprachen für Architektur und Sequenzen vergleichen PlantUML, C4, Structurizr, Mermaid und D2 werden an demselben Architekturfall geprüft. Ausdrucksstärke, Lesbarkeit, Wartbarkeit und Teamfähigkeit werden bewertet.
5. Schritt 5: Prozesse, Datenmodelle und Graphen umsetzen BPMN, ERD und GraphViz werden für Prozess-, Beziehungs- und Abhängigkeitsdarstellungen eingesetzt. Modellgrenzen und geeignete Detaillierungsgrade werden festgelegt.
6. Schritt 6: Netzwerk-, Hardware- und Visualisierungsfälle abdecken NwDiag-, PacketDiag-, RackDiag-, WaveDrom-, WireViz- sowie Vega- und Vega-Lite-Fälle werden eingeordnet und mit kleinen, prüfbaren Beispielen umgesetzt.
7. Schritt 7: HTTP-API über GET und POST verwenden Endpunkte, Diagrammtyp, Ausgabeformat und Nutzdaten werden systematisch aufgebaut. Geeignete Einsatzgrenzen für URL-basierte und body-basierte Übertragung werden bestimmt.
8. Schritt 8: Kodierung, Formate und Optionen beherrschen Kompression, URL-sichere Kodierung, Klartext- und JSON-Nutzdaten, SVG, PNG, PDF sowie optionale Parameter werden reproduzierbar erzeugt und auf Fehlerfälle geprüft.
9. Schritt 9: Dokumentationssysteme integrieren AsciiDoc-, Markdown-, GitLab- und Sphinx-Workflows werden konzeptionell und praktisch verbunden. Lokale Vorschau, Build-Ausgabe und konsistente Referenzen werden abgesichert.
10. Schritt 10: CLI und Skripte standardisieren Wiederverwendbare Befehle, Konfigurationsdateien, Stapelverarbeitung, Fehlercodes, Zeitlimits und Artefaktprüfung werden für lokale und automatisierte Abläufe aufgebaut.
11. Schritt 11: CI/CD-Pipeline mit Qualitätsgates erstellen Diagrammquellen werden bei Änderungen gerendert, geprüft und als Artefakte bereitgestellt. Fehlende Quellen, ungültige Syntax und unerwartete Ausgabeänderungen führen zu klaren Pipeline-Ergebnissen.
12. Schritt 12: Self-Hosting mit Docker oder Podman aufbauen Netzwerk, Ports, Volumes, Images, optionale Renderer, Neustartverhalten und Persistenzanforderungen werden in einer reproduzierbaren Containerkonfiguration umgesetzt.
13. Schritt 13: Konfiguration und Sicherheitsgrenzen härten Erlaubte Diagrammtypen, Größen, Zeitlimits, Netzwerkzugriffe, Safe Modes, Secrets, Image-Herkunft und Protokollierung werden nach einem minimalen Berechtigungs- und Expositionsprinzip eingestellt.
14. Schritt 14: Kubernetes-Bereitstellung planen Deployments, Services, Konfigurationsobjekte, Ressourcenlimits, Health Checks, Rolling Updates und horizontale Skalierung werden für einen kontrollierten Clusterbetrieb zusammengestellt.
15. Schritt 15: Monitoring und Fehleranalyse einrichten Metriken, Logs, Traces, Latenzen, Fehlerquoten, Ressourcenverbrauch und Renderer-Ausfälle werden beobachtbar gemacht. Ein strukturierter Diagnosepfad wird an Störungen erprobt.
16. Schritt 16: Bestände migrieren und Kompatibilität sichern Vorhandene Bilddateien und Diagrammquellen werden inventarisiert, priorisiert und schrittweise in versionierte Quellen überführt. Referenzen und Ausgabeunterschiede werden kontrolliert.
17. Schritt 17: Teamstandards und Governance verankern Sprachauswahl, Namensregeln, Vorlagen, Reviews, Verantwortlichkeiten, Lebenszyklus, Ausnahmen und Archivierung werden in einem praktikablen Regelwerk festgelegt.
18. Schritt 18: Gesamtprozess abnehmen und Betriebsübergabe vorbereiten Der Referenzfall wird von der Quelländerung über Review und Pipeline bis zum Produktiv-Rendering durchlaufen. Abnahmekriterien, Runbook, Rückfallweg und nächste Vertiefungen werden dokumentiert.

Praxisaufgaben

• Mehrere Diagrammsprachen anhand eines gemeinsamen Unternehmensszenarios vergleichen
• API-Aufrufe und Kodierung für SVG-, PNG- und PDF-Ausgabe reproduzierbar erstellen
• Dokumentationsbuild mit automatischer Diagrammerzeugung und Qualitätsprüfung aufbauen
• Abgesicherten Containerdienst mit Betriebs- und Diagnosekonfiguration bereitstellen
• Einführungs-, Migrations- und Governance-Paket für den späteren Produktiveinsatz erstellen

Kompetenzziele

• Kroki als durchgängigen Diagramm- und Dokumentationsdienst fachlich einordnen
• Geeignete Diagrammsprachen und Ausgabewege begründet auswählen
• API-, Dokumentations- und Automatisierungsabläufe reproduzierbar umsetzen
• Self-Hosting, Sicherheit, Kubernetes und Beobachtbarkeit zusammen planen
• Migration, Standards, Rollen und Betriebsübergabe kontrolliert gestalten