IRIS Installation (Windows)

Hinweis zur Installation auf Windows

Die hier formulierte Installationsanleitung beschreibt die Installation von IRIS auf einem Windows System.

Allerdings möchten wir an dieser Stelle darauf hinweisen, dass die Installation unter Docker die simplere Methode zur Installation von IRIS ist.

Im Docker-Container sind diverse Dienste schon vorbereitet, welche hier manuell installiert und konfiguriert werden müssen, dazu zählen u.a.:

• MariaDB
• Interne Zertifizierungsstelle (interne Root CA)
• Reverse Proxy / Webserver

Eine Installation unter Windows ist nur zu empfehlen, wenn man sich mit den o.g. Diensten / Tools bereits sehr gut auskennt.

MariaDB

Für die Installation von IRIS wird eine installierte MariaDB vorausgesetzt:

https://mariadb.org/

Wir testen IRIS hierbei immer gegen die letzte LTS-Version von MariaDB. Zum jetzigen Zeitpunkt (11.12.2023) ist das die Version 10.11.

Zur Administration der Datenbank können Sie ein Tool Ihrer Wahl nehmen, z.B. DBeaver, HeidiSQL oder das bei der Installation mitgelieferte Kommandozeilentool mysql.

Datenbanken

Zum Anlegen der Datenbanken können Sie folgendes Script als root User ausführen:

create database iris_common character set = 'utf8mb4' collate 'utf8mb4_general_ci';
create database iris_account character set = 'utf8mb4' collate 'utf8mb4_general_ci';
create database iris_shipping character set = 'utf8mb4' collate 'utf8mb4_general_ci';

User

Zur besseren Sicherheit sollten jede Datenbank mit einem eigenen User versehen werden, wobei jeder User nur auf diese eine Datenbank Zugriff hat.

Bitte verwenden Sie ein sicheres Passwort, sowie für jeden Benutzer ein anderes Passwort, und ersetzen Sie es in den Befehlen unten.

Falls Sie die MariaDB und IRIS auf unterschiedlichen Servern installieren, dann ersetzen Sie bitte den Teil @'localhost' durch die IP Adresse, wo IRIS installiert wird oder eine geeignete Wildcard, z.B. @'10.0.0.15' oder @'10.0.0.%'

-- User for iris_common. Please replace the password with a secure random password
create user 'iris_common'@'localhost' identified by 'secure_password_for_iris_common_to_be_replaced';
grant all on iris_common.* to 'iris_common'@'localhost';

-- User for iris_account. Please replace the password with a secure random password
create user 'iris_account'@'localhost' identified by 'secure_password_for_iris_account_to_be_replaced';
grant all on iris_account.* to 'iris_account'@'localhost';

-- User for iris_shipping. Please replace the password with a secure random password
create user 'iris_shipping'@'localhost' identified by 'secure_password_for_iris_shipping_to_be_replaced';
grant all on iris_shipping.* to 'iris_shipping'@'localhost';

flush privileges;

Verschlüsselung der Verbindung

Die Verbindung zur MariaDB muss mit TLS/SSL abgesichert werden.

Hierzu können Sie nach offizieller Anleitung vorgehen:

https://mariadb.com/kb/en/securing-connections-for-client-and-server/

Zum Erstellen des Zertifikats verwenden Sie bitte Ihre interne Zertifizierungs-Stelle (interne Root CA).

Bitte prüfen Sie die verschlüsselte Verbindung bevor Sie fortfahren.

Installation iris-account

Sie erhalten das Setup von iris-account von unserem Support.

Installation

Für die Erstinstallation folgen Sie bitte dem Installer. Im Folgenden nehmen wir eine Installation auf C:\Heidler\iris\account an. Sollte Ihre Installation abweichen, ersetzen Sie bitte die Pfade entsprechend.

Datenbank-Verbindung

Zunächst muss die Verbindung zur Datenbank konfiguriert werden. iris-account benötigt eine Verbindung zu den Datenbanken iris_account und iris_common.

Sie finden die vorbereiteten Konfigurationsdateien unter: C:\Heidler\iris\account\config\database

Hier bitte die zwei Dateien kopieren und die Endung .example entfernen.

Danach bitte die Konfigurationsdateien anpassen. Die Dateien selbst enthalten eine Dokumentation und Erklärung zu jedem Parameter.

Wichtig: .properties Dateien können Sonderzeichen beinhalten, diese werden mit einem \ escaped. Sollten Sie einen Backslash benötigen (z.B. als Teil der Pfadangabe des Zertifikates), dann müssen Sie dies auch mit einem \ escapen. Beispiel:

serverCertificate=C:\\Heidler\\iris\\ssl\\ca.crt

Port

Standardmäßig starten iris-account einen HTTP-Webservice auf Port 9710.

Zum Ändern des Ports editieren Sie bitte die Datei: C:\Heidler\iris\account\config\service.properties

Erster Start

Sie können nun iris-account testweise starten.

Nach dem Start erhalten Sie eine Log-Datei unter: C:\Heidler\iris\account\logs\service.log

Wenn alles erfolgreich gestartet wurde, dann erhalten Sie einen Eintrag, der so ähnlich lautet:

2023-02-08 17:22:38.926 -08 WARN  [main] (init.ServiceInitializer:166) - A new user has been created.:
Username: root@localhost
Password: P6oV-GK3GYsdnn_5usDg1tBmn00
Please login with this user and change your password immediately!

Bitte notieren Sie sich diesen Benutzer + Passwort umgehend.

HTTPS

Um HTTPS für iris-account zu aktivieren, hinterlegen Sie bitte das Server-Zertifikat im X.509 Format und den Private-Key im PKCS#8 Format unter folgenden Dateinamen:

C:\Heidler\iris\account\config\server-cert.pem

C:\Heidler\iris\account\config\server-privatekey-pkcs8.pem

Die Zertifikate müssen Sie mit Ihrer internen Zertifizierungsstelle erstellen (interne Root CA).

Nach dem Hinterlegen starten Sie bitte den Dienst neu.

Im Log sollten Sie dann nach dem Neustart diesen Log-Eintrag finden:

2023-02-08 17:27:44.367 -08 INFO  [main] (rest.WebServer:88) - Starting https server on port 9710

Installation iris-shipping

Sie erhalten das Setup von iris-shipping von unserem Support.

Installation

Für die Erstinstallation folgen Sie bitte dem Installer. Im Folgenden nehmen wir eine Installation auf C:\Heidler\iris\shipping an. Sollte Ihre Installation abweichen, ersetzen Sie bitte die Pfade entsprechend.

Datenbank-Verbindung

Zunächst muss die Verbindung zur Datenbank konfiguriert werden. iris-account benötigt eine Verbindung zu den Datenbanken iris_shipping und iris_common.

Sie finden die vorbereiteten Konfigurationsdateien unter: C:\Heidler\iris\shipping\config\database

Hier bitte die zwei Dateien kopieren und die Endung .example entfernen.

Danach bitte die Konfigurationsdateien anpassen. Die Dateien selbst enthalten eine Dokumentation und Erklärung zu jedem Parameter.

Wichtig: .properties Dateien können Sonderzeichen beinhalten, diese werden mit einem \ escaped. Sollten Sie einen Backslash benötigen (z.B. als Teil der Pfadangabe des Zertifikates), dann müssen Sie dies auch mit einem \ escapen. Beispiel:

serverCertificate=C:\\Heidler\\iris\\ssl\\ca.crt

Port

Standardmäßig starten iris-shipping einen HTTP-Webservice auf Port 9720.

Zum Ändern des Ports editieren Sie bitte die Datei: C:\Heidler\iris\shipping\config\service.properties

Erster Start

Sie können nun iris-shipping testweise starten.

Nach dem Start erhalten Sie eine Log-Datei unter: C:\Heidler\iris\account\logs\service.log

HTTPS

Um HTTPS für iris-account zu aktivieren, hinterlegen Sie bitte das Server-Zertifikat im X.509 Format und den Private-Key im PKCS#8 Format unter folgenden Dateinamen:

C:\Heidler\iris\shipping\config\server-cert.pem

C:\Heidler\iris\shipping\config\server-privatekey-pkcs8.pem

Die Zertifikate müssen Sie mit Ihrer internen Zertifizierungsstelle erstellen (interne Root CA).

Nach dem Hinterlegen starten Sie bitte den Dienst neu.

Im Log sollten Sie dann nach dem Neustart diesen Log-Eintrag finden:

2023-02-08 17:33:47.257 -08 INFO  [main] (rest.WebServer:88) - Starting https server on port 9720

Installation Frontend

Sie erhalten die Frontend-Dateien für IRIS von unserem Support.

Bitte entpacken Sie diese Dateien an einem Ort, wo Ihr Webserver / Reverse-Proxy Zugriff hat und diese veröffentlichen kann (z.B. C:\Heidler\iris\frontend).

Reverse Proxy + Web Server

Bitte installieren Sie einen geeigneten Reverse Proxy und Webserver, welcher die Anfragen aus dem Internet entgegennimmt und sowohl das Frontend ausliefern, als auch Anfragen an IRIS weiterleiten kann.

Der Reverse Proxy muss folgende Aufgaben übernehmen:

• Öffentlicher HTTPS-Server mit gültigem und anerkanntem HTTPS-Zertifikat
• Automatische Weiterleitung von HTTP-Anfragen auf HTTPS
• Auslieferung der statischen Frontend-Dateien (Inhalt vom Frontend-Vereichnis entspricht dem URL-Pfad)
  • z.B. https://<domain>/ zu [frontend]\index.html
  • z.B. https://<domain>/js/site.js zu [frontend]\js\site.js
• Umleitung aller Anfragen auf /account an iris-account, inkl. des URL-Teils /account
  • z.B. https://<domain>/account/validate zu https://<servername>:9710/account/validate
• Umleitung aller Anfragen auf /v2/hsc/shipping an iris-shipping, inkl. des URL-Teils /v2/hsc/shipping
  • z.B. https://<domain>/v2/hsc/shipping/echo/test zu https://<servername>:9720/v2/hsc/shipping/echo/test

Intern haben wir diese Konfiguration bereits mit nginx und auch IIS testen können.

Bitte beachten Sie allerdings, dass wir Ihnen keine Unterstützung bei der Konfiguration von externen Diensten geben können.