Funktionalität

Mit der RevisionInfo bietet die B2B die Möglichkeit, die Anpassungen an verschiedenen Konfigurationen (z.B. Customizing) zu dokumentieren: welcher User hat wann welche Änderung durchgeführt?

Die RevisionInfo kann ebenfalls im FSS genutzt werden.

Architektur

Das Feature wurde entkoppelt und benötigt nun keinen Tomcat mehr. Stattdessen gliedert es sich in eine B2B-RevisionInfo-UI & einen B2B-RevisionInfo-Service. Die UI greift auf den Service zu. Der Service greift auf die bestehende Datenbank zu.

Beide Applikationen sind über Keycloak abgesichert.

Um mittelfristig die RevisionInfo aus dem Tomcat herauszulösen, kann die B2B im Tomcat mit dem RevisionInfo-Service kommunizieren, wenn der Tomcat auf Keycloak umgestellt wurde. Ansonsten nutzt der Tomcat die alte integrierte RevisionInfo Logik.

Voraussetzungen

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

Installation

Das Setup der hier beschriebenen Umgebung basiert auf einem docker-compose file. Diese Konfiguration definiert einen Container.

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/
  |- revision-service/
  |  |- application.yml
  |- b2b-revisioninfo-ui/
  |  |- keycloak.json
  |  |- nginx.conf
  |- docker-compose.yml
  |- .env
  |- system.json

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

version: '3.7'
services:
  revision:
    image: ${NEXUS}/revision:2021-03-18
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      - ./revision-service/application.yml:/lib/application.yml
  revisioninfo-ui:
    image: ${NEXUS}/b2b-revisioninfo-ui:2021-03-18
    restart: always
    ports:
      - 1188:8080
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      - ./b2b-revisioninfo-ui/keycloak.json:/usr/share/nginx/html/B2B-RevisionInfo-UI/assets/config/keycloak.json
      - ./b2b-revisioninfo-ui/system.json:/usr/share/nginx/html/B2B-RevisionInfo-UI/assets/config/system.json
      - ./b2b-revisioninfo-ui/logs/host.access.log:/var/log/nginx/host.access.log
      - ./b2b-revisioninfo-ui/logs/host.error.log:/var/log/nginx/host.error.log
    depends_on:
      - revision-service

Bitte folgen Sie bei den Servicenamen unseren Konventionen.

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 sind in der Datei .env enthalten.

NEXUS=docker-nob-erf.next-level-apps.com
TIME_ZONE=Europe/Berlin

optionale Docker-Compose Konfiguration

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

Revision-Service

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: password
    hikari:
      maximumPoolSize: 2
keycloak:
  enabled: true
  auth-server-url: http://[dockerhost]:8080/auth
  realm: [realm]
  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.

Eine Oracle Datenbank kann wie folgt konfiguriert werden:

spring:
  jpa:
    hibernate:
      ddl-auto: none
      naming:
        physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
    database-platform: org.hibernate.dialect.OracleDialect
  datasource:
    driver-class-name: oracle.jdbc.OracleDriver
    url: jdbc:oracle:thin:@[server]:[port]:[schema]
    username: admin
    password: password
    hikari:
      maximumPoolSize: 2

Falls die DNS Namen nicht aufgelöst werden können, hilft es, folgende Datei in den Container zu mounten:

    volumes:
      - /etc/resolv.conf:/etc/resolv.conf

Konfiguration der maximal genutzen Datenbankverbindungen

Um die maximal genutzen Datenbankverbindungen festzulegen, aktualisieren Sie die maximumPoolSize unter dem Abschnitt application.yml> datasource. Wir empfehlen eine maximumPoolSize von 2.

  datasource:
    url: {url}
    username: {username}
    password: {password}
    hikari:
      maximumPoolSize: {maximumPoolSize}

RevisionInfo UI

./b2b-revisioninfo-ui/keycloak.json

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

{
  "realm": "[realm]",
  "auth-server-url": "http://[dockerhost]:8080/auth",
  "ssl-required": "none",
  "resource": "revisioninfo-ui",
  "public-client": true,
  "confidential-port": 0
}

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

./b2b-revisioninfo-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 des Docker-Containers

Mit dem folgenden Kommando kann der benötigte Container im Docker gestartet werden:

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

Mit folgendem Kommando kann der benötigte Container im Docker gestoppt werden:

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

Keycloak Konfiguration

Keycloak Client Konfiguration

Revision Service

Für den Revision-Service muss ein Keycloak Client angelegt werden.

Die ClientId kann von Ihnen selbst gewählt werden, z.B. revision-service.

Die RootURL ist die interne Docker Adresse: http://revision:8080.

Das Client Protocol bleibt auf openid-connect gestellt.

Es ist der Standardflow zu nutzen (standardmäßig aktiv).

Der Access Type ist auf bearer-only zu stellen.

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

Revision-UI

Für die Revision-UI muss ein Keycloak Client angelegt werden.

Die ClientId kann von Ihnen selbst gewählt werden, z.B. revision-ui.

Die RootURL entspricht der externen Adresse des Frontends.

Das Client Protocol bleibt auf openid-connect gestellt.

Es ist der Standardflow zu nutzen (standardmäßig aktiv).

Der Access Type ist public.

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

Keycloak Rollen & Attribute

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

Anbindung der Umsysteme

Anbindung anderer UIs

UIs, welche auf die RevisionInfo zugreifen können sollen, müssen diese in ihrer nginx.conf einstellen. Es folgt eine Beispielkonfiguration für die B2B-UI:

		location /B2B-UI/api/revisionmanager/ {
			    proxy_pass          http://revision: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;
        }

Anbindung Tomcat

Damit der Tomcat auf die RevisionInfo zugreifen kann, muss er für Keycloak konfiguriert sein, d.h. die keycloak.json muss eingebunden sein.

Wenn der Tomcat über Docker betrieben wird, reicht es dann, folgende Umgebungsvariable über die docker-compose.yml zu setzen:

    environment:
      - CATALINA_OPTS: "-Drevision.info.server.url=http://revision:8080"

Anbindung FSS

Damit der FSS auf die RevisionInfo zugreifen kann, muss er für Keycloak konfiguriert sein.

Die entsprechende Dokumentation wird in Kürze ergänzt.