Beschreibung zu eigenen PKS Installation (On-Premise)

Vorbereitende Fragen/Überlegungen

Wird docker und/oder docker-compose verwendet? (Empfohlene Installation!)
Welche PKS Datenbank soll verwendet werden? (Empfehlung: Postgres. Aktuell unterstützt: Postgres, Oracle, MSSQL - weitere Datenbanken auf Anfrage). Hinweis: Bei einer on-premise Installation ist der Kunde für die Datenbank (Wartung, Sicherung etc.) selbst verantwortlich.
Wird Keycloak (wie für die B2B UI) verwendet? (Gleiches) Keycloak wird für den PKS zwingend benötigt!
Wird ein Treafik verwendet? (Empfohlen)

Vorbereitung

Bereitstellung der Datenbank mit SQL Userdaten für das PKS. Die Datenbank-Tabellen werden dann beim Start des PKS Backends durch dieses selbstständig (per Flyway) angelegt. Der Datenbank User des PKS Backends benötigt dafür entsprechende DDL Berechtigung zur Erstellung von Tabellen.

Installation der Services und Infrastruktur

Installation mit Docker

Wir liefern ein docker-services-environment zur Installation aus (Umgebung zur Kunden-Installation vergleiche mit Entwicklungsumgebung - interne Links, können durch uns bereit gestellt werden), welches ein vorkonfiguriertes Set an benötigten Services mit einem docker-compose File bereitstellt. Die docker-compose sieht dabei exemplarisch wie folgt aus:

version: '3.7'
   
networks:
  default:
    external:
      name: localpks
   
services:
  pks:
    image: ${NEXUS_ERP}/pks/contact-sheet-service:${PKS_VERSION}
    restart: always
    depends_on:
      - pks-database
    ports:
      - 8080
    environment:
      - TZ=Europe/Berlin
      - PKS_DATABASE_URL=${PKS_DATABASE_URL}
      - PKS_DATABASE_USER=${PKS_DATABASE_USER}
      - PKS_DATABASE_PASSWORD=${PKS_DATABASE_PASSWORD}
      - PKS_CLIENT_ILN=${PKS_CLIENT_ILN}
      - PKS_CLIENT_MARKET_ROLE=${PKS_CLIENT_MARKET_ROLE}
      - PKS_PARTIN_FORMAT_CHANGE=${PKS_PARTIN_FORMAT_CHANGE}
      - B2B_URL=${B2B_URL}
      - B2B_BASIC_USER=${B2B_BASIC_USER}
      - B2B_BASIC_PASSWORD=${B2B_BASIC_PASSWORD}
    volumes:
      - ./config/pks-backend/application.properties:/workspace/BOOT-INF/classes/application.properties
      - ./config/pks-backend/keycloak.json:/workspace/BOOT-INF/classes/keycloak.json
      - ./logs/pks-backend:/workspace/logs
    logging:
      driver: "json-file"
      options:
        max-size: "20m"
        max-file: "10"
    extra_hosts:
      - ${HOST}:172.17.0.1
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.pks.rule=Host(`${HOST}`) && PathPrefix(`/pks`)"

  pks-ui:
    image: ${NEXUS_ERP}/pks/contact-sheet-service-ui:${PKS_UI_VERSION}
    restart: always
    depends_on:
      - pks
    volumes:
      - ./config/pks-ui/keycloak.json:/usr/share/nginx/html/contact-sheet-service-ui/assets/config/keycloak.json
      - ./config/pks-ui/nginx.conf:/etc/nginx/nginx.conf
      - ./config/pks-ui/system.json:/usr/share/nginx/html/contact-sheet-service-ui/assets/config/system.json
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.pks-ui.rule=Host(`${HOST}`) && PathPrefix(`/contact-sheet-service-ui`)"

  edi-json-converter:
    image: ${NEXUS_ERP}/edi-json.converter:${EDI_JSON_CONVERTER_VERSION}
    hostname: edi-json-converter
    restart: always
    environment:
      - TZ=Europe/Berlin
      - JAVA_OPTS= -Xmx4g -XX:+ExitOnOutOfMemoryError
    volumes:
      - ./logs/edi-json.converter:/logs
      - /etc/localtime:/etc/localtime:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.edi-json-converter.rule=Host(`${HOST}`) && PathPrefix(`/edijsonconverter`)"

Mit dem dazugehörigen Environment Parameter Konfigurations-File, welches exemplarisch wie folgt aussieht:

# Docker registries
NEXUS_ERP=docker-nob-erp.next-level-apps.com
   
## Database configuration
PKS_DATABASE_URL=jdbc:postgresql://pks-database:5432/pks?currentSchema=pks
PKS_DATABASE_USER=postgres
PKS_DATABASE_PASSWORD=password
   
# PKS client configuration
PKS_CLIENT_ILN=9900000000001
## supported values: LF, NB, MSB, BKV, BIKO, UENB, ESA
PKS_CLIENT_MARKET_ROLE=NB
## supported values: FU2204 (PARTIN 1.0), FU2210 (PARTIN 1.0a), FU2304 (PARTIN 1.0b), FU2310 (PARTIN 1.0c)
#PKS_PARTIN_FORMAT_CHANGE=FU2210
   
# B2B configuration
B2B_URL=http://b2b:8080/b2bbp-engine/
#B2B_BASIC_USER=
#B2B_BASIC_PASSWORD=
   
# PKS backend
PKS_VERSION=2022-08-29
# PKS UI
PKS_UI_VERSION=2022-08-25
   
# edi-json.converter
EDI_JSON_CONVERTER_VERSION=2210.1.0
   
HOST=host.docker.internal

Der PKS Backend Container bekommt zudem noch ein (standardisiertes mit Umgebungsvariablen versehenes) application.properties File sowie die keycloak.json seines Clients hinein gemountet. Die PKS UI benötigt die keycloak.json seines Clients als File sowie die nginx.conf mit der Konfiguration der URL und des Backends und eine system.json für den angezeigten Mandanten.

Bereitgestelltes docker-services-environment an einen gewünschten Ort auf Server ablegen und überprüfen welche Services/Einstellungen aus der docker-compose benötigt oder system-spezifisch angepasst werden müssen.
Konfiguration der Clients, Benutzer und Berechtigungen in der Keycloak Administration, siehe unten Abschnitt Einrichtung Keycloak.
Eigene Konfigurationen im env File und (sofern nötig) der unter /config liegenden Files eintragen. Hierbei muss u.a. die Datenbankverbindung und die keycloak.json Konfigurationen exportiert werden.
Start der Docker Services mit dem folgenden Befehl aus dem Verzeichnis der docker-compose.yml:
```
docker-compose up -d
```
Hierbei findet erst ein Pull der Docker Images aus unserer Registry statt (sofern noch nicht vorhanden) und dann ein Bau und Start der Container. Beim erstmaligen Pull der Docker Images von unserer Docker Registry (docker-nob-erp.next-level-apps.com) muss zuvor einmalig ein Login mit den von uns bereit gestellten Kunden-User Daten nach Bezug des PKS
Überprüfen, ob Services sauber gestartet sind:
1. Ist die Swagger-UI des PKS Backends erreichbar (unter http://PKS-Backend-Server:PKS-Backend-Port/PKS-Backend-Kontext-Pfad/swagger-ui.html z.B. http://localhost:8080/pks/swagger-ui/index.html)? Falls nein, schaue in die PKS Backend (Docker) Log-Files.
2. Ist die PKS-UI erreichbar (unter http://PKS-UI-Server:PKS-UI-Port/PKS-UI-Kontext-Pfad/pks z.B. http://localhost:8081/contact-sheet-service-ui/pks))? Falls nein, schau in die PKS UI (Docker) Log-Files.
3. Funktioniert die PKS-UI und erreicht sie das PKS Backend, d.h. können eigene Kontaktdaten eingegeben und erfolgreich gespeichert werden sowie bereits empfangene Partner Kontakt-Daten abgerufen werden? Falls nein: Schau in die Netzwerkanalyse des Browsers (F12) beim Laden der PKS-UI und ggf. in die Docker Log-Files des PKS Frontends und Backends. Die Konfiguration des Backends wird in der config/pks-ui/nginx.conf des Frontends im proxy_pass der REST API angegeben.
Anbindung an die B2B zum PARTIN Empfang und Versand.

Installation ohne Docker

Es wird empfohlen das PKS mit Docker zu installieren.

Vorbereitung

Was wird benötigt?

PKS Backend, PKS Frontend (werden von uns zum Download bereitgestellt)
Java 17
(leere) Datenbank. Aktuell unterstützt: Postgres (empfohlen), Oracle, MSSQL
nginx

Schritte der Installation

PKS Backend und Frontend herunterladen.
Anlegen der Keycloak Clients für das PKS Frontend und Backend, siehe Einrichtung Keycloak.

application.properties Datei anlegen und befüllen, wie hier exemplarisch gezeigt. Die Keycloak Einstellungen für das Backend werden dabei ebenfalls in dieser Datei angegeben. Die eigenen Konfigurationen können dabei aus der Keycloak Administration -> Clients -> “PKS Backend Client” -> Installation -> keycloak.json entnommen werden.

# Swagger-ui
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.operationsSorter=method
   
# PKS database
#spring.datasource.url=${PKS_DATABASE_URL}
#spring.datasource.username=${PKS_DATABASE_USER}
#spring.datasource.password=${PKS_DATABASE_PASSWORD}
# example values for local dev postgres (default)
spring.datasource.url=jdbc:postgresql://localhost:6432/pks?currentSchema=pks
spring.datasource.username=postgres
spring.datasource.password=postgres
spring.flyway.locations=classpath:/db/migration/postgres
spring.jpa.hibernate.ddl-auto=validate
# example values for local dev oracle
#spring.datasource.url=jdbc:oracle:thin:@localhost:1522/orcl
#spring.datasource.username=pks
#spring.datasource.password=password
#spring.flyway.locations=classpath:/db/migration/oracle
#spring.jpa.hibernate.ddl-auto=validate
# example values for local dev mssql
#spring.datasource.url=jdbc:sqlserver://localhost:1433;DatabaseName=pks;trustServerCertificate=true;username=admin;password=password
#spring.flyway.locations=classpath:/db/migration/mssql
#spring.jpa.properties.hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually
#spring.jpa.hibernate.ddl-auto=none

#server.port=9080

# PKS global application properties
pks.client.iln=9900000000001
## supported values for client market roles: LF, NB, MSB, BKV, BIKO, UENB, ESA
pks.client.marketRole=NB
## use, if PARTIN of fixed format-version should be created, supported values: FU2204 (PARTIN 1.0), FU2210 (PARTIN 1.0a), FU2304 (PARTIN 1.0b), FU2310 (PARTIN 1.0c)
#pks.partin.format-change=FU2210
server.servlet.context-path=/pks
spring.main.allow-circular-references=true
management.endpoint.info.enabled=true
management.endpoints.web.exposure.include=info
logging.file.path=logs
   
# B2B configuration
pks.b2b.b2bUrl=http://localhost:8080/b2bbp-engine
#pks.b2b.basicUserName=
#pks.b2b.basicPassword=
   
# Keycloak configuration (from keycloak.json of the PKS backend Keycloak client)
keycloak.realm=master
keycloak.resource=pks
keycloak.auth-server-url=http://localhost:
## use 'none' instead of 'external'
keycloak.ssl-required=none
keycloak.credentials.secret=
keycloak.confidential-port=0

Das Backend kann über eine start.bat ausgeführt werden:
```
java -cp contact-sheet-service.jar org.springframework.boot.loader.PropertiesLauncher --spring.config.location="application.properties"
```
Je nach Ordner Struktur kann es sein, dass die Pfade der Dateien noch angepasst werden müssen. Wenn das Backend erfolgreich installiert wurde, sollte dieser Link zur Swagger-UI der REST Schnittstellen aufgerufen werden können http://localhost:8080/contact-sheet-service/swagger-ui/index.html (oder alternativ konfigurierte Url zum PKS Backend).
Zur Installation des Frontends wird ebenfalls zunächst dessen Keycloak Konfiguration benötigt. Diese kann in der Keycloak Administration exportiert werden, unter Clients -> “PKS UI Client” -> Installation bei “Format Option” das Format “Keycloak OIDC JSON” auswählen und den Inhalt kopieren. Diesen dann im Frontend Verzeichnis unter assets/config/keycloak.json einfügen und den alten Inhalt ersetzen. Achtung: “ssl-required” muss ggf. auf “none” gesetzt werden!
PKS Frontend im nginx Verzeichnis unter nginx/html ablegen.

In nginx/conf muss die nginx.conf angepasst werden. Standardmäßig ist der Port 80, kann jedoch angepasst werden (muss dann auch im Keycloak Client angepasst werden). Außerdem muss unter server noch der proxy fürs Backend gesetzt werden:

#proxy for rest api call
       location /contact-sheet-service-ui/api/ {
               #proxy pass need to change
               proxy_pass   http://<PKS-Backend-Server>:<PKS-Backend-Port>/<PKS-Backend-Kontext-Pfad>/;
               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 800G;
       }

nginx.exe starten. Es sollten im Task-Manager unter Details zwei nginx Prozesse zu sehen sein.
Über http://PKS-UI-Server/PKS-UI-Kontext-Pfad z.B. http://localhost/contact-sheet-service-ui/ die Oberfläche aufrufen und Funktionen testen.
Anbindung an die B2B zum PARTIN Empfang und Versand.

Einrichtung Keycloak

Clients

PKS Backend

Für das PKS Backend muss (je Mandant/ILN) ein eigener Client mit den folgenden exemplarischen Einstellungen im Keycloak angelegt werden:

Um vom PKS erzeugte edi-json PARTINs -> B2B zu schicken (per OAuth2 siehe BTOB-8284) , muss dem PKS Backend Client unter “Service Account Roles” die Rolle “B2B-Edijson-Write” zugewiesen werden. Damit der Reiter zu sehen ist, muss an dem Client zuvor die Eigenschaft “Service Account Enabled” zu ON gesetzt werden.

PKS Frontend

Für das PKS Frontend muss ebenfalls (je Mandant/ILN) ein eigener Client mit den folgenden exemplarischen Einstellungen im Keycloak angelegt werden:

B2B (Tomcat) Backend

Um aus der B2B edi-json PARTINs -> PKS zu schicken, muss dem verwendeten Client (b2b-tomcat) unter “Service Account Roles” die Rolle PKS-PartnerContactData-Write zugewiesen werden. Damit der Reiter zu sehen ist, muss an dem Client zuvor die Eigenschaft “Service Account Enabled” zu ON gesetzt werden.

Rollen und User Gruppen/Berechtigungen

Die PKS-Rollen sind unter Keycloak-Rollen aufgelistet. Damit ein User in der UI den PKS sieht und/oder die entsprechenden Operationen durchführen kann, muss dieser in der Keycloak Administration die entsprechenden Rollenberechtigungen bekommen.

Integration in die Portal-UI

Um auch in der Portal-UI (je PKS Instanz) einen Absprung verfügbar zu haben, muss die portal-config.json der Portal-UI um den Eintrag der PKS UI erweitert werden:

    {
      "uiUrl": "<pks ui server url>/contact-sheet-service-ui/",
      "uiRequiredRole": "PKS-PartnerContactData-Read",
      "uiName": "PKS UI LF",
      "picturePath": "/B2B-Portal-UI/assets/config/images/p-pks.jpg",
      "iconName": "<pks portal server url>/B2B-Portal-UI/assets/config/icons/pks.svg",
      "description": "PARTIN Kontaktdatenblatt Service (LF 9900000000001)"
    },
    ...

Icon pks.svg und Bild p-pks.jpg müssen dazu in der Portal-UI an die entsprechende Stelle gemountet werden:

sevices:
  ...
  portal-ui:
    ...
    volumes:
      ...
      - <server-path>/p-pks.jpg:/usr/share/nginx/html/B2B-Portal-UI/assets/config/images/p-pks.jpg
      - <server-path>/pks.svg:/usr/share/nginx/html/B2B-Portal-UI/assets/config/icons/pks.svg

Damit die User die Kachel sehen und Zugang zum PKS haben müssen diese dann mindestens der Rolle PKS-PartnerContactData-Read im Keycloak zugeordnet sein. Hinweis: Damit die Änderungen in der Portal-UI aktualisiert müssen die UI Docker Container neu erstellt werden.

Unterstützung mehrerer Mandanten (= ILNs)

Im PKS findet eine Mandantentrennung “per infrastructure” statt. Eine einzelne PKS Instanz ist dabei nur Single-Mandantenfähig. Mehrere Mandanten werden dadurch unterstützt, indem der PKS je Mandant mehrfach (gleich) installiert wird. Dazu zählen PKS Backend, Frontend und Datenbank. Diese Lösung ist insbesondere aus Sicht des Datenschutzes und der Datenhaltung günstig.

Hinweis: Der edi-json.converter muss dabei nicht dupliziert werden. Er ist ein reiner Mapping-Service (EDIFACT <-> edi-json) in der Backend Kommunikation mit der B2B. Dieser kann höchstens zur Performance-Steigerung bei sehr hohen Nachrichtenvolumen skaliert werden.

View Me Edit Me

Installation des PKS

Vorbereitende Fragen/Überlegungen

Vorbereitung

Installation der Services und Infrastruktur

Installation mit Docker

Installation ohne Docker

Vorbereitung

Schritte der Installation

Einrichtung Keycloak

Clients

PKS Backend

PKS Frontend

B2B (Tomcat) Backend

Rollen und User Gruppen/Berechtigungen

Integration in die Portal-UI

Unterstützung mehrerer Mandanten (= ILNs)