Seminar Antora – CI/CD, Container und automatisierte Veröffentlichung

Beschreibung

Das Seminar entwickelt eine reproduzierbare Antora-Pipeline vom Commit bis zur kontrollierten Veröffentlichung. Im Mittelpunkt stehen deklarative Buildumgebungen, Node.js-Paketmanagement, Container, Cache-Strategien, Qualitätsprüfungen, private Inhaltsquellen, sichere Zugangsdaten, Vorschauumgebungen, atomare Deployments und Rollback. Die Übungen werden als durchgängige Pipeline mit klaren Prüfpunkten umgesetzt.

Inhaltsübersicht

1. Reproduzierbares Buildprojekt
2. Containerisierte Laufzeit
3. Pipeline-Stufen, Cache und Artefakte
4. Qualitätsgates für Inhalte und Ausgabe
5. Private Quellen und Zugangsdaten
6. Vorschau und Freigabefluss
7. Produktionsdeployment und Rollback
8. Beobachtbarkeit und Betriebsübergabe

Lernziele

• Eine reproduzierbare Antora-Laufzeit für lokale und CI-Builds definieren.
• Pipeline-Stufen mit Caches, Artefakten und Qualitätsgates aufbauen.
• Private Repositories und Geheimnisse sicher in den Build integrieren.
• Vorschau, Veröffentlichung, atomare Umschaltung und Rollback automatisieren.

1. Reproduzierbares Buildprojekt

Die Pipeline beginnt mit einem versionierten Playbook-Projekt, gesperrten Abhängigkeiten und identischen lokalen sowie automatisierten Buildbefehlen.

Schritt-für-Schritt: Das Buildprojekt stabilisieren

1. Playbook, Paketmanifest, Lockdatei und Buildskripte in einem eigenen Repository strukturieren.
2. Antora CLI, Site Generator, Erweiterungen und UI-Abhängigkeiten explizit versionieren.
3. Saubere Installation der Abhängigkeiten aus der Lockdatei erzwingen.
4. Lokalen Buildbefehl ohne globale Pakete und ohne manuelle Vorbedingungen ausführen.
5. Ausgabeverzeichnis, temporäre Daten und Caches klar voneinander trennen.
6. Versionen und Buildparameter als maschinenlesbare Artefaktmetadaten ausgeben.

Praxisaufgabe

Ein zuvor nur manuell funktionierendes Projekt wird in einen reproduzierbaren Build mit gesperrten Abhängigkeiten überführt.

2. Containerisierte Laufzeit

Ein Container kapselt Laufzeit und Werkzeuge, muss aber Benutzerrechte, Caches, Dateizugriffe und Erweiterungen bewusst behandeln.

Schritt-für-Schritt: Ein Build-Image erstellen und prüfen

1. Geeignete Basislaufzeit und unterstützte Node.js-Version auswählen.
2. Abhängigkeiten in einer deterministischen Image-Stufe installieren und unnötige Werkzeuge entfernen.
3. Nicht privilegierten Benutzer, Arbeitsverzeichnis und benötigte Mountpunkte definieren.
4. Git-Zertifikate, Zeitzone, Locale und Dateiberechtigungen kontrolliert konfigurieren.
5. Image mit festem Tag und unveränderlicher Referenz in der Pipeline verwenden.
6. Lokalen und CI-Build mit demselben Image ausführen und Ausgaben vergleichen.

Praxisaufgabe

Ein minimales Build-Image wird erstellt, mit Read-only-Anteilen gehärtet und gegen Berechtigungsfehler getestet.

3. Pipeline-Stufen, Cache und Artefakte

Klare Stufen ermöglichen gezielte Wiederholung und verhindern, dass ein fehlerhafter Build direkt veröffentlicht wird.

Schritt-für-Schritt: Eine mehrstufige Pipeline aufbauen

1. Stufen für Installation, Inhaltsprüfung, Site-Build, Ausgabekontrolle, Paketierung und Deployment definieren.
2. Abhängigkeiten, Git-Cache und erzeugte Site als unterschiedliche Cache- oder Artefaktarten behandeln.
3. Cache-Schlüssel an Lockdatei, Laufzeit und relevante Konfiguration koppeln.
4. Artefakte mit Aufbewahrungsdauer, Prüfsumme und Buildmetadaten versehen.
5. Abhängigkeiten zwischen Stufen so setzen, dass nur geprüfte Ausgaben weitergereicht werden.
6. Fehlerfall und Wiederholung einer einzelnen Stufe ohne versteckte Seiteneffekte testen.

Praxisaufgabe

Eine Pipeline wird aufgebaut und anschließend mit absichtlich veraltetem Cache sowie abgebrochener Stufe getestet.

4. Qualitätsgates für Inhalte und Ausgabe

Vor der Veröffentlichung werden strukturelle Fehler, Warnungen, defekte Verweise und unvollständige Site-Artefakte automatisiert erkannt.

Schritt-für-Schritt: Ein verbindliches Qualitätsgate definieren

1. Erlaubte und nicht erlaubte Logschweregrade für den Build festlegen.
2. Fehlende xrefs, Includes, Bilder und Navigationseinträge als Pipelinefehler behandeln.
3. Ausgabe auf erwartete Startseiten, Assets, Suchindex und verbotene Dateien prüfen.
4. HTML- und Metadatenprüfungen mit eindeutigem Fehlerbericht ergänzen.
5. Ausnahmen zeitlich begrenzen und mit verantwortlicher Stelle dokumentieren.
6. Gate sowohl bei Merge Requests als auch vor Produktionsdeployment ausführen.

Praxisaufgabe

Ein Satz absichtlich fehlerhafter Inhalte wird durch das Gate abgewiesen und nach Korrektur freigegeben.

5. Private Quellen und Zugangsdaten

Der Build benötigt häufig Zugriff auf mehrere private Repositories, ohne Schlüssel oder Tokens in Logs, Images oder Artefakten zu hinterlassen.

Schritt-für-Schritt: Quellzugriff sicher konfigurieren

1. Benötigte Repository-Berechtigungen nach minimalem Leserecht bestimmen.
2. Kurzlebige Tokens oder dedizierte technische Identität gegenüber persönlichen Zugangsdaten bevorzugen.
3. Geheimnisse ausschließlich über geschützte Pipeline-Mechanismen bereitstellen.
4. Git-Konfiguration und URL-Umschreibung so setzen, dass Logs keine Zugangsdaten enthalten.
5. Zugriff auf erlaubte Hosts und Repositories begrenzen und Fehler ohne Geheimniswert protokollieren.
6. Rotation, Widerruf und Notfallabschaltung in einem Testfall durchspielen.

Praxisaufgabe

Die Pipeline erhält Zugriff auf mehrere private Quellen; anschließend wird ein kompromittiertes Token kontrolliert rotiert.

6. Vorschau und Freigabefluss

Kurzlebige Vorschauen erlauben fachliche Prüfung, bevor Inhalte in die produktive Site gelangen.

Schritt-für-Schritt: Eine Preview-Umgebung automatisieren

1. Auslöser und Lebenszyklus für Merge-Request- oder Branch-Vorschauen definieren.
2. Eindeutigen, kollisionsfreien Zielpfad je Vorschau erzeugen.
3. Robots- und Zugriffsschutz für nicht freigegebene Vorschauen berücksichtigen.
4. Buildstatus, Vorschauadresse und relevante Warnungen an den Review-Vorgang zurückmelden.
5. Vorschau nach Merge, Schließen oder Ablauf automatisch entfernen.
6. Unterschiede zwischen Vorschau- und Produktionskonfiguration minimieren und dokumentieren.

Praxisaufgabe

Eine kurzlebige Vorschau wird erzeugt, aktualisiert und nach Abschluss des Review-Vorgangs automatisiert bereinigt.

7. Produktionsdeployment und Rollback

Die Veröffentlichung wird als kontrollierte Übergabe eines unveränderten, geprüften Artefakts umgesetzt.

Schritt-für-Schritt: Eine atomare Veröffentlichung implementieren

1. Zielsystem und unveränderliches Site-Artefakt eindeutig identifizieren.
2. Upload in einen neuen Versionspfad durchführen und Prüfsummen kontrollieren.
3. Smoke-Tests gegen die neue, noch nicht aktive Version ausführen.
4. Aktive Version durch atomare Umschaltung oder gleichwertigen Mechanismus wechseln.
5. Vorherige Version für definierten Zeitraum verfügbar halten.
6. Rollback auslösen, testen und als regulären Pipelinepfad dokumentieren.

Praxisaufgabe

Ein Produktionsdeployment mit absichtlich fehlerhaftem Smoke-Test wird gestoppt; anschließend wird ein Rollback geprobt.

8. Beobachtbarkeit und Betriebsübergabe

Pipeline und Veröffentlichung benötigen messbare Laufzeiten, eindeutige Fehlerdaten und klare Zuständigkeiten.

Schritt-für-Schritt: Die Automatisierung betriebsfähig machen

1. Builddauer, Erfolgsrate, Warnungszahl, Artefaktgröße und Deploymentdauer als Kennzahlen definieren.
2. Logs mit Build-ID, Commit, Quellenständen und Pipeline-Stufe korrelierbar machen.
3. Alarme für wiederholte Ausfälle, starke Laufzeitabweichungen und fehlende Veröffentlichungen festlegen.
4. Runbooks für Quellzugriff, Cachefehler, Buildabbruch und Rollback erstellen.
5. Betriebs- und Entwicklungszuständigkeiten einschließlich Eskalationsweg vereinbaren.
6. Komplette Pipeline in einer simulierten Störung ausführen und Dokumentation korrigieren.

Praxisaufgabe

Das Ergebnis ist eine dokumentierte, messbare und wiederanlaufbare Antora-Pipeline mit geregelter Betriebsübergabe.

Zielgruppe und Voraussetzungen

Zielgruppe: DevOps- und Plattformteams, Build- und Release-Engineering, SRE, technische Dokumentationssysteme und Entwicklerinnen und Entwickler mit Pipeline-Verantwortung.

Voraussetzungen: Antora-Grundkenntnisse, sicherer Umgang mit Git und Kommandozeile sowie Grundlagen einer CI/CD-Plattform und von Container-Images.

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.