Seminar Antora – Betrieb, Performance und Troubleshooting

Beschreibung

Das Seminar vermittelt den stabilen Betrieb einer Antora-Build- und Veröffentlichungsumgebung. Behandelt werden Logauswertung, reproduzierbare Fehleranalyse, Cache- und Arbeitsverzeichnisverhalten, defekte Inhaltsquellen, UI- und Konvertierungsfehler, Laufzeit- und Speicherengpässe sowie Runbooks für Wiederanlauf und Incident-Bearbeitung. Fehler werden anhand vorbereiteter Laborszenarien schrittweise eingegrenzt.

Inhaltsübersicht

1. Betriebsmodell und Diagnosebasis
2. Content-Quellen, Git und Arbeitsverzeichnisse
3. Inhalts-, Verweis- und Konvertierungsfehler
4. UI-, Erweiterungs- und Publikationsfehler
5. Performance-Messung und Optimierung
6. Runbooks, Wiederanlauf und Incident-Bearbeitung

Lernziele

• Build- und Veröffentlichungsfehler reproduzierbar eingrenzen.
• Logs, Exit-Codes und Pipeline-Artefakte als Diagnosebasis nutzen.
• Laufzeit-, Speicher- und I/O-Engpässe messen und priorisieren.
• Runbooks für Wiederanlauf, Rollback und Incident-Bearbeitung erstellen.

1. Betriebsmodell und Diagnosebasis

Eine belastbare Diagnose beginnt mit einer bekannten Laufzeit, unveränderten Eingaben und gesicherten Build-Artefakten.

Schritt-für-Schritt: Einen reproduzierbaren Diagnosefall vorbereiten

1. Antora-, Node.js- und Paketversionen sowie Betriebssystem und Build-Parameter erfassen.
2. Playbook, Lockdatei, relevante Umgebungsvariablen und Commitstände der Quellen sichern.
3. Build mit definierter Logstufe und getrenntem Ausgabeverzeichnis erneut ausführen.
4. Exit-Code, Laufzeit, Speicherbedarf und vollständiges Log als Incident-Artefakte speichern.
5. Fehler auf Inhalt, Quellzugriff, Konvertierung, UI, Erweiterung oder Veröffentlichung vorläufig klassifizieren.

Praxisaufgabe

Ein nicht deterministischer Buildfehler wird in einen reproduzierbaren, dokumentierten Testfall überführt.

2. Content-Quellen, Git und Arbeitsverzeichnisse

Fehler beim Klonen, Aktualisieren oder Auswählen von Branches, Tags und Worktrees werden von Inhaltsfehlern getrennt untersucht.

Schritt-für-Schritt: Quellzugriffsfehler systematisch eingrenzen

1. Erreichbarkeit, Berechtigung und ausgewählte Referenzen jeder Inhaltsquelle einzeln prüfen.
2. Branch-, Tag- und Worktree-Muster mit den tatsächlich vorhandenen Git-Referenzen vergleichen.
3. Cache- und temporäre Arbeitsverzeichnisse identifizieren und deren Besitzrechte kontrollieren.
4. Build mit leerem Cache ausführen und Ergebnis mit dem inkrementellen Lauf vergleichen.
5. Große oder fehlerhafte Repositories durch schrittweises Deaktivieren isolieren.
6. Korrektur und Cache-Bereinigung so dokumentieren, dass kein unnötiger Datenverlust entsteht.

Praxisaufgabe

Mehrere vorbereitete Fehler zu Referenzmustern, Berechtigungen und veraltetem Cache werden diagnostiziert.

3. Inhalts-, Verweis- und Konvertierungsfehler

Warnungen zu fehlenden Ressourcen, ungültigen Includes oder AsciiDoc-Strukturen werden auf die verursachende Seite und den Buildkontext zurückgeführt.

Schritt-für-Schritt: Eine fehlerhafte Seite bis zur Ursache verfolgen

1. Logmeldung nach Schweregrad, Komponente, Version und Quelldatei auswerten.
2. Ressourcen-ID, Modul, Familie und tatsächlichen Dateipfad miteinander vergleichen.
3. Include-, xref-, Bild- und Attributauflösung in der betroffenen Seite einzeln prüfen.
4. Minimales Reproduktionsdokument erstellen und nicht beteiligte Inhalte entfernen.
5. Korrektur in einem isolierten Build verifizieren und anschließend den Gesamtbuild ausführen.
6. Regressionstest für den gefundenen Fehler in die Qualitätsprüfung aufnehmen.

Praxisaufgabe

Ein Satz aus defekten xrefs, Includes, Attributen und Seiteneigenschaften wird mit einer festen Diagnosefolge korrigiert.

4. UI-, Erweiterungs- und Publikationsfehler

Fehler nach der Inhaltskonvertierung können aus UI-Bundles, Helfern, Erweiterungen oder dem Zielsystem der Veröffentlichung entstehen.

Schritt-für-Schritt: Pipelineabschnitte gegeneinander abgrenzen

1. Build zunächst mit bekanntem UI-Bundle und deaktivierten optionalen Erweiterungen ausführen.
2. Erweiterungen einzeln aktivieren und Ereignis sowie Logausgabe des Fehlers bestimmen.
3. UI-Templates, Helfermodule und statische Assets auf fehlende oder inkompatible Einträge prüfen.
4. Erzeugte Site lokal kontrollieren, bevor ein Veröffentlichungsfehler untersucht wird.
5. Schreibrechte, Zielpfade, atomare Umschaltung und Bereinigungsregeln des Publish-Schritts testen.
6. Nach Korrektur sowohl Inhalt als auch Deployment mit einem Ende-zu-Ende-Test verifizieren.

Praxisaufgabe

Ein defektes UI-Bundle und ein fehlgeschlagener Publish-Schritt werden unabhängig diagnostiziert und behoben.

5. Performance-Messung und Optimierung

Optimierung erfolgt anhand gemessener Engpässe und nicht durch pauschale Cache- oder Parallelisierungseinstellungen.

Schritt-für-Schritt: Eine Performance-Baseline erstellen und verbessern

1. Referenzbuild mit fester Eingabe und mindestens drei Messläufen durchführen.
2. Zeitanteile für Quellabruf, Aggregation, Konvertierung, UI und Veröffentlichung soweit möglich erfassen.
3. Repository-Größe, Seitenzahl, Asset-Volumen, Erweiterungen und Suchindex als Einflussgrößen dokumentieren.
4. Engpass nach CPU, Speicher, Netzwerk oder Dateisystem klassifizieren.
5. Jeweils eine Optimierungsmaßnahme anwenden und gegen die Baseline vergleichen.
6. Verbesserung, Nebenwirkungen und Rückfallkriterium in einem Performance-Protokoll festhalten.

Praxisaufgabe

Eine langsame Beispielsite wird vermessen; Optimierungen werden mit nachvollziehbarem Vorher-Nachher-Vergleich bewertet.

6. Runbooks, Wiederanlauf und Incident-Bearbeitung

Betriebswissen wird in kurze, prüfbare Verfahren für Störung, Rücksetzung, Wiederanlauf und Eskalation überführt.

Schritt-für-Schritt: Ein Betriebsrunbook erstellen

1. Häufige Störungsklassen und ihre ersten Prüfungen als Entscheidungsbaum formulieren.
2. Sichere Schritte zum Stoppen, Sichern, Bereinigen und erneuten Starten festlegen.
3. Kriterien für Rollback auf vorherige Pakete, UI-Bundles oder Site-Artefakte definieren.
4. Benötigte Logs, Zuständigkeiten und Eskalationswege pro Fehlerklasse festhalten.
5. Runbook in einer simulierten Störung ohne zusätzliches Expertenwissen ausführen.
6. Unklare oder fehlende Schritte aus dem Probelauf unmittelbar korrigieren.

Praxisaufgabe

Zum Abschluss entsteht ein getestetes Runbook für Buildausfall, fehlerhafte Veröffentlichung und Performance-Regressionsalarm.

Zielgruppe und Voraussetzungen

Zielgruppe: Plattformbetrieb, DevOps und SRE, Build- und Release-Engineering, technische Dokumentationssysteme, Second-Level-Support und verantwortliche Entwicklerteams.

Voraussetzungen: Praktische Antora-Grundkenntnisse, sicherer Umgang mit Kommandozeile, Git und Node.js-Paketprojekten.

Methodik und Arbeitsweise

Die Inhalte werden durch strukturierte Erläuterungen, Demonstrationen, schrittweise Konfigurations- und Analyseaufgaben sowie kontrollierte Fehlerfälle vertieft. Jede Übung verwendet definierte Ausgangswerte, Prüfpunkte und Dokumentationsanforderungen, damit die erarbeiteten Abläufe im späteren Projekt- und Betriebsalltag reproduzierbar bleiben.