Setup der New-UI in Docker

Einleitung

Diese Dokumentation beschreibt das Setup und die Konfiguration einer B2B-New-UI auf Basis von Docker-Containern in einem Docker-Host-System.

Umgebung

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

Übersicht der einzelnen Module/Komponenten

Docker-Host

Als “Docker-Host” wird das System/Server bezeichnet, auf dem die Docker-Instanz läuft in der die New-UI, der Keycloak und (optional) die B2B installiert sind.

Als Betriebssystem für den Docker-Host kann Microsoft Windows oder aber auch Linux-Systeme (z.B. ubuntu, openSuse) verwendet werden. Bei der Auswahl sollte jedoch darauf geachtet werden ein möglichst etabliertes und stabiles System zu verwenden. Zudem ist es wichtig, dass für das verwendete Betriebssystem des Docker-Hosts (z.B. Windows, ubuntu, openSuse) entsprechend aktuelle Docker-Versionen verfügbar sind.

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

Der 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.

index-management-service

Dieser Docker-Container stellt die Backend-Instanz Index Management zur Verfügung. Diese läuft in einem Java-Container.

index-management-ui

Dieser Docker-Container stellt die Index Management UI-Instanz zur Verfügung. Sie läuft auf einem nginx-Webserver..

Setup

In diesem Kapitel werden die Voraussetzungen und die Installation der New-UI, der Keycloak-Instanz und (optional) der B2B-Instanz im Docker beschrieben.

Voraussetzungen

docker-compose Umgebung

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/
  |  |     |- arc/
  |  |     |- ccm/
  |  |     |- full/
  |  |- b2bbp-engine.xml
  |  |- keycloak.json
  |- b2b-ui/
  |  |- keycloak.json
  |  |- nginx.conf
  |- index-management-service/
  |  |- application.yml
  |- index-management-ui/
  |  |- keycloak.json
  |  |- nginx.conf
  |- keycloak/
  |  |- data/
  |- docker-compose.yml
  |- .env
  |- README.md

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

version: '3.7'
services:
  # Container-Definition für die keycloak-Instanz
  keycloak:
    image: ${NEXUS}/keycloak:nli-10
    restart: always
    hostname: keycloak
    ports:
      # Port unter dem der keycloak (auch von außen) erreichbar ist
      - ${KEYCLOAK_PORT}:8080
    environment:
      # Admin-Zugang für den keycloak
      - KEYCLOAK_USER=admin
      - KEYCLOAK_PASSWORD=admin
    volumes:
      # mount point für die keycloak DB
      - ./keycloak/data/:/opt/jboss/keycloak/standalone/data
  # Container-Definition für die B2B-Instanz
  b2b:
    image: ${NEXUS}/b2b:2020-08-18
    hostname: b2b-tomcat
    restart: always
    ports:
      # Port unter dem die B2B-Instanz (auch von außen) erreichbar ist
      - ${B2B_PORT}:8080
    environment:
      - REVISION_INFO_SERVER_URL: http://revision-service:8080
      - SECURE_WITH_KEYCLOAK: "true"
      - 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
  b2bui:
    image: ${NEXUS}/b2b-ui:2020-08-19
    restart: always
    hostname: b2b-ui
    ports:
      # Port unter dem die B2B-New-UI-Instanz (auch von außen) erreichbar ist
      - ${NUI_PORT}:80
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      # mount point für die Konfiguration des B2B-New-UI Webservers
      - ./b2b-ui/nginx.conf:/etc/nginx/nginx.conf
      # 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
  index-management-service:
    image: ${NEXUS}/indexmanagement:2020-10-14
    ports:
      - 8090:8080
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      - ./b2b-tomcat/tomcat_all/index:/index
      - ./index-management-service/application.yml:/lib/application.yml
  index-management-ui:
    image: ${NEXUS}/index-management-ui:2020-10-14
    restart: always
    ports:
      - 94:8080
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      - ./index-management-ui/nginx.conf:/etc/nginx/nginx.conf
      - ./index-management-ui/keycloak.json:/usr/share/nginx/html/B2B-Index-Management-UI/assets/config/keycloak.json
      - ./index-management-ui/portal-url.json:/usr/share/nginx/html/B2B-Index-Management-UI/assets/config/portal-url.json
      - ./system.json:/usr/share/nginx/html/B2B-Index-Management-UI/assets/config/system.json
    depends_on:
      - index-management-service

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:

KEYCLOAK_PORT=8080
B2B_PORT=8081
NUI_PORT=80
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
NEXUS=docker-nob-irr.next-level-apps.com
TIME_ZONE=Europe/Berlin

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 im Folgenden aufgeführt und erläutert.

./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>

Das Veröffentlichen des B2B-Tomcat-Ports nach außen ist optional, solange der Tomcat nur von der UI angesprochen wird.

./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",
  "public-client": true,
  "confidential-port": 0
}

Die Datei wird am besten direkt aus der Keycloak Admin-UI exportiert.

./b2b-ui/nginx.conf

Diese Datei konfiguriert den Webserver für den Container der B2B-New-UI-Instanz. Folgende Konfiguration wurde für diese Dokumentation verwendet:

worker_processes  1;
events {
    worker_connections  1024;
}
http {
    include             mime.types;
    default_type        application/octet-stream;
    sendfile            on;
    keepalive_timeout   65;
    server {
        listen          80;
        server_name     b2b-ui;
        location /B2B-UI/ {
            alias       /usr/share/nginx/html/B2B-UI/;
            try_files   $uri$args $uri$args/ /B2B-UI/index.html;
        }
        location /B2B-UI/b2bNews/ {
            proxy_pass  https://b2bbp.next-level-help.org/feed.news.xml;
        }
        error_page      500 502 503 504  /50x.html;
        location = /50x.html {
            root        html/B2B-UI;
        }
        location /B2B-UI/api/ {
            proxy_pass          http://b2b:8080/b2bbp-engine/api/;
            proxy_http_version  1.1;
            proxy_set_header    Upgrade $http_upgrade;
            proxy_set_header    Connection "upgrade";
            proxy_set_header    Host $host;
            proxy_set_header    X-Real-IP $remote_addr;
            proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header    X-Forwarded-Proto $scheme;
            proxy_cache_bypass  $http_upgrade;
        }

        location /B2B-UI/api/b2b-user-messages/system-messages {
            proxy_pass   http://message-service:8080/system-messages;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header        X-Real-IP $remote_addr;
            proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header        X-Forwarded-Proto $scheme;
            proxy_cache_bypass $http_upgrade;
        }
    }
}

Beachten Sie den Eintrag unter proxy_pass, hier wird der B2B-Tomcat im Docker referenziert.

Beachten Sie auch die Property client_max_body_size 100M; Diese Property bestimmt die maximale Dateigröße beim Fileupload. Dies ist z.B. beim Customizing Upload relevant.

./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
}

Die Datei sollte direkt aus der Keycloak Admin-UI exportiert werden.

./index-management-service/application.yml

Diese Datei konfiguriert die Verbindung der Index Management-Backend-Instanz mit dem Keycloak. Diese Datei konfiguriert auch die verwendeten Indizes. Die folgende Konfiguration wurde für diese Dokumentation verwendet:

server:
  port: 8080

spring:
  main:
    allow-bean-definition-overriding: true

search-system:
  vendor: LUCENE2
  search-types:
    FULLTEXT: ../index/full
    ARCHIVE: ../index/arc
    CCM: ../index/ccm
    SYSTEMSPLIT_METERINGPOINT: ../index/custom_index/systemsplit_meteringpoint
    SYSTEMSPLIT_METERINGPOINTTEMP: ../index/custom_index/systemsplit_meteringpoint_temp
    SYSTEMSPLIT_RESPONSE: ../index/custom_index/systemsplit_answer

keycloak:
  enabled: true
  auth-server-url: http://host.docker.internal:8080/auth
  realm: b2b-qa
  resource: indexmanagement
  bearer-only: true
  public-client: false
  cors: true

./index-management-ui/nginx.conf

Diese Datei konfiguriert den Webserver für den Container der Index Management UI-Instanz. Die folgende Konfiguration wurde für diese Dokumentation verwendet:

#user  nobody;
worker_processes  1;

#Changed from /var/run/nginx.pid due to using non-root user
pid /tmp/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    #access_log  logs/access.log  timing;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    server {
        listen       8080;
        server_name  localhost;

        #charset koi8-r;

        #access_log  logs/host.access.log  main;

        location /B2B-Index-Management-UI {
            alias  /usr/share/nginx/html/B2B-Index-Management-UI/;
            try_files $uri$args $uri$args/ /B2B-Index-Management-UI/index.html;
        }

        location /B2B-Index-Management-UI/portalConfig/ {
            proxy_pass   http://host.docker.internal:92/B2B-Portal-UI/assets/config/portal-config.json;
        }

        #error_page  404              /404.html;

        # redirect server error pages to the static page /50x.html
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html/B2B-Index-Management-UI;
        }

        #proxy for rest api call
        location /B2B-Index-Management-UI/api/indexmanagement/ {
                proxy_pass   http://index-management-service:8080/;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_set_header Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_cache_bypass $http_upgrade;
        }

        #proxy for rest api call
        location /B2B-Index-Management-UI/api/ {
                proxy_pass   http://b2b-tomcat:8080/b2bbp-engine/api/;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_set_header Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                oproxy_cache_bypass $http_upgrade;
        }

        location /B2B-Index-Management-UI/api/b2b-user-messages/system-messages {
                proxy_pass   http://message-service:8080/system-messages;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_set_header Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_cache_bypass $http_upgrade;
        }
    }
}

./index-management-ui/keycloak.json

Diese Datei konfiguriert die Verbindung der Index Management-UI-Instanz mit dem Keycloak. Die folgende Konfiguration wurde für diese Dokumentation verwendet:

{
  "auth-server-url": "http://host.docker.internal:8080/auth",
  "realm": "b2b-qa",
  "ssl-required": "none",
  "resource": "indexmanagement-ui",
  "public-client": true,
  "confidential-port": 0
}

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

Keycloak Datenbank

Die Datenbank-Zugangsdaten können über Umgebungsvariablen in der docker-compose.yml konfiguriert werden. Für weitere Details vgl. Sie die Keycloak Image Doku. Bsp:

    environment:
      - DB_VENDOR=postgres
      - DB_ADDR=host.docker.internal
      - DB_DATABASE=keycloak
      - DB_USER=postgres
      - DB_PASSWORD=postgres

Des Weiteren muss der benötigte JDBC Treiber gemountet werden z.B so:

    volumes:
      - /opt/b2b/keycloak/ojdbc.jar:/opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main/driver/ojdbc.jar

Docker

Auf dem Docker-Host muss zwingend eine Docker-Instanz und docker-compose installiert sein. Hinweise zur Installation sind im hier aufgelistet.

Um nach einer Installation von Docker zu prüfen, ob der Docker-Service ordnungsgemäß ausgeführt wird, kann unter Linux folgendes Kommando ausgeführt werden:

:> systemctl status docker | grep Active
   Active: active (running) since Fri 2020-08-21 10:17:16 CEST; 34min ago

Unter Windows sollte nach dem Start von “Docker Desktop” das Docker-Icon Docker-Icon in der Taskleiste angezeigt werden. Mit einem Rechtsklick auf das Icon und Auswahl von “Settings” sollte in dem sich öffnenden Popup links unten die Meldung “Docker is running” erscheinen.

Docker-Settings

Eine weitere Möglichkeit zu testen, ob Docker korrekt installiert wurde, ist der Start eines Test-Containers. Hierfür kann mit dem folgenden Kommando (für Windows und Linux) eine Hello-World-Anwendung in einem Container gestartet werden:

:> docker run hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Erscheint die Ausgabe in etwa so wie oben dargestellt, wurde Docker korrekt installiert.

Zugriff auf NLI-Nexus

Damit beim Starten der Docker-Container die Docker-Images vom NLI-Nexus bezogen werden können, muss dieser vom Docker-Host-System aus zugänglich sein. Hierfür ist für Kundensysteme über ein NLI-Support Ticket eine entsprechende Firewall-Freischaltung für den Docker-Host zu beantragen.

Zusätzlich zur IP-Freischaltung muss auch ein Login beantragt werden. Mithilfe dieses Logins kann der initiale Docker-Login am NLI-Nexus durchgeführt werden.

Für NLI externe Netze (z.B. Arvato) kann mithilfe eines VPNs auf den NLI-Nexus zugegriffen werden. Die Konfiguration für z.B. openVPN kann ebenfalls über den NLI-Support beantragt werden.

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.

Erstellen der DB-Views für die New-UI

In dem Schema der bestehenden B2B-DB-Instanz müssen die hier aufgeführten Views erstellt werden.

Anpassen einiger GlobalProperties

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].

Entpacken der docker-compose Umgebung

Die bereits oben beschriebene docker-compose Umgebung, kann den Kunden als Archiv-Datei (z.B. zip oder tgz) ausgeliefert werden. Um die einzelnen Container auf dem Docker-Host zu starten, ist zunächst die ausgelieferte Datei der docker-compose Umgebung in einem entsprechenden Verzeichnis auf dem Docker-Host zu entpacken (hier auf einem Linux-System):

:/opt/docker/b2b> tar xzf docker-compose-env.tgz

Eine Auflistung des Verzeichnisinhaltes sollte nun in etwa wie folgt aussehen:

drwxr-xr-x 4 root root    4096 Aug 20 09:48 b2b-tomcat
drwxr-xr-x 2 root root    4096 Aug 20 11:14 b2b-ui
-rwxr-xr-x 1 root root    3095 Aug 21 09:34 docker-compose.yml
-rw-rw-r-- 1 root root 5621248 Aug 20 14:38 docker-compose-env.tgz
drwxr-xr-x 3 root root    4096 Aug 19 12:14 keycloak
-rwxr-xr-x 1 root root     168 Aug 20 13:54 README.md

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).

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.

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. Dieser Ordner kann wie folgt dem Classpath hinzugefügt werden: aktualisieren Sie bitte die Datei tomcat/conf/catalina.properties folgendermaßen:

common.loader=”${catalina.base}/lib”,”${catalina.base}/lib/.jar”,”${catalina.home}/lib”,”${catalina.home}/lib/.jar”,”${catalina.home}/conf”

Mit dem nächsten Release (Mitte November) wird diese Konfiguration vereinfacht.

Backend-Service Konfiguration

Die Docker Umgebung stellt nicht nur UI Frontends im nginx, sondern auch Java Backends zur Verfügung. Neben dem klassischen B2B-Tomcat gehören dazu auch:

  • Revision-Service (von manchen Frontends, B2B-Tomcat & FSS genutzt)
  • User-Messages-Service (von allen Frontends genutzt)
  • Index-Service (einzig von der IndexUI genutzt)

Revision-Service

Zum Revision-Service muss in Keycloak ein Client angelegt werden. Der Zugriffstyp muss confidential sein.

Der Revision Service wird über eine application.yml konfiguriert. Diese muss in der docker-compose.yml gemountet werden. Konfiguriert werden muss die Anbindung an die Datenbank (aktuell die gleiche Datenbank wie die B2B-Datenbank) sowie ans Keycloak. Beispiel:

server:
  port: 8080
spring:
  main:
    allow-bean-definition-overriding: true
  jpa:
    database-platform: org.hibernate.dialect.PostgreSQLDialect
  datasource:
    url: jdbc:postgresql://b2b-postgres:5432/b2bbp
    username: postgres
    password: ***
keycloak:
  enabled: true
  auth-server-url: http://host.docker.internal:8080/auth
  realm: b2b
  resource: b2b-revision
  bearer-only: true
  public-client: false
  cors: true

Der Pfad zum Revision-Service muss entsprechend in den aufrufenden Frontends/Backends konfiguriert werden.

In den nginx.conf ist der Pfad wie üblich anzugeben. Beispiel in der RevisionInfo UI:

http {
  server {
        location /B2B-RevisionInfo-UI/api/revisionmanager/ {
                proxy_pass   http://revision-service:8080/revisionmanager/;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_set_header Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_cache_bypass $http_upgrade;
        }

        location /B2B-RevisionInfo-UI/api/ {
                proxy_pass   http://b2b-tomcat:8080/b2bbp-engine/api/;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_set_header Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_cache_bypass $http_upgrade;
                proxy_read_timeout 360s;
                client_max_body_size 150M;
        }

        location /B2B-RevisionInfo-UI/api/b2b-user-messages/system-messages {
                proxy_pass   http://message-service:8080/system-messages;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_set_header Host $host;
                proxy_set_header        X-Real-IP $remote_addr;
                proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header        X-Forwarded-Proto $scheme;
                proxy_cache_bypass $http_upgrade;
        }

Damit der Tomcat ebenfalls auf das Revision-Backend zugreifen kann, ergänzen Sie bitte die CATALINA_OPTS in tomcat/bin/setenv.sh folgendermaßen:

-Drevision.info.server.url={revision_url}

Falls Hostnamen innerhalb des Containers nicht aufgelöst werden können (z.B. der Hostname des Datenbankservers), können diese auch in der docker-compose.yml mit Hilfe von extra_hosts konfiguriert werden. Beispiel:

  revision-service:
    image: ${NEXUS}/revision:2020-10-26
    volumes:
      - ./revision-service/application.yml:/lib/application.yml
    extra_hosts:
      - "databaseserver:10.10.10.10"

User-Message-Service

Die Konfiguration des User-Message-Service verläuft analog zum Revision-Service. Hier ist allerdings keine Konfiguration seitens des Tomcats nötig.

IndexManagement-Service

Die Konfiguration des IndexManagement-Service verläuft analog zum User-Message-Service.

Zusätzlich müssen in der application.yml die verfügbaren Indexe konfiguriert werden. Beispiel:

search-system:
  vendor: LUCENE2
  search-types:
    FULLTEXT: ../index/full
    ARCHIVE: ../index/arch

Diese Verzeichnisse müssen entsprechend in den Docker-Container gemounted werden. Dies kann über die docker-compose.yml konfiguriert werden.

Start docker container (New-UI, B2B, keycloak)

Nachdem die docker-compose Umgebung vorbereitet wurde, die Anpassungen an der Remote-B2B-Datenbank vorgenommen wurden und bestätigt werden konnte, dass der Docker-Service ausgeführt wird, kann mit dem folgenden Kommando der Login der Docker-Instanz am NLI-Nexus vorgenommen werden (Zugangsdaten siehe hier):

:opt/docker/b2b/> docker login -u [user] -p [password] nexus-docker.next-level-apps.com

Anschließend können mit dem folgenden Kommando die benötigten Container im Docker gestartet werden:

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

Um zu prüfen, ob die Container erfolgreich gestartet wurden kann der Status der Container mit dem folgenden Kommando abgefragt werden:

:opt/docker/b2b/> docker ps -a

Als Ergebnis dieses Kommandos sollte in etwa Folgendes ausgegeben werden:

CONTAINER ID        IMAGE                                                COMMAND                  CREATED             STATUS              PORTS                                            NAMES
c5b131cc4bd4        nexus-docker.next-level-apps.com/b2b:2020-08-18      "/bin/sh -c 'catalin…"   30 minutes ago      Up About a minute   0.0.0.0:8000->8000/tcp, 0.0.0.0:8081->8080/tcp   dev_b2b_1
79ea59d8cab7        nexus-docker.next-level-apps.com/b2b-ui:2020-08-19   "/docker-entrypoint.…"   19 hours ago        Up 2 hours          0.0.0.0:80->80/tcp                               dev_b2bui_1
3213ce077344        nexus-docker.next-level-apps.com/keycloak:nli-10     "/opt/jboss/tools/do…"   19 hours ago        Up 2 hours          0.0.0.0:8080->8080/tcp, 8443/tcp                 dev_keycloak_1

Wichtig ist hierbei der Status der einzelnen Container, der jeweils “Up” sein sollte.

Konfiguration/Einrichtung des keycloak

Nachdem die Container im Docker gestartet wurden, muss nun noch der keycloak konfiguriert werden. Hier sind die folgenden Bereiche einzurichten:

  • Realm
  • Clients
  • Roles
  • Users

Diese Schritte werden im Folgenden zusammengefasst. Es sei hier auch auf die vollständige Keycloak-Konfiguration-Doku verwiesen.

Realm

Um die Kommunikation zwischen der New-UI und der B2B in Docker abzusichern, muss im keycloak zunächst ein Realm definiert werden. Hierzu ist der keycloak im Browser unter der URL “http://[keycloak-host]:8080” aufzurufen:

Startseite der Keycloak-Docker-Instanz

Nach einem Klick auf “Administration Console” kann man sich mit “admin/admin” anmelden und über “Add realm” den Realm “B2B” anlegen:

keycloak_add-realm

Der Realm “B2B” kennzeichnet den gesamten Applikationskontext. Dem Realm kann nun noch ein Name zugewiesen werden. Dieser Name (“Display name” bzw. “HTML Display name”) wird im Login-Formular angezeigt:

Anpassen des Realm B2B

Folgende Werte können vergeben werden (frei anpassbar):

Feld Wert
Display name B2B by Practice
HTML Display name <h1 style="color:red;font-weight:bold;">B2B by Practice</h1>

Clients

Innerhalb des neuen Realms “B2B” müssen jetzt die Applikationen angelegt werden, die sich innerhalb des Applikationskontextes authentifizieren dürfen. Diese s.g. Clients können unter der entsprechenden Menüfunktion erstellt werden:

Öffnen des Formulars zum Erstellen eines neuen Clients

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 wird confidential empfohlen.

Weitere Anpassungen sind hier nicht vorzunehmen.

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.

Weitere Anpassungen sind hier nicht vorzunehmen.

Roles

Die im keycloak definierten Roles werden nach einem Login an der entsprechenden Session des Nutzers gespeichert und dienen der Steuerung der zugreifbaren (B2B-Backend) bzw. anzeigbaren Inhalte (B2B-New-UI).

Hinzufügen einer Rolle

Alle in diesem Kapitel aufgeführten Rollen müssen wie im Folgenden dargestellt eingerichtet werden:

Hinzufügen einer Rolle

Users

Damit man sich beim Aufruf der B2B-New-UI auch anmelden kann, muss zumindest ein Nutzer im keycloak hinterlegt werden. Dies kann unter dem Menüpunkt “Users” vorgenommen werden:

Aufruf des Formulars zum Erstellen eines Benutzers

Zunächst wird wie im Folgenden dargestellt ein Testbenutzer angelegt:

Erstellen eines Benutzers

Nach dem Klick auf “Save”, wird dessen Detailansicht im keycloak angezeigt. Um dem Nutzer die benötigten Rollen zuzuweisen, sind dieser unter dem entsprechenden Register auszuwählen und zuzuordnen:

Zuordnen der Rollen zu einem Benutzer

Migration der B2B-Benutzer nach keycloak

Eine Migration der B2B-Nutzer (der Remote-B2B) ist möglich. Mithilfe eines Migrationstools können die in der Remote-B2B enthaltenen Benutzer in die Keycloak-Instanz überführt werden. Eine Übernahme der Passwörter ist ab Oktober 2020 (Ticket NUI-785) möglich. Ab NUI-519 (vorraussichtlich ab Oktober 2020) kann mit Hilfe des Migrationstools allen migrierten Nutzern eine selbst-definierbare Standardgruppe von Rollen zugewiesen werden. Die Rollen & Gruppen können dannach für jeden User einzeln in Keycloak konfiguriert werden.

Die aktuelle Dokumentation des Migrationstools finden sie hier

Migration der Benutzer

Die Migration der Benutzer von der Remote-B2B in den Keycloak erfolgt mithilfe eines Migrationstools. Dieses Migrationstool ist eine Java-Konsolen-Anwendung und wird als Jar-Datei ausgeliefert. Neben der Jar-Datei wird eine Konfigurationsdatei (application.yml) benötigt. Diese Konfigurationsdatei beinhaltet alle Einstellungen, um sowohl auf die Remote-B2B-Datenbank als auch die keycloak-Instanz zuzugreifen.

Im Folgenden ist die Konfigurationsdatei abgebildet:

spring:
  main:
    banner-mode: off

keycloak:
  serverUrl: http://[Docker-Host]:8080/auth/
  realm: B2B
  username: migration-user
  password: [Passwort des migration-user]
  clientId: admin-cli

database:
  driver: oracle.jdbc.OracleDriver
  url: jdbc:oracle:thin:@[Remote-B2B-Datenbank Host]:[Remote-B2B-Datenbank Port]:[Remote-B2B-Datenbank Name]
  username: [Datenbank User]
  password: [Datenbank Passwort]
 = b2bbp_adm_account_date_range.userid
  selectTableSql: SELECT * FROM b2bbp_adm_account
  # basicColumns are columns from db, where it must be provided and migrate to keycloak
  basicColumns: username:userid;firstname:firstname;lastname:lastname;email:email;
  # attributesColumns are columns from db, where is not necessary to be provided for keycloak user attribute
  attributeColumns: organization;password
#  attributeColumns:

ssh:
  # if database require SSH connection, then enable must be true
  enable: false
  # provide ldap username and password for ssh connection
  username: Ldap account
  password: Ldap password
  host: Ssh server
  port: 22
  remoteDbServer: Remote Database server name
  # Remote database server port number
  remoteDbPort: 5413
  # local db port must same as above database url port, else connection will fail
  localDbPort: 5437

output:
  filePath: b2b_migration_result.txt

Um das Migrationstool auszuführen, ist zunächst eine Verzeichnisstruktur zu erstellen. Für diese Dokumentation erfolgt dies mit diesen Kommandos:

:> mkdir -p /opt/b2b/nui/migration/config
:> mkdir -p /opt/b2b/nui/migration/lib

Anschließend sind sowohl die Jar-Datei des Migrationstools als auch der JDBC-Datenbanktreiber (siehe hier) in das Verzeichnis /opt/b2b/nui/migration/lib zu kopieren. Die oben aufgeführte application.yml ist in das Verzeichnis /opt/b2b/nui/migration/config zu kopieren bzw. anzulegen.

Die Ausführung des Migrationstools erfolgt mit dem folgenden Kommando:

:/opt/b2b/nui/migration> java -cp './config/:./lib/' org.springframework.boot.loader.JarLauncher

Nach der Ausführung dieses Kommandos ist die im Folgenden dargestellte Nutzereingabe mit “1” zu beantworten:

...
1 - Database user migration to keycloak
2 - Worklist definition migration
1

Sofern die Migration erfolgreich durchgeführt wurde, erscheint die folgende beispielhafte Ausgabe:

2020-08-28 08:42:43.951  INFO 1816 --- [           main] c.n.b.migration.tool.impl.UserMigration  : Executing select statement 'SELECT * FROM b2bbp_adm_account'
2020-08-28 08:42:43.995  INFO 1816 --- [           main] c.n.b.migration.tool.impl.UserMigration  : Total records need to migrate to keycloak : 2
2020-08-28 08:42:43.995  INFO 1816 --- [           main] c.n.b.migration.tool.impl.UserMigration  : Migrating data from database to keycloak...
2020-08-28 08:42:44.515  INFO 1816 --- [           main] c.n.b.migration.tool.impl.UserMigration  : Total records migrated to keycloak: 2 , details of migration error can refer to b2b_migration_result.txt
2020-08-28 08:42:44.515  INFO 1816 --- [           main] c.n.b.m.t.MigrationConsoleApplication    : -----------------------MIGRATION FINISHED-----------------------

Diese Ausgabe gibt Auskunft über den Verlauf der Migration und die Anzahl migrierten Benutzern.

manuelle Anpassung der Benutzer nach der Migration

Nachdem die oben beschriebene Benutzermigration durchgeführt wurde, müssen nun die Benutzer im Keycloak sowohl mit den entsprechenden Rollen versehen als auch ihr initiales Passwort vergeben werden. Beide Schritte sind manuell über die Keycloak-Administrationskonsole vorzunehmen.

Die Zuweisung der Rollen erfolgt nach der Auswahl des Benutzers, wie im Kapitel Users dokumentiert. Welche Rolle die einzelnen Benutzer erhalten obliegt dem durchführenden Administrator.

Da während der Benutzermigration den einzelnen Benutzer keine Passwörter zugewiesen wurden, ist dies nun manuell für jeden Benutzer wie folgt nachzuholen. Dabei wird jedem Benutzer ein initiales Passwort vergeben (z.B. [Vorname]-[Nachname]) und der Account wird mit der Aktion zum Zurücksetzen des Passwortes bei erstmaligem Login versehen.

Zunächst ist der Benutzer nach der Anmeldung an der Keycloak-Administrationskonsole zu öffnen:

Öffnen eines Benutzers zum Bearbeiten

Nachdem (wie oben erwähnt) die Rollen zugewiesen wurden, ist über “Details” und “Credentials” das initiale Passwort und die Aktion zum Zurücksetzen des Passwortes bei erstmaligem Login zu vergeben:

Setzen der Aktion zum Zurücksetzen des Passwortes

Vergabe des initialen Passwortes

Nachdem die hier beschriebenen Anpassungen vorgenommen wurden, können sich die Benutzer bei der B2B-New-UI anmelden und werden nach dem ersten Login zum Zurücksetzen ihres Passwortes aufgefordert.

nützliche Docker-Kommandos

Stoppen von einzelnen Containern

:> docker stop [Containername]

Starten von einzelnen Containern

:> docker start [Containername]

Stoppen aller Container

:> docker stop $(docker ps -a -q)

Entfernen aller Container

:> docker rm $(docker ps -a -q)

Log-Ausgaben einzelner Container anzeigen

:> docker logs [Containername]

oder um den Log-Ausgaben zu folgen:

:> docker logs --follow [Containername]

Zugriff auf einzelne Container

:> docker exec -it [Containername] bash

Dieses Kommando ist sehr nützlich, um direkt in dem entsprechenden Docker-Container zu arbeiten. So können ggf. direkte Anpassungen im Container vorgenommen werden oder weitere Log-Dateien analysiert werden.

View Me   Edit Me