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