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

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

  2. 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.
  3. Konfiguration der Clients, Benutzer und Berechtigungen in der Keycloak Administration, siehe unten Abschnitt Einrichtung Keycloak.
  4. 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.
  5. 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

  6. Ü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.
  7. 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

  1. PKS Backend und Frontend herunterladen.

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

  3. 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
    
  4. 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).

  5. 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!

  6. PKS Frontend im nginx Verzeichnis unter nginx/html ablegen.

  7. 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;
           }
    
  8. nginx.exe starten. Es sollten im Task-Manager unter Details zwei nginx Prozesse zu sehen sein.

  9. Über http://PKS-UI-Server/PKS-UI-Kontext-Pfad z.B. http://localhost/contact-sheet-service-ui/ die Oberfläche aufrufen und Funktionen testen.
  10. 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

image

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