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
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}
Verwendung von Umgebungsvariablen
Die Konfiguration der Datenbank sowie des Keycloak ist ebenfalls über Umgebungsvariablen möglich. Ein Mounten der application.yml und/oder keycloak.json ist in diesem Fall nicht notwendig.
| Variablenname | Beschreibung |
|---|---|
| SPRING_DATASOURCE_URL | Datenbank-URL im jdbc-Format |
| SPRING_DATASOURCE_USERNAME | Datenbank-Benutzername |
| SPRING_DATASOURCE_PASSWORD | Datenbank-Passwort |
| KEYCLOAK_AUTHSERVERURL | Keycloak Auth-Server-Url |
| KEYCLOAK_REALM | Keycloak Realm |
| KEYCLOAK_RESOURCE | Keycloak Resource |
| KEYCLOAK_CREDENTIALS_SECRET | Keycloak Credentials Secret |
RevisionInfo UI
./b2b-revisioninfo-ui/keycloak.json
Verwendung von Umgebungsvariablen (ab August 2023)
Wir empfehlen die Verwendung von Umgebungsvariablen in der keycloak.json, sofern keine zusätzlichen Eigenschaften konfiguriert werden sollen.
Die Standard keycloak.json für die Revision-UI sieht aktuell wie folgt aus:
{
"realm": "${KC_REALM}",
"auth-server-url": "${KC_URL}",
"ssl-required": "${KC_SSL_REQUIRED}",
"resource": "${KC_CLIENT}",
"public-client": true,
"confidential-port": 0
}
Die definierten Umgebungsvariablen werden beim Erzeugen des Docker-Containers gesetzt und verwendet, sofern keine keycloak.json-Datei in den Container gemountet wurde.
Bei allen Keycloak-Parametern müssen json-Sonderzeichen escaped werden, da sonst keine valide keycloak.json erzeugt wird.
| Variablenname | Beschreibung | Default |
|---|---|---|
| KC_REALM | Keycloak Realm | |
| KC_URL | Keycloak Auth-Server-Url | |
| KC_SSL_REQUIRED | Keycloak SSL required | none |
| KC_CLIENT | Keycloak Resource | revision-ui |
Als gesamte Datei
Diese Datei konfiguriert die Anbindung der Revision-UI-Instanz an den keycloak. Folgende Konfiguration wurde für diese Dokumentation verwendet:
{
"realm": "B2B",
"auth-server-url": "http://keycloak:8080/auth/",
"ssl-required": "none",
"resource": "revision-ui",
"public-client": true,
"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.
./b2b-revisioninfo-ui/nginx.conf
Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben.
Sie kann auch über die folgenden Umgebungsvariablen individuell angepasst werden:
ENV PORTAL_UI_URL="http://portal-ui:8080" # URL mit der die B2B-Revision-UI auf die B2B-Portal-UI zugreifen kann.
ENV B2B_URL="http://b2b:8080" # URL mit der die B2B-Revision-UI auf das B2B Backend zugreifen kann.
ENV NOTIFICATION_URL="http://notification:8080" # URL mit der die B2B-Revision-UI auf das Notification Backend zugreifen kann.
ENV REVISION_URL="http://revision:8080" # URL mit der die B2B-Revision-UI auf das Revision Backend zugreifen kann.
ENV SERVICE_PATH=/B2B-RevisionInfo-UI # URL-Pfad zur UI. Achtung: Eine Änderung des Defaults muss in allen Konfigurationen der UI berücksichtigt werden (z.B. Keycloak Client und portal-config.json).
./system.json
Verwendung von Umgenungsvariablen
Wir empfehlen die Verwendung von Umgebungsvariablen in der system.json, sofern keine zusätzlichen Eigenschaften konfiguriert werden sollen.
Die Standard system.json für die B2B-RevisionInfo-UI sieht aktuell wir folgt aus:
{
"systemName": "${SYSTEM_NAME}", # Angezeigter Name in der UI. Default: B2B
"backgroundColor": "${BACKGROUND_COLOR}", # Farbe der UI in hex color code. Default: #008ECC (blau)
"activateUserMessages": "${ACTIVATE_USER_MESSAGES}", # Wird das Feature für Benutzerbenachrichtigungen verwendent. Default: false
}
Die definierten Umgebungsvariablen werden beim Start des Containers gesetzt und verwendet, sofern eine eigene system.json nicht bereits keine Datei in den Container gemountet wurde.
Als gesamte Datei
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
Das FSS-Backend benötigt das Revision Manager Schreibrecht um dort Einträge hinterlegen zu können. Dieses kann über die Keycloak Adminoberfläche unter Clients verteilt werden. Üblicherweise heißt der Client für das FSS-Backend fss.
Es muss Service Accounts Enabled aktiviert werden, was in älteren Keycloak-Versionen nur möglich ist, wenn der Access Type nicht auf public steht. Dann muss über den Service Account Roles Tab die Rolle RevisionManager-Write zugewiesen werden. Sollte das FSS-Backend dabei schon laufen, muss es neugestartet werden, damit die Rechteänderung greift.