Setup der B2B-Portal-UI in Docker

Funktionalität

Die Portal-UI bietet eine grafische Oberfläche, aus der heraus ein einfacher Absprung in alle anderen UI’s möglich ist.

Das Ergebnis nach der Anmeldung:

Architektur

Die Portal-UI greift auf alle UIs zu und alle UIs greifen auf die Portal-UI zu.

Die Portal-UI benötigt keinen Zugriff zum Tomcat, zu Backends oder zur Datenbank.

Die Portal-UI wird über Keycloak abgesichert.

Voraussetzungen

Docker einsatzbereit
Keycloak installiert
es macht Sinn, vorher alle anderen UIs installiert zu haben

Installation

Docker-Compose

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/
  |- b2b-portal-ui/
  |  |- keycloak.json
  |  |- portal-config.json
  |- docker-compose.yml
  |- .env
  |- system.json

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

version: '3.7'
services:
  portal-ui:
    image: ${NEXUS}/portal-ui:2020-11-12
    restart: always
    ports:
      - 1192:8080
    environment:
      - TZ: ${TIME_ZONE}
    volumes:
      - ./b2b-portal-ui/keycloak.json:/usr/share/nginx/html/B2B-Portal-UI/assets/config/keycloak.json
      - ./b2b-portal-ui/system.json:/usr/share/nginx/html/B2B-Portal-UI/assets/config/system.json
      - ./b2b-portal-ui/portal-config.json:/usr/share/nginx/html/B2B-Portal-UI/assets/config/portal-config.json
      - ./b2b-portal-ui/logs/host.access.log:/var/log/nginx/host.access.log
      - ./b2b-portal-ui/logs/host.error.log:/var/log/nginx/host.error.log

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

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

./b2b-portal-ui/portal-config.json

Damit es möglich wird aus der Portal-UI heraus in alle anderen verfügbaren UI’s abzuspringen, müssen die Zugänge in der portal-config.json konfiguriert werden. Ein vollständige portal-config.json-Konfiguration kann wie folgt aussehen:

{
  "portalConfig": [
    {
      "uiUrl": "http://[dockerhost]:8082/B2B-UI",
      "uiRequiredRole": "B2B-Dashboard",
      "uiName": "portalConfig.uiName.b2b",
      "picturePath": "/B2B-Portal-UI/assets/config/images/p-b2b.jpg",
      "iconName": "/B2B-Portal-UI/assets/config/icons/B2b.svg",
      "description": "portalConfig.description.b2b"
    },
    {
      "uiUrl": "http://[dockerhost]:1186/FSS-UI/",
      "uiRequiredRole": "FSS-CertificateManager-Read",
      "uiName": "portalConfig.uiName.fss",
      "picturePath": "/B2B-Portal-UI/assets/config/images/p-security.jpg",
      "iconName": "/B2B-Portal-UI/assets/config/icons/SecurityServer.svg",
      "description": "portalConfig.description.fss"
    },
    {
      "uiUrl": "http://[dockerhost]:1190/User-Messages-UI/",
      "uiRequiredRole": "B2B-UserMessages-Write",
      "uiName": "portalConfig.uiName.userMessages",
      "picturePath": "/B2B-Portal-UI/assets/config/images/p-systemmessage.jpg",
      "iconName": "/B2B-Portal-UI/assets/config/icons/systemmessage.svg",
      "description": "portalConfig.description.userMessages"
    },
    {
      "uiUrl": "http://[dockerhost]:1188/B2B-RevisionInfo-UI/",
      "uiRequiredRole": "RevisionManager-Read",
      "uiName": "portalConfig.uiName.revisionManager",
      "picturePath": "/B2B-Portal-UI/assets/config/images/p-reversion-manager.jpg",
      "iconName": "/B2B-Portal-UI/assets/config/icons/reversionmanager.svg",
      "description": "portalConfig.description.revisionManager"
    },
    {
      "uiUrl": "http://[dockerhost]:1184/B2B-Admin-UI/",
      "uiRequiredRole": "B2BAdmin-Dashboard",
      "uiName": "portalConfig.uiName.admin",
      "picturePath": "/B2B-Portal-UI/assets/config/images/p-admin.jpg",
      "iconName": "/B2B-Portal-UI/assets/config/icons/administration.svg",
      "description": "portalConfig.description.admin"
    },
    {
      "uiUrl": "http://[dockerhost]:8094/B2B-Index-Management-UI/",
      "uiRequiredRole": "B2B-IndexManagement",
      "uiName": "portalConfig.uiName.indexManagement",
      "picturePath": "/B2B-Portal-UI/assets/config/images/p-indexmanagement.jpg",
      "iconName": "/B2B-Portal-UI/assets/config/icons/index-management.svg",
      "description": "portalConfig.description.indexManagement"
    },
    {
      "uiUrl": "http://[dockerhost]:1192/B2B-Portal-UI/",
      "uiRequiredRole": "B2BPortal-UI",
      "uiName": "portalConfig.uiName.portal",
      "picturePath": "/B2B-Portal-UI/assets/config/b2b-ui.jpg",
      "iconName": "dashboard",
      "description": "portalConfig.description.portal"
    }
  ]
}

Unter “uiUrl” werden die jeweiligen URL’s hinterlegt, unter denen die neuen Oberflächen erreichbar sind. Beispiel für B2B-UI: http://[dockerhost]:8082/B2B-UI.
Unter “uiRequiredRole” ist die jeweilige Rolle einzutragen, die benötigt wird, um auf die jeweilige UI-Anwendung zugreifen zu können. Diese Rolle muss in Keycloack vorhanden sowie dem jeweiligen Benutzer zugeordnet sein.
Unter “uiName” wird ein vordefinierter Wert angegeben, der nicht geändert werden sollte. Wenn Sie diesen Wert ändern möchten, müssen Sie den UI-Quellcode für (EN.json und DE.json) aktualisieren.
Unter “picturePath” und “iconName” werden die Pfade für die Bilder der Portal-UI Kacheln definiert. Auch diese Werte sollten aus dem Beispiel übernommen und nicht geändert werden. In unserem Beispiel wurde der Portal-Ui Microservice im Ordner /B2B-Portal-UI installiert.
Unter “description” werden die jeweiligen tooltips geladen. Auch diese Konfiguration sollte aus dem Beispiel übernommen werden.

Technisch ist es auch möglich, fremde Seiten in der Portal-UI über die portal-config.json zu ergänzen. Für die Icons können dann Base-64-URIs genutzt werden.

Zugriff zur portal-config.json

Nicht nur die Portal-UI, sondern auch alle anderen UIs benötigen Zugriff zur portal-config.json. Während die Portal-UI direkt auf die Datei zugreift, fragen die anderen UIs zur Laufzeit den Inhalt bei der Portal-UI an. Dies erfolgt über ihre nginx Konfiguration (welche per Docker-Image automatisch mitgeliefert wird).

Falls es nicht gewünscht ist, dass eine andere UI direkt auf die Portal-UI zugreift, kann alternativ die portal-config.json auch direkt in das Verzeichnis der jeweiligen UI kopiert / gemountet und von dort ausgelesen werden. Hierzu muss die nginx.conf angepasst werden. Am Beispiel der B2B-UI suchen Sie die folgende Zeile:

        location /B2B-UI/portalConfig/ {
            proxy_pass   http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
        }

Und ersetzen Sie sie entsprechend wie folgt:

        location /B2B-UI/portalConfig {
            alias  /usr/share/nginx/html/B2B-UI/assets/config/portal-config.json;
        }

./b2b-portal-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": "portal-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-portal-ui/nginx.conf

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

Um die Portal-UI nutzten zu können, muss zudem die nginx.conf angepasst werden. Fügen Sie dazu die folgende Konfiguration zur nginx.conf hinzu:

worker_processes  1;

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;

        absolute_redirect off;

	location /B2B-Portal-UI {
            alias  html/B2B-Portal-UI/;
            try_files $uri$args $uri$args/ /B2B-Portal-UI/index.html;
        }

        location /B2B-Portal-UI/api/b2b-user-messages/system-messages {
            proxy_pass   http://notification: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;
        }
    }
}

In diesem Beispiel wurde auch der Zugang zum optionalen Features SystemMessages konfiguriert.

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

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

Öffnen des Formulars zum Erstellen eines neuen Clients

Die ClientId kann von Ihnen selbst gewählt werden, z.B. portal-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.

Keycloak Mapper

Die Konfiguration des Keycloak-Mappers für den Client portal-ui ähnelt dem Client b2b-function-ui und fss-ui hier.

Konfiguration der Umsysteme

Die folgende Konfiguration ist bereits in den Images enthalten. Nutzen Sie unsere Images und folgen Sie unseren Servicenamenkonventionen, ist nichts weiter zu tun.

Bei jeder UI, die mit der Portal-UI zusammenarbeiten soll, muss die jeweilige nginx.conf angepasst werden: es muss jeweils ein Eintrag für die Portal-UI ergänzt werden. Nachfolgend werden die sechs Anpassungen für die B2B-UI, B2B-Admin-UI, B2B-RevisionInfo-UI, B2B-Index-Management-UI, User-Messages-UI & FSS-UI aufgezeigt.

        location /B2B-UI/portalConfig/ {
            proxy_pass   http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
        }
				
        location /B2B-Admin-UI/portalConfig/ {
            proxy_pass   http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
        }	
				
        location /B2B-RevisionInfo-UI/portalConfig/ {
            proxy_pass   http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
        }
        
        location /B2B-Index-Management-UI/portalConfig/ {
            proxy_pass   http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
        }
        
        location /User-Messages-UI/portalConfig/ {
            proxy_pass   http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
        }
        
        location /FSS-UI/portalConfig/ {
            proxy_pass   http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
        }

View Me Edit Me