Docusaurus
Veröffentlicht die technische Dokumentation eines Mandanten.
Docusaurus ist ein Open-Source-Framework zur Erstellung statischer Dokumentationswebsites mit React und Markdown beziehungsweise MDX. Navigation, Versionierung, Suche und wiederverwendbare UI-Komponenten werden beim Erzeugen der Website mit den redaktionellen Inhalten zu auslieferbaren Webdateien verbunden.
Docusaurus erzeugt keine fachlichen Inhalte. Struktur, Aktualität und Freigabe werden im Dokumentationsrepository gepflegt und beim Erstellen des Container-Images festgelegt.
Docusaurus in der UDSP
Die UDSP kann für einen Mandanten eine eigene Dokumentationswebsite oder eine gemeinsam genutzte Instanz ausrollen. Das Deployment veröffentlicht ein bereits gebautes Dokumentationsimage unter der konfigurierten Domain und bindet den Zugang bei Bedarf an Keycloak und APISIX an.
Inhaltliche Änderungen erfolgen nicht innerhalb des Plattform-Inventorys. Sie werden im jeweiligen Dokumentationsprojekt versioniert, als neues Image freigegeben und anschließend über die UDSP aktualisiert. Die gemeinsame technische Basis der aktuellen UDSP-Dokumentationen verwendet Docusaurus 3.10.2.
Technische Abhängigkeiten
Die ausgelieferte Dokumentationswebsite ist statisch. Der Plattformzugang wird abhängig vom gewählten Veröffentlichungsmodus durch APISIX und optional Keycloak ergänzt.
APISIX
Veröffentlicht die Dokumentationsdomain und unterscheidet öffentlichen vom geschützten Zugriff.
Komponente öffnen
Keycloak
Schützt eine nicht öffentliche Dokumentationsinstanz über den dafür erzeugten Client.
Komponente öffnenKonfiguration und Deployment
Das Inventory bestimmt Domain, Registry-Pfad, Image-Tag, Registry-Zugang, gemeinsame oder mandantenspezifische Bereitstellung und öffentliche Sichtbarkeit. Die Docusaurus-Version bezeichnet dabei das Framework, mit dem die Website gebaut wird. Branch beziehungsweise Image-Tag bezeichnen dagegen den konkreten Stand der Inhalte und ihrer UDSP-spezifischen Gestaltung.
Das Default-Inventory verwendet derzeit den veränderlichen Container-Tag latest. Für reproduzierbare Umgebungen sollte deshalb ein unveränderlicher Release-Tag oder Image-Digest eingetragen werden. Alle Felder sind unter Mandanten konfigurieren: Docusaurus beschrieben.
Rollen und Rechte
Docusaurus besitzt in der UDSP keine eigenen fachlichen Benutzerrollen. Die Veröffentlichung kennt zwei klar getrennte Zugriffsmodi:
Öffentlich
Mit public: true veröffentlicht APISIX die Dokumentation ohne vorgeschaltete Anmeldung.
Authentifiziert
Mit public: false schützt ein Keycloak-Client den Zugang; eine erfolgreiche Anmeldung erlaubt das Lesen der gesamten ausgelieferten Website.
Eine feinere Berechtigung einzelner Seiten oder Kapitel wird vom aktuellen Docusaurus-Deployment nicht erzeugt. Unterschiedlich geschützte Inhalte müssen deshalb getrennt gebaut und veröffentlicht werden.