Installation Kieselstein ERP Server unter Windows

• 1: Update Kieselstein ERP Server von Version 0.2.x auf 1.x.x unter Windows

Den Kieselstein ERP Server auf einem frischen Windows installieren.

Installation Datenbankserver

Es werden aktuell ausschließlich PostgresQL Version 14 und 15 unterstützt. MS-SQL wird nicht unterstützt. Für eine eventuelle Konvertierung deiner MS-SQL Datenbank wende dich bitte an die Kieselstein ERP eG. Neuere PostgresQL Versionen können funktionieren, sind aber aktuell von uns nicht freigegeben.
Bei der Installation darauf achten, dass nur PostgresSQL Server und die Command Line Tools installiert werden.



Bei der Installation muss auch das Passwort für den User Postgres angegeben werden.
Hinweis: Es sollte ein sicheres Passwort verwendet werden, welches über einen Passwort-Generator erstellt wurde (Achtung das Passwort wird hier in folgenden Schritten noch benötigt!).

Java installieren

• Azul Java 11 mit FX installieren Siehe hierfür auch Java-Version.
• darauf achten, dass Java Home gesetzt wird
  
  
• Prüfen, dass Java auch installiert wurde durch Command Shell,

  Java -version
  

Setzen Environmentvariable

• path Erweiterung auf Postgres “?:\Program Files\pgAdmin 4\v6\runtime”
• KIESELSTEIN_DIST=?:\kieselstein\dist
• KIESELSTEIN_DATA=?:\kieselstein\data
• MAIN_DB_PASS=(Das oben definierte Datenbank-Passwort)
• DOC_DB_PASS=(Das oben definierte Datenbank-Passwort)

Optional kann auch die KIESELSTEIN_WILDFLY_CONFIG Umgebungsvariable gesetzt werden. Wichtig ist dabei das die Variable keine anderen Variablen beinhalten darf.

Bsp: KIESELSTEIN_WILDFLY_CONFIG=?:\kieselstein\data\wildfly

Es müssen dann noch einmalig folgende files vom wildfly ordner in den KIESELSTEIN_WILDFLY_CONFIG kopiert werden.

?:\kieselstein\dist\wildfly-26.1.2.Final\standalone\configuration

• application-roles.properties
• application-users.properties
• mgmt-groups.properties
• mgmt-users.properties

Danach noch einen Applikations-User mit \opt\kieselstein\dist\wildfly-26.1.2.Final\bin\add-user.bat hinzufügen.

Es gibt noch weitere optionale Environment-Variablen welche in der README.md Datei bei den Start-Scripten (im KIESELSTEIN_DIST/bin/) beschrieben sind.

Achtung: Damit die Umgebungsvariablen für den Kieselstein-Dienst funktionieren, müssen diese als Systemvariablen hinterlegt werden.

Installation Liquibase

Für die Datenbankmigrationen muss das Tool liquibase installiert werden.
Aktuelle Liquibase Version vom git Repository runterladen:
https://github.com/liquibase/liquibase/releases
Hier bis zu den Assets runterscrollen und dann den passenden (Windows-)Installer auswählen. Z.B.: liquibase-windows-x64-installer-x.x.x.exe

Den Installer am Server ausführen und durchklicken.
Bitte darauf achten, dass Add Liquibase to PATH angehakt bleibt.

Achtung nach der Installation von Liquibase müssen für die weiteren Arbeiten neue Eingabeaufforderungen (cmd) gestartet werden! Ein Neustart des Servers ist nicht erforderlich.

ACHTUNG

Das Liquibase ergänzt die Pfad-Angabe nur benutzerspezifisch.
Das bedeutet, wenn du danach das Update unter einem anderen Benutzer machst, hast du keinen Zugriff mehr.
Unsere Empfehlung:
Verschiebe die Pfad-Ergänzung von den Benutzervariablen in die Systemvariablen.

Installation Kieselstein ERP, Version (aktuelle Version):

Herunterladen aktuelle Kieselstein ERP Version

Siehe auch

Dist-Paket über die bestehende Installation entpacken (In der Windows Eingabeaufforderung cmd.exe) Beispiel:

tar -xvf <pfad-zum-dist-packet>.gz -C ?:\kieselstein\

Datenbank Initialisieren

Die installierte ?:\kieselstein\dist\bootstrap\liquibase\createdb.bat ausführen. Hier muss dann 4x das Passwort für den Postgres-Benutzer eingegeben werden.

In der Command Shell in das Verzeichnis navigieren und mit liquibase den update Befehl durchführen:

cd ?:\kieselstein\dist\bootstrap\liquibase
run-liquibase.bat update

Einrichten des Dienstes und starten des Servers

Mit Administrationsrechten das Install-Script ?:\kieselstein\dist\bootstrap\service\windows\install-kieselstein-services.bat ausführen.

NGINX Webserver (Optional)

Sollte für die REST-Schnittstelle ein eigener Port notwendig sein. Damit der Zugriff zum Beispiel über das Internet zur Verfügung gestellt werden kann oder bestehende Zeiterfassung-Terminals oder andere Anwendungen bereits den Port: 8280 verwenden, kann ein Nginx-Webserver als Proxy hierfür installiert werden.

Mit Administrationsrechten das Install-Script ?:\kieselstein\dist\bootstrap\service\windows\install-kieselstein-nginx-service.bat ausführen.

Für das Freischalten im Internet sollte auf jeden Fall ein SSL-Zertifikat noch hinterlegt werden (siehe hier auch Configuring HTTPS servers bzw. Nginx-Webserver)

Zum Überprüfen, ob der Nginx funktioniert und mit dem Kieselstein kommuniziert, kann die Url: http://(Name oder IP-Adresse des Servers):8280/kieselstein-rest/services/rest/api/v1/system/ping aufgerufen werden.

TODO Hinterfragen, ob die Config gleich ins richtige Verzeichnis vom Dist-Pack geladen werden kann oder ob das manuell gemacht werden muss.

läuft der Server?

bewährt hat sich, das Laufen des Servers in folgender Reihenfolge zu prüfen:

1. ?:\kieselstein\dist\wildfly-26.1.2.Final\standalone\deployments/
   Hier müssen für alle drei Dateien auch .deployed Dateien stehen
2. Prüfen ob die RestAPI geht:
   einen Browser starten, http://localhost:8080/kieselstein-rest-docs/ muss die Restapi Dokumentation bringen. Bzw. auch mit dem Nginx-Port http://localhost:8280/kieselstein-rest-docs/ aufrufen (falls Nginx-Installiert wurde).
3. Client starten und mit Admin, admin anmelden.
   

weiters zu tun

• Backup einrichten
• Einrichten der Zugriffe von anderen Rechner aus.

Server startet nicht, was tun?

Wenn du Daten von anderen Installationen übernimmst, muss beim ersten Start deines Servers der Index der Dokumentendatenbank neu aufgebaut werden. Dies wird grundsätzlich vom Server unterstützt. Es kann aber unter Umständen so lange dauern, dass der Server von sich aus abbricht.
D.h. gegebenenfalls den Server mehrfach starten und oder zusätzlich das Timeout temporär höher drehen. D.h. im launch-kieselstein-main-server(.bat)

Linux (ca Zeile 60)

MAIN_SERVER_OPTS="${MAIN_SERVER_OPTS} -Djboss.as.management.blocking.timeout=3600"

Windows (ca Zeile 90)

set MAIN_SERVER_OPTS=%MAIN_SERVER_OPTS% -Djboss.as.management.blocking.timeout=3600

hinzufügen. Erhöht das Timeout auf eine Stunde.

Server manuell stoppen / starten

Manchmal hat man in Windowsumgebungen das Problem, dass über die Dienste-Konsole der Kieselstein Service nicht endgültig gestoppt werden kann.
Mit den nötigen Administrator Rechten kann mit

net stop "Kieselstein Main Server"

Der Dienst gestoppt werden.

1 - Update Kieselstein ERP Server von Version 0.2.x auf 1.x.x unter Windows

Wenn eine bestehende Kieselstein Installation mit der Version 0.2.x vorhanden ist, können folgende Schritte für das Update auf Version 1.x.x durchgeführt werden.

Kieselstein Dienste deaktivieren

Dienste beenden

• Beide Kieselstein Dienste (Kieselstein Main Server & Kieselstein REST Server) beenden
  
• nun die Dienste deinstallieren, also:
  ?:\kieselstein\dist\bootstrap\service\windows\delete-kieselstein-services.bat

Backup des Kieselstein Dist-Verzeichnis erstellen

Das aktuell installierte Kieselstein in ein eigenes Verzeichnis mit der aktuellen Versionsnummer im Namen wegsichern.
Beispiel: C:\kieselstein nach C:\kieselstein-0.2.10 kopieren.

Neues Java Installieren

• Azul Java 11 mit FX installieren Siehe hierfür auch Java-Version.

• darauf achten, dass Java Home gesetzt wird
  

• Prüfen, dass Java auch installiert wurde durch Command Shell,

  Java -version
  

Altes Java Deinstallieren (optional)

Über “Programme hinzufügen oder entfernen” nach JDK Suchen und die Java 8 Version deinstallieren.

Achtung: Diesen Schritt nur durchführen, wenn auf dem Server sicher keine andere Anwendung mehr das Java 8 JDK benötigt!
Auf jeden Fall ist sicherzustellen, dass die JAVA_HOME Variable auf das Neue JDK 11 gesetzt wurde:

Nicht mehr benötigte Anwendungen entfernen

Bestehende Kieselstein Dienste deinstallieren

Dafür das Skript ?:\kieselstein\dist\bootstrap\service\windows\delete-kieselstein-services.bat mit Administrator Rechten ausführen.

Reports sichern

Damit die Anwender-Reports nach dem Update wieder zur Verfügung stehen, muss der Reports-Ordner in ein neues Verzeichnis kopiert werden.
Hier muss der bestehende ?:\kieselstein\dist\wildfly-12.0.0.Final\server\helium\report nach ?:\kieselstein\dist\wildfly-26.1.2.Final\kieselstein\reports kopiert werden.

WICHTIG: Dies muss vor dem Entpacken des neuen Dist-Packets erfolgen, damit neuere Versionen der Standard-Reports richtig nachgezogen werden.

ACHTUNG: Die Definitionen für dein JasperStudio entsprechend übertragen und auch die Einstellungen im Jasper Studio entsprechend anpassen.
Dies idealerweise, bevor du die nachfolgenden Verzeichnisse löschst.

• In Jasperstudio direkt.
  Eigenschaften des Projekts auf den neuen Pfad ändern.
  Z.B. von …?:\kieselstein\dist\wildfly-12.0.0.Final\server\helium\report auf ?:\kieselstein\data\reports zu ändern.
  Denke auch daran dass die .classpath entsprechend anzupassen ist
  und denke an die Verlagerung der .settings, bin und an das Neu-Schreiben des .projects für JasperStudio.

Im Verzeichnis bin solltest du auch die aktuelle kieselstein-ejb-1.0.3.jar anstatt der bisherigen ejb.jar verwenden.

Alte Programmdateien löschen

Folgende Ordner können nun komplett gelöscht werden:

• ?:\kieselstein\dist\apache-tomcat-8.5.93
• ?:\kieselstein\dist\bin
• ?:\kieselstein\dist\bootstrap
• ?:\kieselstein\dist\service
• ?:\kieselstein\dist\wildfly-12.0.0.Final

Installation Kieselstein ERP, Version (aktuelle Version):

Herunterladen aktuelle Kieselstein ERP Version

TODO Referenz auf die richtige Version setzen.

Siehe auch

Dist-Paket über die bestehende Installation entpacken (In der Windows Eingabeaufforderung cmd.exe) Beispiel

tar -xvf <pfad-zum-dist-packet>.gz -C ?:\kieselstein\

Datenbank Updaten

In der Command Shell in das Verzeichnis navigieren und mit liquibase den update Befehl durchführen:

cd C:\kieselstein\dist\bootstrap\liquibase
run-liquibase.bat update

Hinweis: Wenn die bestehende Kieselstein Version kleiner als 0.0.13 ist:

Dann muss dem Liquibase noch mitgeteilt werden, dass es bereit die Grund-Datenstruktur gibt, somit muss vor dem Befehl run-liquibase.bat update noch folgender Befehl aufgerufen werden: run-liquibase.bat changelog-sync --label-filter="0.0.12"

Einrichten des Dienstes und starten des Servers

Mit Administrationsrechten das Install-Script ?:\kieselstein\dist\bootstrap\service\windows\install-kieselstein-services.bat ausführen.

NGINX Webserver (Optional)

Die Kieselstein-REST Schnittstelle wurde mit dem Update in den Wildfly integriert und ist somit auch über den Port: 8080 erreichbar.

Sollte es notwendig sein, dass diese wie bisher über den Port 8280 erreichbar ist, kann hier ein Nginx-Webserver als Proxy vorgeschaltet werden (Siehe NGINX Webserver)

läuft der Server?

Siehe Läuft der Server
Es hat sich bewährt nach einem Update, insbesondere nach dem Wechsel der Java Version, den Server manuell zu starten. D.h. mit administrativen Rechten das
?:\kieselstein\dist\bin\launch-kieselstein-main-server.bat
auszuführen.

Beobachte hier die Ausgabe der Console. Erscheint hier:

2024-09-19 10:58:50,075 ERROR [org.jboss.msc.service.fail] (ServerService Thread Pool -- 82) MSC000001: Failed to start service jboss.ra.deployer."jackrabbit-jca-2.22.0.rar": org.jboss.msc.service.StartException in service jboss.ra.deployer."jackrabbit-jca-2.22.0.rar": WFLYJCA0046: Failed to start RA deployment [jackrabbit-jca-2.22.0.rar]
    at org.jboss.as.connector.services.resourceadapters.deployment.
    ...
Caused by: org.jboss.jca.deployers.common.DeployException: IJ020056: Deployment failed: jackrabbit-jca-2.22.0.rar
    ...
Caused by: java.lang.UnsupportedClassVersionError: Failed to link org/apache/jackrabbit/jca/JCAResourceAdapter (Module "deployment.jackrabbit-jca-2.22.0.rar" from Service Module Loader): org/apache/jackrabbit/jca/JCAResourceAdapter has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0

this version of the Java Runtime only recognizes class file versions up to 52.0

so bedeutet dies, dass du vermutlich noch Java 8 auf deinem Server verwendest.
Gegebenenfalls willst du auf deinem Server, warum auch immer, auch noch Java 8 verwenden und hast daher beide Java Versionen installiert.
In diesem Falle muss das JAVA_HOME im Start-Batch
(?:\kieselstein\dist\bin\launch-kieselstein-main-server.bat) gesetzt werden.
Z.B. schreibst du in Zeile 3 set JAVA_HOME=c:\Program Files\Zulu\zulu-11, also den Pfad auf dein Java 11 rein.

Dokumentendatenbank Workspace.xml anpassen

Wenn eine bestehende Dokumentendatenbank existiert, müssen hier folgende Parameter Werte (Achtung diese Werte sind 2x in der XML-Datei vorhanden) angepasst werden:

?:\kieselstein\data\jackrabbit\workspaces\default\workspace.xml

• driver: javax.naming.InitialContext
• url: java:/JRDS

Und folgende Parameter können gelöscht werden:

• user
• password

Beispiel:

Alte XML-Datei

<?xml version="1.0" encoding="UTF-8"?>
<Workspace name="default">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.DbFileSystem">
        <param name="driver" value="org.postgresql.Driver"/>
        <param name="url" value="jdbc:postgresql://${org.kieselstein.db-doc.host}:${org.kieselstein.db-doc.port}/${org.kieselstein.db-doc.name}"/>
        <param name="schema" value="postgresql"/>
        <param name="user" value="postgres"/>
        <param name="password" value="postgres"/>
        <param name="schemaObjectPrefix" value="ws_"/>
    </FileSystem>
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.bundle.PostgreSQLPersistenceManager">
        <param name="driver" value="org.postgresql.Driver"/>
        <param name="url" value="jdbc:postgresql://${org.kieselstein.db-doc.host}:${org.kieselstein.db-doc.port}/${org.kieselstein.db-doc.name}"/>
        <param name="user" value="postgres"/>
        <param name="password" value="postgres"/>
        <param name="schema" value="postgresql"/>
        <param name="schemaObjectPrefix" value="jcr_${wsp.name}_"/>
        <param name="externalBLOBs" value="false"/>
    </PersistenceManager>
    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
        <param name="path" value="${wsp.home}/index"/>
    </SearchIndex>
</Workspace>

Neue XML-Datei:

<?xml version="1.0" encoding="UTF-8"?><Workspace name="default">
    <FileSystem class="org.apache.jackrabbit.core.fs.db.DbFileSystem">
        <param name="driver" value="javax.naming.InitialContext"/>
        <param name="url" value="java:/JRDS"/>
        <param name="schema" value="postgresql"/>
        <param name="schemaObjectPrefix" value="ws_"/>
    </FileSystem>
    <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.PostgreSQLPersistenceManager">
        <param name="driver" value="javax.naming.InitialContext"/>
        <param name="url" value="java:/JRDS"/>
        <param name="schema" value="postgresql"/>
        <param name="schemaObjectPrefix" value="jcr_${wsp.name}_"/>
        <param name="externalBLOBs" value="false"/>
    </PersistenceManager>
    <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
        <param name="path" value="${wsp.home}/index"/>
    </SearchIndex>
</Workspace>

weiters zu tun

• Clients Updaten (diese benötigen jetzt auch Java 11) siehe auch
• Wenn Nginx nicht installiert wurde bei allen Zeiterfassung-Terminals oder anderen Programmen, welche die REST-Schnittstelle verwenden, den Port auf 8080 ändern.

Empfehlung:
Insbesondere für die Tests in der ersten Zeit, sollte für ein eventuelles Fallback auf den Clients sowohl die Version für den Java 8 Server als auch für den Java 11 Server parallel vorgehalten werden. Damit man, im schlimmsten Falle, schnell auf die Vorgängerversion zurückwechseln kann.