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 NUI) 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

Grundlegende Installation mit Docker

  1. Wir liefern ein docker-services-environment zur Installation aus, welches ein vorkonfiguriertes Set an benötigten Services mit einem docker-compose File bereitstellt.
    1. Bereitgestelltes docker-services-environment an einen gewünschten Ort auf Server ablegen.
    2. Überprüfen welche Services aus der docker-compose tatsächlich alle benötigt werden oder schon besitzt bzw. nicht benötigt ( pks-database, keycloak, traefik etc.) und Entfernen der nicht benötigten Services.
    3. Environment Konfiguration des Kunden im env File (und als nötig der unter /config liegenden Files) eintragen. Hierbei muss auch die Datenbank angegeben werden
  2. Start der Docker Services:
    1. Login an der Docker Registry mit den von uns bereit gestellten Kunden-User Daten nach Bezug des PKS.
    2. Konfiguration der Services, Benutzer und Berechtigungen in der Keycloak Administration.
    3. Ausführen der docker-compose und überprüfen, ob Services sauber gestartet sind. (Logs der Docker Container, UI erreichbar/benutzbar?)

Installation ohne Docker

Es wird empfohlen das PKS mit Docker zu installieren.

Vorbereitung

Was wird benötigt?

  • PKS Backend
  • PKS Frontend
  • Java 17
  • nginx

Schritte der Installation

  1. PKS Backend herunterladen (PrivateDL) und in der Keycloak Administration einen neuen Client für das Backend hinzufügen.

  2. application.properties Datei anlegen und befüllen. Die Keycloak Einstellungen für das Backend werden ebenfalls in dieser Datei angegeben.

# 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:5432/pks?currentSchema=pks 
#spring.datasource.username=
#spring.datasource.password=
# example values for local dev oracle
server.port=<Port auf dem das Backend laufen soll>
#spring.datasource.url=jdbc:postgresql://localhost:5432/pks
spring.datasource.username=postgres
spring.datasource.password=postgres
spring.flyway.locations=classpath:/db/migration/postgres
spring.jpa.hibernate.ddl-auto=validate

keycloak.realm=<Realm>
keycloak.resource=<client>
keycloak.auth-server-url=http://localhost:8080/auth/
keycloak.ssl-required=none
keycloak.credentials.secret=<secret>
keycloak.confidential-port=0

# PKS global application properties
pks.client.iln=<ILN>
## supported values for client market roles: LF, NB, MSB
pks.client.marketRole=NB

# B2B configuration
pks.b2b.b2bUrl=<B2B-URL>
pks.b2b.basicUserName=user
pks.b2b.basicPassword=password

server.servlet.context-path=/contact-sheet-service
spring.main.allow-circular-references=true
logging.file.path=logs

  1. Das Backend kann über eine start.bat ausgeführt werden.
java -cp contact-sheet-service-1.x-LOCAL-SNAPSHOT.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:/contact-sheet-service/swagger-ui/index.html

  1. In der Keycloak Administration einen neuen Client und die Rollen für das Frontend hinzufügen.

  1. In der Keycloak Oberfläche unter “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!

  2. PKS Frontend im nginx Verzeichnis unter nging/html ablegen.

  3. 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://localhost:<Backend-Port>/contact-sheet-service/;
                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;
        }
  1. nginx.exe starten. Es sollten im Task-Manager unter Details zwei nginx Prozesse zu sehen sein.

  2. Über http://localhost/contact-sheet-service-ui/ die Oberfläche aufrufen

Anbindung an die B2B

Mit Schnell-Customizing

B2B Schnell-Customzing ( interner Link/kann von uns bereitgestellt werden), welches in die B2B über den Customizing-Upload hochgeladen werden kann. Achtung: Es muss dieses bereits vor dem Hochladen geprüft werden, ob dieses in einer kunden-individuellen B2B einfach hochgeladen werden kann (passen die Action bzw. Service IDs?).

Danach müssen noch manuell folgende Schritte durchgeführt werden:

  • Anpassung der Extensions zum Routing der Nachrichten in die Channel IN_PKS bzw. OUT_PKS. Dies sind im Standardfall die Extensions EXT_CHANNEL_DIST, GENERIC_EDICONDITION_DISTRIBUTION und GENERIC_EDICONDITION_DISTRIBUTION_OUT.
  • Im Idealfall sollte eine Erweiterung der GENERIC_EDICONDITION_DISTRIBUTION(_OUT) um die folgenden Einträge genügen:

“IN_PKS” (bzw. “OUT_PKS”) <== $messagecontext.FORMAT.type == “PARTIN”;

  • Anpassung der URLs aus dem Customizing (URL Service Eigenschaften der drei RestClientServices “EdiJson2EdifactMapper”, “ Edifact2EdiJsonMapper” und “PKS_IN”) zur Verbindung mit dem ausgerollten PKS Backend bzw. edi-json.converter.

Manuell

Falls die B2B Konfiguration manuell durchgeführt werden soll, dann sind grundsätzlich die folgenden Schritte in der Channel-Verarbeitung zu beachten:

  • Inbound:
    • (Volltextindizierung standardmäßig über Channel-Distribution)
    • Validierung
    • CONTRL Erzeugung/Versand
    • APERAK Erzeugung/Versand
    • EDIFACT nach edi-json Mapping (via RestClientService)
    • Übergabe ans PKS (ebenfalls via RestClientService)
  • Outbound:
    • edi-json nach EDIFACT Mapping (via RestClientService)
    • Volltextindizierung
    • Optional und nur für Testsysteme empfohlen: Ausgehende Validierung
    • Nachrichtenversand an Markt

Einrichtung Keycloak

Clients (PKS frontend/backend)

Weitere Doku folgt. Wir unterstützen gerne auf Anfrage!

Rollen and User Gruppen/Berechtigungen

Weitere Doku folgt. Wir unterstützen gerne auf Anfrage!

Unterstützung mehrerer Mandanten (= MPIDs)

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, Fronend und Datenbank. Diese Lösung ist insbesondere aus Sicht des Datenschutzes und der Datenhaltung günstig.

Hinweis: Der edi-json.converter zählt nicht dazu. Er ist ein reiner Mapping-Service (EDIFACT <-> edi-json) in der Backend Kommunikation mit der B2B. Dieser kann zur Performance-Steigerung bei sehr hohen Nachrichtenvolumen skaliert werden.

View Me   Edit Me