Seminar Docusaurus – CI/CD und Deployment

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Auslieferungsmodell und Pfadkonfiguration klären
3. Schritt 2: Reproduzierbare Abhängigkeiten sicherstellen
4. Schritt 3: CI-Prüfkette aufbauen
5. Schritt 4: Vorschauumgebungen für Änderungen erzeugen
6. Schritt 5: Deployment als unveränderliches Artefakt gestalten
7. Schritt 6: Konfiguration und Geheimnisse trennen
8. Schritt 7: Freigabe, Rollback und Wiederanlauf definieren
9. Schritt 8: Betrieb und Überwachung integrieren
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar baut eine reproduzierbare Lieferkette vom Quellrepository bis zum statischen Produktionsartefakt auf. Behandelt werden Build-Konfiguration, Qualitätsgates, Vorschauumgebungen, Deployment-Modelle, Konfigurationsmanagement, Rollback und Betrieb.

• Docusaurus-Builds reproduzierbar und umgebungsneutral erzeugen
• Prüfungen und Vorschauen in einen nachvollziehbaren CI/CD-Prozess integrieren
• statische Artefakte sicher auf unterschiedliche Zielplattformen ausliefern
• Rollback, Monitoring und Betriebsdokumentation für regelmäßige Veröffentlichungen etablieren

Seminarinhalte

Schritt 1: Auslieferungsmodell und Pfadkonfiguration klären

Zuerst werden Ziel-Domain, Unterpfad, Routing, Slash-Konvention und Artefaktstruktur festgelegt. Die Konfiguration von URL und Basis-Pfad wird so geprüft, dass lokale Vorschau und Produktion dasselbe Routingmodell verwenden.

• Zielpfad und Hosting-Modell dokumentieren
• URL-, Basis-Pfad- und Slash-Regeln festlegen
• statische Assets und absolute Pfade kontrollieren

Schritt 2: Reproduzierbare Abhängigkeiten sicherstellen

Paketmanager, Lockdatei, Laufzeitversion und Installationsmodus werden verbindlich festgelegt. Alle Docusaurus-Pakete erhalten kompatible Versionsstände und der Build startet aus einer sauberen Umgebung.

• Laufzeit- und Paketmanager-Version festschreiben
• deterministische Installation in CI verwenden
• Abhängigkeitsabweichungen frühzeitig erkennen

Schritt 3: CI-Prüfkette aufbauen

Die Pipeline trennt schnelle Inhaltsprüfungen, statische Analysen und den vollständigen Produktions-Build. Fehler werden mit verständlichen Logs und eindeutigen Abbruchregeln zurückgemeldet.

• Markdown-, MDX- und Konfigurationsprüfung ausführen
• Links, Assets und doppelte Routen validieren
• Produktions-Build als verbindliches Gate etablieren

Schritt 4: Vorschauumgebungen für Änderungen erzeugen

Jeder relevante Änderungsantrag erhält eine isolierte Vorschau mit identifizierbarem Stand. Vorschauen werden zeitlich begrenzt, dürfen keine Produktionsgeheimnisse enthalten und bilden die spätere Pfadkonfiguration realistisch ab.

• Preview-Auslöser und Gültigkeitsdauer definieren
• Status und Artefaktversion sichtbar machen
• Zugriff und Datenklassifikation für Vorschauen regeln

Schritt 5: Deployment als unveränderliches Artefakt gestalten

Das geprüfte Build-Verzeichnis wird als versioniertes Artefakt veröffentlicht, ohne im Deployment erneut Inhalte zu generieren. Dadurch bleiben Freigabestand, Prüfergebnis und ausgelieferte Dateien identisch.

• Artefakt paketieren und mit Build-Metadaten versehen
• Upload und Aktivierung voneinander trennen
• Cache-Invalidierung und atomare Umschaltung planen

Schritt 6: Konfiguration und Geheimnisse trennen

Öffentliche Build-Parameter, Umgebungswerte und echte Geheimnisse werden unterschiedlich behandelt. Browserseitig ausgelieferte Werte werden grundsätzlich als öffentlich betrachtet.

• Build- und Laufzeitparameter inventarisieren
• Geheimnisse nur in geschützten Pipeline-Schritten verwenden
• Drittanbieterkennungen und Einwilligungsanforderungen prüfen

Schritt 7: Freigabe, Rollback und Wiederanlauf definieren

Veröffentlichungen erhalten nachvollziehbare Versionen, Freigabepunkte und Rückfalloptionen. Ein Rollback aktiviert ein bereits geprüftes Artefakt statt einen ungeprüften Neubau auszuführen.

• Release-Kandidaten und Freigabeprotokoll festlegen
• vorheriges Artefakt schnell reaktivierbar halten
• Wiederanlauf nach Teilfehlern dokumentieren

Schritt 8: Betrieb und Überwachung integrieren

Nach dem Deployment werden Erreichbarkeit, zentrale Routen, Assets und Suchfunktion kontrolliert. Ein Betriebsleitfaden verbindet technische Alarme mit klaren Diagnose- und Eskalationsschritten.

• Smoke-Tests nach der Aktivierung ausführen
• Build- und Deployment-Kennzahlen erfassen
• Runbook für 404-Fehler, Asset-Probleme und Fehlkonfiguration erstellen

Praxisphasen

Die einzelnen Arbeitsschritte werden an einer durchgängigen Übungsplattform umgesetzt. Konfigurationen, Inhalte und Prüfungen werden schrittweise erweitert und jeweils mit einem produktionsnahen Build kontrolliert.

• Entwurf einer vollständigen Pipeline mit Installation, Prüfungen, Build, Artefakt und Deployment
• Konfiguration einer Vorschau für Änderungsanträge mit produktionsnahem Basis-Pfad
• Durchspielen eines fehlerhaften Releases einschließlich Diagnose und Rollback

Zielgruppe und Voraussetzungen

Zielgruppe: DevOps-Teams, Build- und Release-Verantwortliche, Docusaurus-Administratoren, Entwickler und technische Plattformteams

Voraussetzungen: Docusaurus-Grundkenntnisse, sicherer Umgang mit Git und grundlegende Erfahrung mit CI/CD-Systemen und statischem Hosting