Setup der B2B-Admin-UI in Docker

Funktionalität

Diese UI enthält:

Customizing Administration
Kommunikationsbeziehungen (AS2)
Lock Tabelle
Queue Tabelle
Systemfehler

Architektur

Dieses Modul kommuniziert mit einer B2B im Tomcat.

Sowohl UI als auch Tomcat müssen über Keycloak abgesichert sein.

Es ist möglich & üblich, genau den gleichen Tomcat zu nutzen, der zusammen mit der B2B-UI eingerichtet wurde. Deshalb wird auf die Konfiguration des Tomcats auf dieser Seite nicht mehr im Detail eingegangen.

Voraussetzungen

Docker einsatzbereit
Keycloak installiert
Remote B2B-Datenbank installiert

Installation

Die Installation verläuft völlig analog zur B2B-UI.

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

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

version: '3.7'
services:
  b2b:
    ...
  admin-ui:
    image: ${NEXUS}/admin-ui:2023-08-10
    restart: always
    ports:
      - 1184:8080
    environment:
      TZ: ${TIME_ZONE}
      SYSTEM_NAME: ${SYSTEM_NAME}
      KC_REALM: ${KC_REALM}
      KC_URL: ${KC_URL}
      KC_SSL_REQUIRED: ${KC_SSL_REQUIRED}
      KC_CLIENT: b2b-admin-ui
    volumes:
      - ./logs/b2b-admin-ui:/var/log/nginx
    depends_on:
      - b2b

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
SYSTEM_NAME="Meine Test B2B"
KC_REALM=b2b
KC_URL=http://host.docker.internal:9000/auth/
KC_SSL_REQUIRED=none

Bei der b2b-tomcat Konfiguration handelt es sich exakt um die gleiche Konfiguration wie bei der B2B-UI.

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

./admin-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 B2B-Admin-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	b2b-admin-ui

Als gesamte Datei

Diese Datei konfiguriert die Anbindung der B2B-Admin-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": "b2b-admin-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.

./admin-ui/nginx.conf

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

Sie kann aber über die folgenden Umgebungsvariablen individuell angepasst werden:

ENV PORTAL_UI_URL="http://portal-ui:8080"  # URL mit der die B2B-Admin-UI auf die Portal-UI zugreifen kann.
ENV B2B_URL="http://b2b:8080"  # URL mit der die B2B-Admin-UI auf das B2B Backend zugreifen kann.
ENV NOTIFICATION_URL="http://notification:8080"  # URL mit der die B2B-Admin-UI auf das Notification Backend zugreifen kann.
ENV REVISION_URL="http://revision:8080"  # URL mit der die B2B-Admin-UI auf das Revision Backend zugreifen kann.
ENV AS4_ADDRESS_URL="http://as4-address-service:8080"  # URL mit der die B2B-Admin-UI auf den AS4 Address Service zugreifen kann.
ENV SERVICE_PATH=/B2B-Admin-UI  # URL-Pfad zur B2B-Admin-UI. Achtung: Eine Änderung hier muss in jeder UI Konfiguration entsprechend berücksichtigt werden.
ENV SYSTEM_NAME=B2B  # Angezeigter Name in der UI
ENV BACKGROUND_COLOR="#008ECC"  # Farbe der UI
ENV ACTIVATE_USER_MESSAGES="true"  # Wird das Feature zur Benutzerbenachrichtigung eingesetzt?
ENV KC_CLIENT=b2b-admin-ui  # Keycloak resource / client name
ENV KC_SSL_REQUIRED=none  # Keycloak ssl-required
ENV AS4_STYLE="false"  # Wird die UI auch für AS4 eingesetzt?

./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-Admin-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
  "as4AddressServiceUrl": "${SERVICE_PATH}/api/as4-address/",
  "as4Style": "${AS4_STYLE}",
  "backendUrl": "${SERVICE_PATH}/api/"
}

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 docker container (Admin-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 Konfiguration

Keycloak Client Configuration

Für die Admin-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. b2b-admin-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.

View Me Edit Me