Page Comparison

Installationsbundle

Es existieren zwei unterschiedliche Installationsbundles. Eines dient der Installation in einer reinen Docker-Umgebung per docker-compose. Das Andere ist zur Installation in einer Umgebung mit Kubernetes gedacht, bspw. Open Shift.

Docker Compose

Unser Installationsbundle für den Kommentierungsserver besteht aus mehreren Dateien:

.env

In dieser Datei werden Umgebungsvariablen festgelegt, die definieren unter welchem SSL-Port die Anwendung laufen soll und wie die Dateien heißen, in denen das (von Ihnen für Ihre Domain bereitgestellte) SSL Zertifikat und der SSL Key liegen.

*_password.txt

In zwei Dateien, die mit “_password.txt” enden, wird festgelegt, welche Passwörter (initial) für die Datenbank und den globalen Administrator-User verwendet werden sollen.

config.properties

Hier werden Einstellungen für unseren Kommentierungsserver festgelegt. Aktuell findet dort die Konfiguration des SMTP Mail-Servers statt, der dazu verwendet wird Benachrichtigungsemails zu versenden, wenn ein Benutzer in einem Kommentar erwähnt wurde.

init-commenting-db.sql

Die Initialisierung des Postgres-Servers mit einer neuen Datenbank und zwei Schemata ist hier definiert. Hier ist vom Benutzer nichts anzupassen.

nginx.conf

In der Konfigurationsdatei befindet sich die Definition, wie der NGINX Reverse Proxy die Anfragen gegen das Kommentierungsbackend an die einzelnen Docker Container weiterleiten soll. Hier ist in der Regel vom Benutzer nichts anzupassen.

docker-compose.yaml

Die Definition welche Container für das Kommentierungsbackend erstellt werden müssen, welche Dateien vom Host-System verwendet werden dürfen und wie das interne Netzwerk aufgebaut ist muss in der Regel nicht angepasst werden.

commenting.war

In dieser Datei liegt die Logik für das Kommentierungsbackend, sie wird automatisch in dem Tomcat-Container in Docker installiert.

Installationsvorgang

1. Installieren Sie Docker wie hier beschrieben: https://docs.docker.com/engine/install/

2. Entpacken Sie das Installationsbundle und die Dateien aus dem Installationsbundle kopieren Sie auf das Docker-Hostsystem an einen beliebigen Ort.

3. Sie fügen Ihr SSL Zertifikat mit dem Dateinamen “ssl_certificate.crt” und den dazugehörigen privaten Schlüssel mit dem Dateinamen “ssl_certificate.pem” an dem selben Ort wie in Schritt 1 ein. Bei unterschiedlichen Pfaden oder Dateinamen, muss die Datei “.env” angepasst werden.

4. Wenn sie einen anderen Port als “3333” für den Server verwenden möchten, so passen Sie die in der Datei “.env” an.

5. In der “commenting_db_password.txt” Datei definieren Sie das Passwört für die Datenbank der Userverwaltung und der Kommentarablage. Dieses wird intern an die entsprechenden Container übermittelt.

6. In der Datei “keycloak_admin_password.txt” definieren Sie das Passwort für den Administrator des Kommentarbackends. Dieser besitzt die Berechtigung Kommentare zu lesen, zu schreiben, zu bearbeiten, zu löschen und neue Benutzer zu definieren. Sie benötigen dessen Passwort also um sich initial in unsere Komponenten und die Verwaltungsoberfläche einzuloggen. Der Benutzername lautet hier “admin”. Neu angelegten Benutzern können dann die Rollen “viewer”, “editor” oder “admin” zugewiesen werden.

7. Ist die Konfiguration vollständig, so können Sie in der Kommandozeile in dem Ordner des Installationsbundles den Befehl “docker-compose up” ausführen. Damit werden alle benötigten Komponenten gestartet.

Kubernetes

Unser Installationsbundle für den Kommentierungsserver auf Kubernetes besteht aus mehreren Dateien:

Im Folgenden gehen wir davon aus, dass Ihnen bekannt ist, wie Dockerfiles und .yml Konfigurationsdateien in Kubernetes zu verwenden sind.

Dockerfile*

In den drei Dockerfiles befinden sich die Anweisungen, wie die drei für die Kommentierung benötigten Container erstellt werden. Die so erstellten Container müssen dann in Ihre docker-registry gepusht werden um sie in Kubernetes zu nutzen.

Ordner comments-keycloak-theme, commenting.jar, nginx.conf, keycloak-docker-entrypoint.sh

Diese Dateien werden von den Dockerfiles verwendet um die einzelnen Container zu erstellen. Eine Modifikation ist hier in der Regel nicht notwendig.

*-kubernetes-*.yml

In den fünf YAML-Dateien befinden sich die Konfigurationen für Kubernetes um unseren Service starten zu können. Diese dienen als Orientierung und es können je nach Ihrer Kubernetes-Konfiguration Anpassungen nötig sein. In der 0-kubernetes-ns.yml ist der Namespace definiert, in dem die graphomate comments Entitäten in Kubernetes erstellt werden. Die 1-kubernetes-role.yml definiert die Rollen die notwendig sind, damit die graphomate services die Konfigurationen lesen dürfen. Die Datei 2-kubernetes-config.yml definiert unterschiedliche Konfigurationsparameter für den unseren Service. Dazu gehören die Verbindungsdaten für die Datenbanken in denen die Kommentare und die Benutzer gespeichert werden. Diese können auch in der selben Datenbank gespeichert werden. Dafür sind in PostgreSQL zwei Schemata notwendig. Bisher konnten wir auch erfolgreich MSSQL auf Azure ohne Schemata testen. Die Konfiguration dafür ist in etwas komplexer als die für PostgreSQL und kann bei Bedarf durch uns erklärt werden. Auch die Definition für den Mailserver werden hier getätigt. Dieser wird verwendet um einem Benutzer der in einem Kommentar erwähnt wurde darüber per Mail zu benachrichtigen. In der 3-kubernetes-secrets.yml werden Zugangsdaten für die Datenbanken, den Mailserver und den initialen Administrator gepflegt. Diese sind wie für Kubernetes üblich Base64 encodiert. In 4-kubernetes-deployment.yml werden die drei für unseren Service benötigten Container Konfiguriert. Diese sind in unserem Bespiel alle in einem Pod vereint und verwenden temporäre in-memory Volumes. Es steht ihnen natürlich frei, andere, bespielsweise persistente, Volumes zu verwenden und die Container für besseres Load-Balancing in unterschiedlichen Pods zu verteilen. Dafür ist allerdings im Fall von dem keycloak-Container eine relative komplexe Konfiguration und eine Anpassung der nginx.conf für den Nginx-Container notwendig, auf die wir in diesem Rahmen nicht eingehen wollen.

Installationsvorgang

Die drei Docker-Container müssen mit den von uns ausgelieferten Dockerfiles erstellt und in Ihre von kubernetes verwendete Docker-Registry gepusht werden. Nachdem die Konfigurationsparameter und Secrets angepasst wurden sollten diese in Kubernetes angewendet werden. Außer der erstellung einer Datenbank und der Schematas übernimmt unser Service die restliche Konfiguration der Datenbank selbst, sobald der Service das erste Mal gestartet wird. Vor den Port 80 des Nginx-Containers sollten Sie bspw. einen Ingress-Controller setzen, der die SSL Terminierung übernimmt und den Port nach außen mit SSL gesichert exponiert. Weitere Port auf unseren Service sind nicht notwending, da der Nginx-Container hier als Reverse-Proxy fungiert. Wenn Sie den Service erfolgreich installiert haben, können Sie drei Dinge tun um dessen Funktionsfähigkeit zu überprüfen. An der Root-URL auf den Service, sollten ein JSON mit Informationen zu dem Service und der installierten Version erscheinen. <Server URL>/auth sollte die Bedienoberfläche von Keycloak öffnen, in der Sie sich mit den Daten des initialen Admin-Benutzers einloggen können, wenn Sie auf “Administration Console” klicken. Hier können Sie auch andere Ident-Provider an unseren Service anbinden. Bswp. sind hier Active Directory per SAML und externe OAuth Provider zu nennen. Für weitere Informationen hierzu konsultieren Sie bitte die Dokumentation von Keycloak. Als letztes überprüfen Sie bitte, ob unter <Server URL>/commenting/administration/ unsere Bedienoberfläche für das Backend erscheint. Hier können Sie, mit einem gültigen Benutzer (bspw. wieder der Admin), bestehende Kommentare einsehen, diese bearbeiten und auch neue erstellen. Gleichzeitig haben Sie die Möglichkeit neue Benutzer zu erstellen und diesen eine von drei Rollen zuzuweisen. Die Rolle “Viewer” kann Kommentare nur anzeigen, “Editor” kann diese erstellen + bearbeiten und “Admin” kann zusätzlich noch User erstellen und ändern.

Active Directory Benutzer

Um Benutzer an unser comments backend anzubinden, die über Microsoft Active Directory verwaltet werden, ist die Nutzung von Active Directory Federation Services (AD FS) und SAML v2.0 notwendig. Haben Sie bereits AD FS auf Ihrem Server eingerichtet, so folgen Sie bitte folgender Anleitung, um ihr AD an die comments anzubinden: https://www.alphabold.com/ms-adfs-configuration-in-keycloak/

Die dafür zu notwendige Verwaltung von Keycloak erreichen sie unter: https://<SERVER_URL>/auth

Der unter “SETUP IDENTITY PROVIDER IN KEYCLOAK” zu findende Schritt 6 ist optional und bietet in unserem Fall die Möglichkeit bestehende Attribute in SAML auf die drei in den comments definierten Rollen zu mappen. Im letzten Feld sollte in unserem Fall dann eben statt “manager” entweder “viewer”, “editor” oder “admin” stehen.

Wenn Sie ansonsten der Anleitung gefolgt sind, so gibt es beim Login in die comments nun eine weitere Option:

Image Added

Wenn Sie nun die untere Option auswählen, so können Sie sich (falls Sie nicht bereits eingeloggt sind) mit einem Benutzer aus dem Active Directory einloggen. Beim ersten Login fragt ein Formular den Vornamen und Nachnamen des zu importierenden Nutzers ab. Um dies zu verhindern sind weitere Mapper notwendig. Die dafür benötigte Konfiguration in der AD FS Konsole sieht wie folgt aus:

Image Added

In Keycloak müssen dem SAML Identity Provider noch zwei weitere Mapper hinzugefügt werden:

Image Added

Image Added

Nach dieser Konfiguration ist nun nach Login eines Active Directory Nutzers keine weitere Dateneingabe nötig.

Begriffserklärung

Docker

Docker ist ein Open-Source Projekt, das dazu dient Software in einer isolierten Umgebung - einem sogenannten Container - auszuführen. Das heißt, Software die innerhalb von einem Container ausgeführt wird teilt sich die Basisfunktionalität des eigentlichen Betriebssystemes, ist aber ansonsten was das Dateisystem und den Arbeitsspeicher angeht von dem restlichen Betriebssystem und anderen Containern isoliert. Das bietet den Vorteil, dass Software die innerhalb eines Docker-Containers ausgeführt wird, immer in einer fest definierten Umgebung mit fest definierten und installierten Abhängigkeiten ausgeführt wird.

Der Docker-Host, der notwendig ist um Docker-Container auszuführen, kann auf jedem beliebigen Linux, Windows oder Mac OSX Server installiert werden. Da jedoch immer eine Linux “Zwischenschicht” notwendig ist, ist ein Linux Server zu empfehlen. Weitere Informationen zur Installation von Docker find Sie hier: https://docs.docker.com/engine/install/

Docker Container

Docker bietet eine Vielzahl von vordefinierten Containern für bestimmte Anwendungszwecke. Diese Container werden oft von den Entwicklern einer Software selbst gepflegt. Beispielsweise gibt es einen offizielles Container-Abbild von Postgres, in dem die gleichnamige Datenbank ausgeführt wird. Um einen Docker Container zu konfigurieren exponiert dieser ein vordefiniertes Set von Einstellungen, die von außen an den Container weitergegeben werden können.

Docker Compose

Mit der Beschreibungssprache “Docker Compose” kann konfiguriert werden, wie eine Anwendung, die aus mehreren Docker Containern besteht, aufgebaut ist. Hier ist beispielsweise definiert, welche Container inkl. ihrer Konfiguration für die gesamte Anwendung ausgeführt werden müssen, wie die Container miteinander in einem virtuellen Netzwerk kommunizieren, welche Dateien vom Host-System im Container zur Verfügung stehen sollen und welche Passwörter verwendet werden sollen.

Datenbankstruktur Kommentare

comment

• id: UUID;

• createdAt: Timestamp;

• changedAt: Timestamp;

• createdBy: string;

• lastModifiedBy: string;

• text: Lob;

• dashboardId: string;

• dashboardName: string;

• hostId: string;

• hostName: string;

• contexts: Foreign Key Context[];

context

• id: UUID;

• createdAt: Timestamp;

• changedAt: Timestamp;

• createdBy: string;

• lastModifiedBy: string;

• type: “DataContext” | “EnvironmentContext”;

• key: string;

• value: string;

• keyText: string <optional for type DataContext>;

• valueText: string <optional for type DataContext>;

Beispiel Tabellenzeilen

comments

contexts