Setup der B2B-UI in Docker

Die B2B-UI wird auch B2B-Functional-UI genannt.

Funktionalität

Die UI enthält:

  • Dashboard mit News & Statistiken
  • MessageMonitor
  • Arbeitsvorräte
  • MpidEditor
  • Systemweiche
  • Manueller Versand

Architektur

Die UI kommuniziert mit einer B2B im Tomcat.

Sowohl UI als auch Tomcat müssen über Keycloak abgesichert sein. Im Rahmen dieser Doku wird beschrieben, wie ein entsprechender Tomcat im Docker ausgeführt werden kann.

Die folgende Abbildung skizziert die Zusammenhänge der einzelnen Komponenten des Setups:

Übersicht der einzelnen Module/Komponenten

Remote-B2B

Als “Remote-B2B” wird das System/Server bezeichnet in dem die bestehende B2B betrieben wird.

Remote-B2B-Datenbank

Als “Remote-B2B-Datenbank” wird das System/Server bezeichnet in dem die Datenbank der Remote-B2B betrieben wird.

keycloak

Unser Docker-Container “keycloak” stellt eine entsprechende Instanz zur Verfügung, die für die Authentifizierung der Nutzer über die B2B-New-UI gegen das B2B-Backend zuständig ist. Diese Keycloak-Instanz wird innerhalb des Dockers betrieben und speichert die Daten (Rollen und Nutzer) in einer eigenen Datenbank. In diesem Setup wird als Datenbank die standardmäßig integrierte H2-Datenbank genutzt. Über ein docker mount wird die Datenbank in das Dateisystem des Docker-Host gemountet, sodass die Daten auch nach dem Löschen des Keycloak-Containers zur Verfügung stehen.

Für einen produktiven Keycloak Einsatz empfehlen wir statt der integrierten H2 Datenbank eine DB analog zur Remote-B2B-Datenbank zu nutzen, also z.B. Postgres oder Oracle.

Für einen produktiven Keycloak Einsatz in einer öffentlichen Umgebung empfehlen wir dringend den Einsatz von HTTPS.

b2bui

Dieser Docker-Container stellt die eigentliche B2B-New-UI-Instanz bereit. Dies läuft in einem nginx Webserver.

b2b

Der Docker-Container der B2B ist prinzipiell nicht zwingend notwendig, wird in diesem Setup aber vorgesehen, da die B2B-Instanz mit der die B2B-New-UI kommuniziert, ebenfalls an keycloak angebunden sein muss. Damit die bestehende B2B (Remote-B2B), nicht für die Anbindung an Keycloak umkonfiguriert werden muss, wurde sich für eine separate B2B-Instanz in einem Docker-Container entschieden.

Übergangsweise ist ein Mischbetrieb denkbar, bei dem insbesondere die Knoten, die vom Frontend angesprochen werden, auf Keycloak umgestellt werden, während gerade die für Backendprozesse relevanten Knoten zunächst weiterhin über BasicAuth angesprochen werden.

B2B Vorinstallation

Voraussetzung dieser Dokumentation ist, dass Sie bereits mind. einen B2B Knoten samt Datenbank eingerichtet haben. Dieser Knoten wurde im vorherigen Abschnitt Remote B2B genannt, die Datenbank wurde Remote-B2B-Datenbank genannt.

Voraussetzungen

  • Docker einsatzbereit
  • Keycloak installiert
  • Remote B2B-Datenbank installiert

Installation

Anpassungen der bestehenden B2B-Instanz

Um einen reibungslosen Start der B2B-Instanz im Docker sicherzustellen, müssen noch die folgenden Anpassungen an der bestehenden B2B-Instanz vorgenommen werden.

Anpassungen der Remote-B2B-Datenbank

In dem Schema der bestehenden B2B-DB-Instanz müssen die hier aufgeführten Datenbankanpassungen durchgeführt werden.

Anpassungen des Customizings

Anpassen einer GlobalProperty für die ClusterCommunication

Wie für die B2B üblich muss einem neuen Knoten eine Knotennummer in den GlobalProperties zugewiesen werden. Danach muss der Knoten neugestartet werden.

In der DB-Tabelle B2BBP_ADM_GLOBAL_PROPERTY muss der PROPERTYKY=b2b-tomcatusrlocaltomcatwebappsb2bbp-engine eingefügt werden. Der Wert des Feldes PROPERTYKEY setzt sich wie folgt zusammen:

[in der docker-compose.yml angegebene hostname des b2b-Containers][Pfad (ohne Trennzeichen "/") der gestarteten B2B-Instanz im Docker-Container)]

Dieser Datensatz erhält nach dem Start des B2B-Containers automatisch einen Wert [Knotennr.],LAST STARTED AT: [Datum] at [Uhrzeit].

Für dieses Feature wird der hostname in der docker-compose.yml explizit angegeben.

Anpassungen der Arbeitsvorräte

Die B2B-Arbeitsvorräte (nicht zu verwechseln mit den CCM-Arbeitsvorräten) werden nun nicht mehr über die Rollenattribute sondern über die Extension WORKLISTS konfiguriert. Bei der Umstellung hilft das Migration-Tool.

Docker-Compose

docker-compose Umgebung

Unsere Docker Umgebung wird hauptsächlich durch eine Reihe von Konfigurationsdateien gesteuert. Diese im Folgenden beschriebenen Dateien können von NLI gebündelt als zip-Archiv bereitgestellt werden.

Das Setup der hier beschriebenen Umgebung basiert auf einem docker-compose file. Diese Konfiguration definiert die einzelnen Container, deren Sichtbarkeit und die einzubindenden Dateien.

Die docker-compose Umgebung besteht letztlich aus einer Verzeichnisstruktur, die die einzelnen im Folgenden beschriebenen Dateien enthält. Die Verzeichnisstruktur stellt sich wie folgt dar:

| base/
  |- b2b-tomcat/
  |  |- lib/
  |  |  |- [DB-JDBC-Treiber].jar
  |  |- tomcat_all/
  |  |  |- index/
  |  |     |- full/
  |  |     |- arc/
  |  |     |- ccm/
  |  |- b2bbp-engine.xml
  |  |- keycloak.json
  |- b2b-ui/
  |  |- keycloak.json
  |- docker-compose.yml
  |- .env
  |- system.json

Diese Dokumentation basiert auf der folgenden docker-compose.yml:

version: '3.7'
services:
  traefik:
    image: "traefik:v2.3"
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.traefik.address=:7777"
      - "--entryPoints.web.forwardedHeaders.insecure"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
#   For running local
    ports:
      - 80:80
#    For Linux machine
#    network_mode: host
  b2b:
    image: ${NEXUS}/b2b:2021-02-22
    restart: always
    hostname: b2b
    ports:
      # Port unter dem die B2B-Instanz (auch von außen) erreichbar ist
      - ${B2B_PORT}:8080
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      # mount point für die zu verwendende B2B-DB-Konfiguration
      - ./b2b-tomcat/b2bbp-engine.xml:/usr/local/tomcat/conf/Catalina/localhost/b2bbp-engine.xml
      # mount point für die zu verwendende B2B-keycloak-Konfiguration
      - ./b2b-tomcat/keycloak.json:/usr/local/tomcat/conf/keycloak.json
      # mount für die logs
      - ./b2b-tomcat/tomcat_all/logs:${LOGS}
      # mount points für die zu verwendende B2B-Indizes
      - ./b2b-tomcat/tomcat_all/index/full:${FUL_IDX_PATH}
      - ./b2b-tomcat/tomcat_all/index/arc:${ARC_IDX_PATH}
      - ./b2b-tomcat/tomcat_all/index/ccm:${CCM_IDX_PATH}
      # mount point für den zu verwendenden B2B-DB-Treiber
      - ./b2b-tomcat/lib/${DB_DRV_FILE}:/usr/local/tomcat/lib/${DB_DRV_FILE}
  # Container-Definition für die B2B-New-UI-Instanz
  b2b-ui:
    image: ${NEXUS}/b2b-ui:2021-03-18
    restart: always
    ports:
      # Port unter dem die B2B-New-UI-Instanz (auch von außen) erreichbar ist
      - ${NUI_PORT}:8080
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      # mount point für die zu verwendende B2B-New-UI-keycloak-Konfiguration
      - ./b2b-ui/keycloak.json:/usr/share/nginx/html/B2B-UI/assets/config/keycloak.json
      - ./system.json:/usr/share/nginx/html/B2B-UI/assets/config/system.json
      - ./b2b-ui/logs/host.access.log:/var/log/nginx/host.access.log
      - ./b2b-ui/logs/host.error.log:/var/log/nginx/host.error.log
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.b2b-ui.rule=Host(`${TRAEFIK_HOST}`) && PathPrefix(`/B2B-UI`)"	  
    depends_on:
      - b2b

Bitte folgen Sie unseren Konventionen für Servicenamen (aus denen sich dann die Hostnamen ergeben).

Achten Sie beim image darauf, eine aktuelle Version gemäß unserer Kompatibilitätsübersicht anzugeben.

Die oben aufgeführte docker-compose.yml beinhaltet verschiedene Variablen “${Variable}”. Diese Variablen dienen der Auslagerung von speziellen Bedingungen. Diese Variablen sind in der Datei .env enthalten und werden während des Starts der Container via docker-compose angewendet. Für die oben aufgeführte docker-compose.yml sieht die .env wie folgt aus:

NEXUS=docker-nob-erf.next-level-apps.com
TIME_ZONE=Europe/Berlin
B2B_PORT=8081
NUI_PORT=8082
FUL_IDX_PATH=/usr/local/tomcat_all/index/full
ARC_IDX_PATH=/usr/local/tomcat_all/index/archive
CCM_IDX_PATH=/usr/local/tomcat_all/index/ccm
LOGS=/usr/local/tomcat_all/logs
DB_DRV_FILE=postgresql-42.2.16.jar
TRAEFIK_HOST=localhost

Weiterhin werden in der oben aufgeführten docker-compose.yml verschiedenen Dateien referenziert. Sowohl die angegebenen Verzeichnisse der einzelnen Dateien, als auch die Dateien an sich, sind Bestandteil der docker-compose Umgebung und werden in den Abschnitten der konkreten Applikationen aufgeführt und erläutert.

optionale Docker-Compose Konfiguration

Falls es bei Ihnen zu Abbrüchen während der Volltextsuche kommt (besonders bei MSSQL Datenbanken beobachtet), müssen Sie die Eigenschaft auxiliarySearchThreshold konfigurieren. Diese steuert, ab welcher Anzahl an Volltextsuchtreffern die Hilfstabelle zum Einsatz kommen soll. Die Hilfstabelle verhindert, dass Datenbankanfragen zu groß werden. Reduzieren Sie den Wert der Eigenschaft, wenn es zu Abbrüchen bei der Volltextsuche kommt. Default ist 30000, für MSSQL empfehlen wir als Wert 2000.

Die Eigenschaft kann als Umgebungsvariable bei einer Docker Installation in der docker-compose.yml gesetzt werden:

  b2b:
    environment:
      AUXILIARY_SEARCH_THRESHOLD: 2000

Wenn Sie einen vom Standard abweichenden Service in Ihrer Reverse-Proxy-Konfiguration konfigurieren möchten, folgen Sie bitten den Hinweisen in der Docker-Compose-Dokumentation

Traefik

Der Traefik Container wird für das Routing der Request verwendet. Durch das Hinzufügen von verschienden Lables zu den anderen Containern wird der Traefik konfiguriert. Durch die Umgebungsvariable TRAEFIK_HOST muss der durch Traefik verwendete Hostname gesetzt werden.

B2B-Tomcat

Das Veröffentlichen des B2B-Tomcat-Ports nach außen ist optional, solange der Tomcat nur von der UI angesprochen wird. Wird der Port veröffentlicht, kann man z.B. zu Testzwecken auf die Swagger-UI zugreifen.

Einbindung des Datenbank-Treibers

Wenn als Remote B2B-Datenbank eine Oracle eingesetzt wird und die entsprechenden Datenbank-Treiber aus Lizenzgründen nicht durch uns ausgeliefert werden dürfen, sind diese durch den Kunden in das Verzeichnis ./b2b-tomcat/lib/ zu kopieren. Als Bezugsquelle für die JDBC-Treiber kann die entsprechende Download-Seite von Oracle verwendet werden (siehe auch hier). Der Dateiname ist in der Umgebungsvariablen DB_DRV_FILE anzugeben.

./b2b-tomcat/b2bbp-engine.xml

Diese Datei definiert die Datenbankverbindung, mit der sich die B2B-Instanz mit der Remote-B2B-Datenbank verbindet. Hier die für diese Dokumentation verwendete Datei:

<?xml version="1.0" encoding="UTF-8" ?>
<Context path="/b2bbp-engine" reloadable="true" cachingAllowed="true" crossContext="true">
	<Resource name="jdbc/b2bbp"
			  auth="Container"
			  type="javax.sql.DataSource"
			  driverClassName="[jdbc-Treiber, z.B. org.postgresql.Driver]"
			  url="jdbc:[Datenbank, z.B. postgresql]://[Host der Remote-B2B-DB]:[Port der Remote-B2B-DB]/[Name der Remote-B2B-DB]"
			  username="[username]"
			  password="[password]"
			  maxTotal="20"
			  maxIdle="10"
			  maxWaitMillis="-1"/>

	<Valve className="org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve"/>

	<Parameter name="keycloak.config.file" value="/usr/local/tomcat/conf/keycloak.json" override="false"/>

</Context>

./b2b-tomcat/keycloak.json

Diese Datei konfiguriert die Anbindung der B2B-Instanz an den keycloak. Folgende Konfiguration wurde für diese Dokumentation verwendet:

{
  "realm": "B2B",
  "auth-server-url": "http://keycloak:8080/auth/",
  "ssl-required": "external",
  "resource": "b2b-tomcat",
  "credentials": {
    "secret": "***"
  },
  "confidential-port": 0
}

Die Datei wird am besten direkt aus der Keycloak Admin-UI exportiert. In Keycloak muss dafür ein passender Client angelegt werden. Dies wird im Keycloak Abschnitt später genauer beschrieben.

Tomcat Classpath Konfiguration

Damit die keycloak.json in weiteren Tomcat Workflows genutzt werden kann, muss sichergestellt sein, dass sie im Classpath verfügbar ist. Wir empfehlen die Datei im Ordner tomcat/conf zu mounten, da dieser bereits zum Classpath des Images gehört.

tomcat_all Verzeichnis

In der docker-compose.yml sind bereits einige tomcat_all Verzeichnisse gemountet.

Hier sind ggf weitere geteilte Verzeichnisse zu hinterlegen, z.B. für Filecrawler/Filewriter (sofern der Tomcat im Docker solche Aufgaben übernehmen soll).

Beim Mounting ist darauf zu achten, dass Verzeichnisstrukturen gewählt werden, die kompatibel zu denen im Customizing definierten Verzeichnispfaden sind.

Für weitere Tips zum mounten vgl. Sie auch den Abschnitt Anbindung der B2B-Indizes

Anbindung der B2B-Indizes

Da die B2B-Instanz (auch die im Docker gestartete) Zugriff auf die Verzeichnisse der Indizes benötigt, sind diese nun in die docker-compose Umgebung anzubinden. Dies erfolgt mit den folgenden Kommandos:

Für Linux:

:/opt/docker/b2b> sudo mount.cifs //[Remote-B2B-Server]/[Pfad zum Volltextindex] /opt/docker/b2b/b2b-tomcat/tomcat_all/index/full -o user=[Benutzername des Remote-B2B-Servers]
:/opt/docker/b2b> sudo mount.cifs //[Remote-B2B-Server]/[Pfad zum Archivindex] /opt/docker/b2b-tomcat/tomcat_all/index/arc -o user=[Benutzername des Remote-B2B-Servers]
:/opt/docker/b2b> sudo mount.cifs //[Remote-B2B-Server]/[Pfad zum CCM-Index] /opt/docker/b2b-tomcat/tomcat_all/index/ccm -o user=[Benutzername des Remote-B2B-Servers]

Für Windows-Systeme sind die Verzeichnisse über s.g. Netzwerklaufwerke einzubinden. Dabei müssen jedoch die Pfade in der docker-compose.yml angepasst werden.

Logging

Wie in der klassischen B2B üblich wird das Log-Verzeichnis über die Global Property B3P_LOG4J_BASE_DIR konfiguriert. Entsprechend muss über die docker-compose volumes das Verzeichnis an die definierte Stelle gemountet werden.

Das Image schreibt die Logs per default mit dem Linux User 5000:5000. Entweder, sie erlauben diesem User Schreibzugriff auf das Log-Verzeichnis, oder sie geben einen alternativen User in docker-compose an:

  b2b:
    image: ${NEXUS}/b2b:2021-02-22
    user: 1000:1000
    ...

Generell empfehlen wir immer das Einrichten des Loggings. Ferner kann es dazu kommen, dass einzelne Komponenten nicht richtig angezeigt werden, wenn das Logging nicht funktioniert.

B2B-UI

./b2b-ui/keycloak.json

Diese Datei konfiguriert die Anbindung der B2B-New-UI-Instanz an den keycloak. Folgende Konfiguration wurde für diese Dokumentation verwendet:

{
  "realm": "B2B",
  "auth-server-url": "http://keycloak:8080/auth/",
  "ssl-required": "external",
  "resource": "b2b-functional-ui",
  "public-client": true,
  "confidential-port": 0
}

Die Datei sollte direkt aus der Keycloak Admin-UI exportiert werden. In Keycloak muss dafür ein passender Client angelegt werden. Dies wird später genauer beschrieben.

./b2b-ui/nginx.conf

Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben.

./system.json

Die Datei system.json kann als globale Konfiguration genutzt werden. Nach Möglichkeit sollte die gleiche Datei für alle Frontends verwendet werden.

In ihr können der angezeigte Systemname sowie die angezeigte Hintergrundfarbe festgelegt werden.

Ferner kann durch sie das Feature UserMessages aktiviert werden.

{
  "systemName": "B2B Dokusystem",
  "backgroundColor": "#008ECC",
  "activateUserMessages": true
}

Logging

Das access_log und das error_log werden in der nginx.conf definiert.

Damit das Log nicht mit einem weggeworfenen Container verloren geht, kann man das Log auch von außen in den Container mounten. Hierfür sind die Log-Files in den docker-compose/volumes mit anzugeben. Für diese Lösung müssen die Dateien vorher bereits auf dem Docker-Host angelegt und mit geeigneten Berechtigungen versehen sein.

Start docker container (New-UI, B2B)

Mit dem folgenden Kommando können die Container im Docker gestartet werden:

:opt/docker/b2b/> docker-compose up -d

Mit folgendem Kommando können die Container im Docker gestoppt werden:

:opt/docker/b2b/> docker-compose stop

Keycloak

Keycloak Client für die B2B-Docker-Instanz

Für den Client “b2b-tomcat” müssen die Einstellungen wie folgt vorgenommen werden:

Erstellen des Clients b2b-tomcat

Folgende Werte müssen gesetzt sein:

Feld Wert
Client ID b2b-tomcat
Client Protocol openid-connect
Root URL http://b2b:8080/b2bbp-engine

Durch ein Klick auf “Save” werden die Einstellungen gespeichert und die Übersichtsseite des neuen Clients wird angezeigt:

Übersicht des Clients b2b-tomcat

Als Access-Type muss confidential gesetzt werden.

Als Login-Theme kann das nli Thema gewählt werden.

Weitere Anpassungen sind hier nicht vorzunehmen.

Keycloak Client für die B2B-New-UI-Docker-Instanz

Für den Client “b2b-functional-ui” müssen die Einstellungen wie folgt vorgenommen werden:

Erstellen des Clients b2b-functional-ui

Folgende Werte müssen gesetzt sein:

Feld Wert
Client ID b2b-functional-ui
Client Protocol openid-connect
Root URL http://[hostname]/

Durch ein Klick auf “Save” werden die Einstellungen gespeichert und die Übersichtsseite des neuen Clients wird angezeigt:

Übersicht des Clients b2b-functional-ui

Der Standard Flow ist zu aktivieren.

Der Access Type ist auf public zu setzen.

Als Login-Theme kann das nli Thema gewählt werden.

Weitere Anpassungen sind hier nicht vorzunehmen.

Keycloak Rollen & Attribute

Die Konfiguration der benötigten Rollen und Attribute wird hier beschrieben.

UI Komponenten werden nur angezeigt, wenn die entsprechenden Rollen den Usern zugewiesen worden sind.

Mandantenfilterung

Die B2B-UI unterstützt eine Mandantenfilterung. Die Konfiguration wird hier beschrieben. Falls diese konfiguriert ist, werden nur die Nachrichten angezeigt, die zum Mandanten des Users passen.

View Me   Edit Me