Bereits mit den Anfängen der Firma HashiCorp, so die Erzählung der beiden Gründer Mitchell Hashimoto und Armon Dadgar, legten Mitarbeiter zahlreiche Dokumente an, um Ideen, Prozesse, Verfahren, Konzepte und Dokumentation, aber auch einfach Gesprächsinhalte und Gedanken festzuhalten. Das schriftliche Niederlegen sei damit elementarer Bestandteil der Unternehmenskultur. Um die Qualität der erzeugten Schriftstücke zu verbessern und für die Zukunft sicherzustellen, wurde ein entsprechendes Tool gesucht, mit dem sich der gesamte Workflow eines Dokuments abbilden ließ und mit dem mehrere Mitarbeiter zeitgleich am selben Text arbeiten konnten.

Offenbar fand das Unternehmen keine zufriedenstellende Lösung, denn ein Team mit dem Namen "HashiCorp Labs" entwickelt seit einiger Zeit eine eigene – Hermes [1]. Ende Januar wurde der erste Wurf dann als Open Source über GitHub öffentlich zugänglich gemacht – ein offiziell von HashiCorp vermarktetes Produkt ist Hermes damit nicht. Das Repository stellt den in Golang und TypeScript/Javascript geschriebenen Quellcode bereit. Der ist zwar nur eine Alpha-Version, das Tool aber einmal auszuprobieren, kann durchaus lohnen. Denn der Ansatz ist vielversprechend, um Bewegung in den eingeschlafenen Dokumentationswillen der Belegschaft zu bringen.

Hermes ist sehr fokussiert auf das eigentliche Anwendungsszenario innerhalb von HashiCorp zugeschnitten. Die eigentliche Codebase ist eher überschaubar, weil das Tool im Hintergrund sehr intensiv auf die Funktionen von Google Workspace [2] beziehungsweise die darunter liegende Google-Cloud zugreift. Für einen Test von Hermes ist es daher praktisch, wenn Sie in Ihrem Unternehmen bereits Google Workspace verwenden.

Aber selbst dann, wenn Sie bisher keine Erfahrung mit den Diensten gesammelt haben, können Sie Hermes ausprobieren und mit einem Testkonto bei Google 14 Tage kostenfrei nutzen. Wir gehen im Folgenden davon aus, dass Sie bisher keinen Account für Google Workspace haben.

Registrieren Sie also ein neues Workspace-Konto und geben Sie die entsprechenden Informationen ein. Den Namen des Unternehmens können Sie leer lassen, die Anzahl der Konten und die Region müssen Sie jedoch festlegen. Im zweiten Schritt tippen Sie Ihren Namen und eine gültige E-Mail-Adresse für den Administrationsbenutzer an. Nun werden Sie nach einer Domain gefragt, die Sie für die Registrierung verwenden möchten. Tatsächlich benötigen Sie hier eine Domain, bei der Sie für den späteren Schritt zur Verifizierung Einstellungen im DNS ändern können. Google stellt Ihnen nämlich einen TXT-Record zur Verfügung, den Sie dauerhaft im DNS hinterlegen und mit dem Sie die Webseiten-Inhaberschaft bestätigen.

Klicken Sie die nächsten Dialoge durch, lehnen Sie auf Wunsch die Werbeanfragen ab und vergeben Sie dann einen Benutzernamen und ein Passwort für Google Workspace. Anschließend wählen Sie den Tarif des Benutzers aus, bestenfalls ergänzt mit einem Kalendereintrag, um rechtzeitig vor Ablauf des Testzeitraums zu kündigen. Ergänzen Sie im nächsten Schritt die Details zu Ihrem Unternehmen und hinterlegen Sie gültige Zahlungsdaten.

Im Webinterface für Googles Cloud legen Sie nun ein neues Projekt für Hermes an. Wählen Sie einen ansprechenden Namen und gehen Sie dann in den Einstellungen auf den Punkt "APIs und Dienste". Dort klicken Sie auf "+APIs und Dienste aktivieren". Suchen Sie die folgenden drei APIs und aktivieren Sie sie:

- Google Docs API

- Google Drive AP

- People API

Die Docs- und Drive-API benötigen Sie zum kooperativen Bearbeiten und Speichern der Dokumente in Hermes. Über die People-API wählen Sie vor allem Mitarbeiter und Reviewer aus. Damit das möglich ist, müssen Sie noch die Freigabeeinstellungen "Verzeichniseinstellungen" Ihrer zu Beginn angelegten Organisation ändern. Diese müssen nämlich externe Zugriffe über die API erlauben (Bild 1). Wenn Sie auch E-Mails über Google versenden möchten, aktivieren Sie zusätzlich noch die Gmail-API. Hermes kann dann Benutzer informieren, wenn diesen Aufgaben oder Dokumente zugewiesen wurden.

Während Sie unter "APIs und Dienste" die Einstellungen konfigurieren, passen Sie auch gleich unter "OAuth-Zustimmungsbildschirm" die Anwendungsinformationen für die Anmeldung an. Geben Sie dafür die URL der Startseite von Hermes an und legen Sie die autorisierte Domain fest. Wenn Sie Hermes nur lokal verwenden, müssen Sie hier neben Ihrer genutzten Domain zusätzlich den localhost hinterlegen.

Im nächsten Schritt bestimmen Sie die Geltungsbereiche (Scopes) der Anwendung. Wählen Sie unter "Vertrauliche Bereiche" die URL für die Google-Docs-API "https://www.googleapis.com/ auth/drive.readonly" entweder aus der Liste aus oder geben Sie diese als manuellen Bereich im Textfeld an. Speichern Sie anschließend die Anwendung und kehren Sie zurück zur Übersicht.

Bleiben Sie bei "APIs und Dienste" und generieren Sie im nächsten Schritt OAuth-Client-Credentials für die Hermes-Webanwendung und das Backend unter dem Menüpunkt "Anmeldedaten". Klicken Sie dafür auf "+Anmeldedaten erstellen" und wählen Sie "OAuth-Client-ID".

Markieren Sie im ersten Schritt "Webanwendung" als Typ und vergeben Sie einen sprechenden Namen. Tippen Sie unter "Autorisierte JavaScript-Quellen" die URL Ihrer Instanz ein oder "http:// localhost: 8000", wenn Sie Hermes ausschließlich lokal betreiben.

Die unter "Autorisierte Weiterleitungs-URIs" anzugebende Adresse lautete für unsere Workshop-Domain "https://hermes.it-administrator.de/torii/redirect.html". Passen Sie diese für Ihre Installation entsprechend an und denken Sie an die Portangabe ":8000", wenn Sie localhost verwenden. Die wie in Bild 2 im Bestätigungsdialog angezeigten Credentials können Sie zunächst im JSON-Format speichern. Sie benötigen diese, wenn Sie Hermes kompilieren.

Das Erstellen der Anmeldeinformationen für das Backend gestaltet sich deutlich einfacher. Wählen Sie hier statt "Webanwendung" nun "Desktopanwendung" und geben Sie einen passenden Namen an. Speichern Sie die Informationen aus dem Bestätigungsdialog im Projektverzeichnis als "credentials.json". Damit haben Sie im Google-Backend alles Notwendige konfiguriert und können mit Algolia weiter machen.

Bei Algolia [3] handelt es sich um einen Dienst für die Indexierung und die Suche in Webanwendungen. Auch Hermes nutzt ihn für die Volltextsuche. Daher benötigen Sie einen kostenfreien Algolia-Account, den Sie zunächst anlegen müssen. Nachdem Sie sich eingeloggt haben, sehen Sie im Menü unter "Settings / Team and Access" die API-Keys Ihres Accounts ein. Notieren Sie den API-Key für "Admin" und "Search-Only" für die spätere Konfiguration. Ist noch kein API-Key hinterlegt, erzeugen Sie mit einem Klick auf "Regenerate" einen neuen.

Nachdem nun alle Vorbereitungen getroffen sind, können wir uns endlich Hermes selbst zuwenden. Klonen Sie erst einmal das Git-Repository, falls Sie dies nicht bereits getan haben, wechseln Sie in den Ordner und kopieren Sie die "credential.json" mit den Google-OAuth-Credentials der Desktopanwendung hinein.

Vor dem Kompilieren kopieren Sie außerdem die Hermes-Konfiguration und erstellen die Umgebungsvariable für die OAuth-Client-ID mit folgenden Befehlen:

Prüfen Sie zunächst die installierte Version von node.js und Yarn. Von node.js sollten Sie mindestens Version 16.17 über den Paketmanager Ihrer Distribution installieren. Dann können Sie Yarn einfach mit corepack und folgendem Kommando installieren beziehungsweise aktualisieren:

Nun ist die Build-Umgebung vorbereitet, sodass Sie das Kompilieren mit make build starten können. Nach einiger Zeit sollten Sie die Erfolgsmeldung in Ihrer Konsole sehen. Hermes ist nun fertig, eine klassische Installationsroutine benötigt es nicht. Zum Start braucht Hermes noch eine Postgres-Datenbank. Diese ist in einem Docker-Container geplant und lässt sich ebenfalls über das Makefile in Betrieb nehmen. Daher müssen Sie die Datenbank selbst nicht einrichten oder konfigurieren. Starten Sie die Datenbank einfach mit dem folgenden Kommando:

Erhalten Sie eine Fehlermeldung, dass "docker-compose" nicht gefunden werden kann, verfügen Sie bereits über eine aktuelle Docker-Version mit integriertem Compose. Entweder legen Sie in der Shell-Umgebung einen Alias an oder Sie editieren das Makefile und entfernen an drei Stellen den Bindestrich. Anschließend sollte der Aufruf den Docker-Container starten. Bevor Sie nun mit Hermes arbeiten können, müssen Sie allerdings noch dessen Konfiguration anpassen.

Die Konfiguration von Hermes gestaltet sich im Grunde recht einfach, denn die Datei "config.hcl" ist verhältnismäßig kurz. Öffnen Sie diese mit einem Texteditor und gehen von oben nach unten durch. Die "Base URL" müssen Sie nur anpassen, wenn Sie Hermes mit eigener Domain hinter einem Proxy betreiben. Geben Sie nun die "application_id" sowie die beiden API-Keys aus Ihrem Algolia-Konto ein. Die Namen der "Indices" lassen Sie einfach wie voreingestellt.

Zwar sind die Dokumenttypen Teil der Hermes-Konfiguration, zum Zeitpunkt der Konzeption dieses Workshops ließen sich diese aber noch nicht anpassen. Daher überspringen Sie den Bereich der "document_types". Dafür dürfen Sie den Absender der von Hermes versendeten E-Mails an Ihre Gegebenheiten anpassen oder den Versand von E-Mails deaktivieren.

Um den Bereich von Google Workspace zu konfigurieren, müssen Sie zunächst ein Google Drive dafür einrichten. Die Entwickler empfehlen ein bestimmtes Layout, allerdings müssen Sie sich nicht zwingend daran halten. Da sich die Dateien im Google Drive aber auch außerhalb von Hermes teilen lassen, ergibt eine gewisse Struktur der geteilten Ordner Sinn. Melden Sie sich mit Ihrem Organisationskonto bei Drive an und erstellen Sie eine "geteilte Ablage". In unserem Beispiel nennen wir diese einfach "Hermes". In der Ablage legen Sie anschließend die drei Ordner mit den Namen "Documents", "Drafts" und "Shortcuts" an.

Wie Sie der Beispielkonfiguration von Hermes entnehmen können, benötigen Sie beim Hinterlegen der entsprechenden Ordner die ID dieser geteilten Verzeichnisse – die Namen allein reichen für eine Zuordnung nicht aus und führen beim Anlegen neuer Dateien zu 404-Fehlern in der Anwendung. Um die IDs der Ordner zu erhalten, öffnen Sie diese einzeln im Browser, kopieren die ID aus der URL und fügen diese in der Datei "config.hcl" hinzu.

Im Bereich "OAuth2" hinterlegen Sie noch die Client-ID der Webanwendung sowie Ihre genutzte Domain unter "hd". Die "redirect_url" passen Sie an die weiter oben gemachten Angaben beim Generieren der Credentials an. Weitere Optionen müssen Sie in der Konfiguration erst einmal nicht einstellen. Unter "products" können Sie noch weitere Produkte Ihres Unternehmens hinzufügen, für die Sie eine separate Dokumentation erstellen möchten. Für einen ersten Test von Hermes müssen Sie das jedoch nicht. Speichern Sie nun die Datei und starten Sie Hermes mit dem Kommando:

Der Startvorgang dauert ein wenig Sobald Sie den "listening"-Logeintrag auf der Konsole sehen, wird ein Browserfenster zur Auswahl und Freigabe Ihres Administratorkontos für den Zugriff durch Hermes geöffnet. Nachdem Sie Ihr Vertrauen in die Anwendung bestätigt haben, schließen Sie dieses Fenster einfach wieder. Anschließend rufen Sie im Browser die Startseite von Hermes auf. Der Login in die Anwendung ist über Googles OAuth-Funktionalität möglich. Dafür klicken Sie auf den blauen Button "Authenticate with Google" und schon gelangen Sie nach der Wahl Ihres Benutzerkontos in die Dokumentenübersicht von Hermes.

Nach dem ersten Login finden sich erwartungsgemäß noch keine Dateien in der Übersicht von Hermes. Mit einem Klick auf das +-Symbol neben dem Suchfeld gelangen Sie zur Auswahl der Produkttemplates für das neue Dokument (Bild 3). Wir starten auf Basis des Templates "Request for Comments". Da wir in unserem Szenario davon ausgehen, dass wir zunächst die Dokumentation der IT-Abteilung erweitern möchten, passt das erst einmal besser. Wir erzeugen also nun einen Schriftsatz mit dem Titel "Umsetzung des Datenschutzes in der IT-Abteilung". Dieser Titel ist bewusst ohne Umlaute gewählt, da Hermes noch keine unterschiedlichen Sprachen und Zeichensätze unterstützt und Umlaute daher nicht korrekt interpretiert . Englischsprachig sind Sie hier auf der sicheren Seite. Das Gleiche gilt leider für das Summary-Feld. Das Dokument selbst kommt später erfreulicherweise mit Umlauten zurecht.

Als Produkt wählen wir hier erst einmal "Engineering", es sei denn, Sie haben bei der Konfiguration bereits andere passende Produkte angelegt. In der Auswahl "Add contributors" wählen Sie Kollegen aus, die Sie zur Mitarbeit einladen möchten. Hier sollten Sie mindestens sich selbst selektieren können, wenn Sie die People-API wie geschildert übernommen haben. Mit einem Klick auf "Create RFC in Google Drive" erstellen Sie das Dokument, was einen Moment dauern kann, und die Ansicht von Hermes schaltet zur Bearbeitung zu Google Docs. Den Hinweis über Erwähnungen und Benachrichtigungen können Sie zur Kenntnis nehmen und zukünftige Anzeigen unterbinden, indem Sie den Haken bei "Don't show this again" auswählen.

Hermes erzeugt nun ein dem Template angepasstes Dokument und erstellt einen Header entsprechend dem gewählten Dokumenttyp. Wundern Sie sich nicht über die in der Bezeichnung angegebenen drei Fragezeichen, hier erscheint im weiteren Verlauf automatisch eine laufende Nummer. Bei "Status" erkennen Sie den geplanten Workflow von Hermes – das Schriftstück ist zur Zeit als "WIP" (work in progress) markiert, was der Entwurfsphase entspricht. Legen Sie nun Ihre Dokumentation an. Die Bearbeitung erfolgt so, wie Sie das von Google Docs oder anderen Programmen zur Textverarbeitung kennen. Die Arbeit lässt sich jederzeit unterbrechen, indem Sie das Fenster schließen oder im linken Bereich auf "Back to Dashboard" klicken. Ihren Entwurf finden Sie oben im Menü unter "My Drafts". Bei einer größeren Menge an Dokumenten sortieren Sie diese für mehr Übersicht nach Typ, Status, Produkt oder Zeitpunkt der Erstellung.

Das Dokument lässt sich jederzeit direkt in Google Drive suchen und öffnen, und zwar im zuvor von Ihnen angelegten Drafts-Ordner. Auch das Teilen mit weiteren Nutzern ist eine Option. Hermes kümmert sich eigentlich nur darum, den Header von Zeit zu Zeit neu zu generieren. Diesen sollten Sie also nicht ändern beziehungsweise nicht erwarten, dass Ihre Änderungen dauerhaft sind. Wenn Sie beim nächsten Mal in Hermes weitermachen, merken Sie im Grunde keinen Unterschied bei der kollaborativen Bearbeitung des Entwurfs. Hermes pflegt für Sie automatisch eine Übersicht zu weiteren Autoren.

Haben Sie Ihre erste Dokumentation fertiggestellt, können Sie – nun wieder in Hermes – die Datei einem oder mehreren Ihrer Kollegen zum Review übergeben, indem Sie im linken Bereich unten auf "Request Review" klicken. Im folgenden Dialog wählen Sie die Benutzer für das Review aus und bestätigen dies. Auch dieser Vorgang nimmt etwas Zeit in Anspruch. Das Dokument erhält nun die schon erwähnte laufende Nummer im Kopfbereich und der Status ändert sich auf "In-Review". In Google Drive befindet sich die Datei nun schon nicht mehr im Entwürfe-, sondern im Dokumente-Ordner.

Der Reviewer kann nun die typischen Funktionen von Docs verwenden und etwa Kommentare anfügen oder Änderungen vorschlagen, aber natürlich auch einfach direkt etwas im Schriftsatz ändern. Welchen Modus Sie durch den Reviewer bevorzugen, müssen Sie im Team besprechen und vielleicht in mehreren Durchgängen ausprobieren. Wenn Sie die Kommentare und Änderungen eingearbeitet haben, steht der nächste Schritt an: die Annahme (approval). Leider ist es derzeit nicht möglich, das Dokument noch einmal in den Draft-Status zurückzuversetzen, was bei größeren Änderungen durchaus Sinn ergeben kann.

Mit einem Klick auf "Move to Approved" im linken Bereich finalisieren Sie das Dokument. Leider verbleiben noch existierende Kommentare in der Datei, die eigentlich im Rahmen des Review-Prozesses erledigt sein sollten. Diese müssten Sie also noch entfernen, denn das Dokument sollte ja "fertig" sein. Elemente im Status "Approved" können Sie bei Bedarf wieder zurück in den "In-Review"-Status versetzen. Mit einem Klick auf das Mülleimersymbol lässt sich das Dokument als veraltet ("Obsolete") markieren. Auch hier bekommen Sie es über den Weg des "In-review"-Status wieder in die Bearbeitung.

Hermes befindet sich derzeit im Alpha-Status, ist also formell erst die Vorankündigung einer entwickelten Software. Das bedeutet, dass das Werkzeug weit entfernt ist von einer produktiv einsetzbaren Software und bei weitem nicht "feature-complete" oder fehlerfrei. Während der Verwendung fällt zum Beispiel auf, dass nach kurzer Zeit der Nichtbenutzung immer wieder Timeouts im Hintergrund auftreten. Leider bleibt dann oft nur ein Reload des Browserfensters. Außerdem lassen sich Dokumente, die eigentlich schon "Approved" sind, nicht vor einer weiteren Bearbeitung schützen. Kombiniert mit dem erwähnten Timeout kann es also passieren, dass externe Bearbeiter in Google Docs gar keine Informationen über den Status einer Datei erhalten und diese nach der Finalisierung noch bearbeiten. Insgesamt geht Hermes derzeit nur wenig über die reine Workflow-Abbildung rund um das Erstellen von Dokumenten hinaus.

Die Metadaten eines Schriftsatzes verfügen über Felder wie "Current Version" oder "Target Version". Insbesondere diese Versionen aktualisiert Hermes leider nicht automatisch und dies bleibt manuelle Aufgabe des Benutzers. Ferner ist es (noch) nicht möglich, Dokumente inhaltlich in neuen Versionen weiterzuentwickeln, ohne dabei die ältere Version aufzugeben. In dem durch Hermes erzeugten Header finden Sie auch Angaben wie "Tags". Das Interface von Hermes sieht jedoch aktuell kein Eingabefeld für Tags vor. Möchten Sie Dokumente über Tags auffindbar machen, müssen Sie diese einfach direkt im Text mit angeben. Suchen Sie dann nach den Tags, finden Sie zuverlässig Ihre gelabelten Unterlagen.

HashiCorp hat deshalb für Hermes noch so einiges auf der Roadmap. Unter anderem sollen sich weitere Ressourcen an Dokumente anhängen lassen, etwa Bilder oder Videos. Hermes soll zukünftig ein Empfehlungssystem für Leser auf Basis Ihrer "gelikten" Dateien beinhalten und als Teil des Dashboards darstellen. Den Workflow-Prozess und erweiterte Freigabemöglichkeiten will der Hersteller weiter ausbauen, sodass Entwürfe zunächst innerhalb eines Teams geteilt werden können und erst anschließend im eigentlichen Review-Prozess landen. Neben diesen Meilensteinen dürften sicher auch einige Anregungen aus der Community in zukünftigen Versionen Berücksichtigung finden.

Im Alpha-Status von HashiCorp Hermes ist aktuell hauptsächlich der Workflow bei der Dokumenterstellung abgebildet. Damit können Sie etwa das Erzeugen von Dokumentationen in Ihrem Unternehmen zielgerichtet organisieren. Neben kleineren Limitierungen besteht die größte Einschränkung des Open-Source-Werkzeugs darin, dass derzeit ausschließlich Google Workspace als Backend-Dienst in Frage kommt. Unternehmen, die auf andere Clouddienste setzen, müssten zumindest zum Teil in die Google Cloud migrieren, wenn sie regelmäßig mit Hermes arbeiten möchten. Der Artikel demonstriert Ihnen die dazu notwendigen Vorbereitungen, die Installation und die Benutzung von Hermes.