ROOTS Server

ROOTS Server

Einleitung

ROOTS Server ist ein OSGi-basiertes Boot System für Entwicklung und Ausführung von OSGi Subsystemen.
ROOTS ECP Server ist der um die zur Entwicklung und Ausführung eventgesteuerter Anwendungen (RApps) erweiterter ROOTS Server. ECP steht hierbei für event centric processing und ist das Eventsystem das allen RApps zur Grunde liegt.

Im ersten Kapitel wird eine kurze Anleitung zur Installation und Starten/Stoppen des ROOTS ECP Servers gegeben.
Das darauf folgende Kapitel geht auf die Struktur und Konfigurationsmöglichkeiten des ROOTS Servers ein.
Im letzten Kapitel wird die Nutzung der ROOTS Web Konsole zur Prüfung des ROOTS Server Status' gegeben.

Kurzanleitung zur Installation des ROOTS ECP Servers

In diesem Kapitel wird der Bezug, die Installation, das Starten und Stoopen des ROOTS ECP Servers sowie Statusprüfung beschrieben.
Das Verständnis für Administration von Betriebsystemen, insb. für Rechtevergabe und die Verwendung von Diensten/Daemon's, wird vorausgesetzt.

Der ROOTS ECP Server besteht aus dem ROOTS Server und den ECP RApps.
Um dem Anwender die Installation zu erleichtern bzw. das Herunterladen und Installieren der einzelnen ECP RApps aus dem RAppository zu ersparen, ist an der o.g.
Lokalität nicht der ROOTS Server sondern der ROOTS ECP Server zu finden.
Die Beschreibung der ECP RApps ist zu finden im Abschnitt "ROOTS und ROOTS ECP Server".

Bezugsquelle des ROOTS ECP Servers

Der ROOTS ECP Server kann unter
http://kachel.de.com/svn/public/df/trunk/ROOTS/releases
heruntergeladen werden.

Der Name der Datei gibt Aufschluss über die ROOTS Releaseversion sowie das Betriebssystem:
RootsECPServer<Betriebsystem>_<Releaseversion>.zip

Aktuell wird ROOTS ECP Server für Win64 und MacOS64 Betriebsystem bereit gestellt. ROOTS ECP Server für Ubuntu ist in Vorbereitung.

Um den ROOTS Server ohne die ECP RApps zu starten siehe Kapitel "ROOTS Server und ROOTS ECP Server"

Installation des ROOTS ECP Servers

Folgende Schritte müssen ausgeführt werden um ROOTS ECP Server zu installieren:

ROOTS ECP Server von der im Abschnitt "Bezugsquelle des ROOTS ECP Servers" genannten Lokalität herunterladen.
Die Archivdatei in das gewünschte Verzeichnis (im Folgenden <ROOTSECPServer> genannt) entpacken.

Hiermit ist die Installation des ROOTS Servers abgeschlossen.

ROOTS ECP Server kann auch als Service (Dienst bzw. Deamon) gestartet werden.

Um den Server unter Windows als Dienst starten zu können, muss er zunächst als Dienst installiert werden:

Die Datei <ROOTSECPServer>/RootsServiceInstall.bat

Unter MacOS ist eine Installation eines Deamons nicht nötig.

Starten des ROOTS ECP Servers

Der installierte ROOTS Server wird durch das Ausführen der Datei <ROOTSECPServer>/RootsServerStart.bat (Windows) bzw. <ROOTSECPServer>/RootsServerStart.sh (Mac OS) gestartet. Nach dem Start ist die ROOTS Shell zu sehen:

Nach dem Start des ROOTS Servers wird empfohlen das Kommando rstate in der ROOTS Shell auszuführen, welches den Zustand des gestarteten Roots Servers anzeigt (wie in der obigen Abbildung zu sehen).

Falls ROOTS ECP Server als Dienst unter Windows installiert wurde, kann er alternativ als Dienst gestartet werden. Dies wird entweder über die üblichen, betriebssystemspezifischen Wege oder über das Ausführen der Datei <ROOTSECPServer>/RootsServiceStart.bat durchgeführt.

Unter MacOS kann der ROOTS Server beim Starten des Systems als Deamon gestartet werden.

Ist der ROOTS ECP Server gestartet, so ist die ROOTS Shell über die ROOTS Web Konsole erreichbar.
Zum Starten der ROOTS Web Konsole siehe Abschnitt "ROOTS Web Konsole".
Nach dem Starten der ROOTS Web Konsole kann die Roots Shell geöffnet werden:

In der ROOTS Shell kann das Kommando rstate ausgeführt werden:

Stoppen des ROOTS ECP Servers

Der gestartete ROOTS ECP Server wird durch das Schließen der ROOTS Shell gestoppt.

Ist der ROOTS ECP Server als Dienst unter Windows gestartet, kann er über die üblichen, betriebssystemspezifischen Wege oder über das Ausführen der Datei <ROOTSECPServer>/RootsServiceStop.bat (Windows) gestoppt werden.

Unter MacOS werden die betriebsspezifischen Mechanismen zur Handhabung von Deamons zum Stoppen des ROOTS ECP Server Deamons verwendet.

ROOTS Server und ROOTS ECP Server

In diesem Kapitel wird die Kentniss der grundlegenden ROOTS Begriffe und Mechanismen vorausgesetzt.

ROOTS ECP Server ist der um folgende RApps erweiterter ROOTS Server:

Console: ROOTS ECP console server mit session und web target services.
Core: bietet die Funktionalität zur Handhabung konkurrierender Zugriffe inkl. Konsole. Des Weiteren ist ein Datentyp zur Verwaltung großŸer Datenobjekte (ILOB) in dieser RApp enthalten.
ECP: ROOTS Event System ermöglicht Entwicklung eventgesteuerter Anwendungen.
HINO: Hierarchische Datenstruktur zur transienten und persistenten Speicherung der Daten sowie HINO Konsole.
Remote: Stellt die Funktionalität für den Remote Zugriff auf in ROOTS definierte targets zur Verfügung.
Store: Speicher Manager des ROOTS Servers.
Web: ROOTS Web Konsole.

Um ROOTS Server ohne die ECP RApps zu starten genügt es die esa-Dateien der hier beschriebenen RApps aus dem rappsdeploy Verzeichnis zu entfernen und den ROOTS Server neu zu starten.
ROOTS Server ohne die ECP RApps könnte z.B. verwendet werden um eigene ECP unabhängige OSGi basierte Anwendungen auszuführen zu lassen.

ROOTS Server Lizenz

Die Installation beinhaltet eine Testlizenz für 30 Tage. Die Lizenzdauer kann in der ROOTS Shell mit dem rstate Befehl (siehe ROOTS Web Konsole) überprüft werden.
Für darüberhinaus gehende Nutzung des ROOTS Servers benötigt man einen Lizenzschlüssel von der kachel GmbH.
Bitte schreiben Sie dazu eine E-Mail an contact@kachel.biz.

Struktur des installierten ROOTS Servers

In dem Verzeichnis <ROOTSECPServer> befinden sich nach der Installation folgende Verzeichnisse:

appl
In diesem Verzeichnis werden anwendungsspezifische Daten abgelegt.
backups
Jede RApp kann die Möglichkeit anbieten Backups der verarbeiteten Daten zu erstellen. Diese Daten werden hier strukturiert abgelegt.
Beispiel für eine Backup erstellende Rapp ist der PFileAgent: ist die entsprechende Property im Processor gesetzt, werden die verarbeiteten Dateien im Unterverzeichnis pfileagent des backups Verzeichnisses gesichert.
boot
Das Verzeichnis beinhaltet die Boot Rapp des ROOTS Servers. Die darin für den Start des ROOTS Servers zwingend erforderlichen bundles dürfen durch den Anwender NICHT gelöscht oder geändert werden!
databases
Das Verzeichnis beinhaltet die Datenbank des ROOTS Servers und darf durch den Anwender nicht geändert werden.
definitions
Das Verzeichnis beinhaltet verschiedene Definitionen der in ROOTS Server verwendeten Formate. Das Verzeichnis darf durch den Anwender erweitert werden, die vorhandenen Dateien sollten jedoch nicht gelöscht werden.
jre
Java Runtime Umgebung.
rapps
Dieses Verzeichnis beinhaltet die zur Laufzeit des ROOTS Servers aktiven RApps. Jede RApp wird durch ein Unterverzeichnis mit den darunter liegenden jar Dateien repräsentiert.
Inhalt dieses Verzeichnisses darf durch den Anwender NICHT geändert werden!
rappsdeploy
Beim Start des ROOTS Servers werden alle RApps, die sich im rappsdeploy (die und nur genau die) Verzeichnis befinden installiert und gestartet.
Soll demnach eine RApp hinzugefügt, aktualisiert oder gelöscht werden, wird die Änderung in diesem Verzeichnis durchgeführt.
system
In diesem Verzeichnis sind die systemeigenen Daten zu finden. Für den Anwender interessant sind insbesondere das Log-Verzeichnis, das Lizenzverzeichnis, und die Konfigurationsdatei roots.conf im wrappenConfigurations Verzeichnis:
- logs
  ROOTS log Dateien (eine Datei pro Tag). Die tagesaktuelle Datei sollte nicht gelöscht werden.
- tmp
  Diese Dateien werden von ROOTS zur Laufzeit erstellt bzw. verwendet und sollten nicht gelöscht bzw. geändert werden.
- yajsw
  Im Unterverzeihnis conf dieses Verzeichnisses befindet sich die Datei roots.conf. Die Datei roots.conf enthält Wrapper Konfiguration und darf bei Bedarf vom Anwender angepasst werden. Die Änderungen sind erst nach dem Neustart des ROOTS Servers aktiv.
  Die übrigen Daten im yajsw Verzeichnis dürfen nicht geändert werden.
- Datei .keystore
  Keystore Datei.
- Datei java.policy
  Java policy.

Des Weiteren sind folgende Dateien in <ROOTSECPServer> enthalten:

ecpweb.properties
ROOTS Console properties.
ginger.properties
Properties für die Ausführung der Ginger RApp. Diese Datei wird nur von der Ginger RApp verwendet.
roots.properties
Diese Datei beinhaltet sie Konfigurationseinstellungen zu dem ROOTS Server. Die einzelnen Properties sind in der Datei dokumentiert, eine Anpassung der Properties ist i.d.R. nicht notwendig.
RootsLizenzvertrag.pdf
Lizenzbedingungen.
RootsServerStart.bat (Windows) bzw. RootsServerStart.sh (MacOS)
Startet den ROOTS Server.

Unter Windows gibt es noch zusätzliche Dateien zur Installation, Deinstallation, Start und Stop des Dienstes:

RootsServiceInstall.bat
Installiert den ROOTS Service.
Wichtig: Zwischen Service Installation und De-Installation darf roots.conf und die wrapper scripte nicht modifiziert werden, da sonst die De-Installation fehlschlagen kann.
Falls eine Dienstkonfiguration geändert werden muss, muss zunächst der ROOTS Dienst deinstalliert, die Konfiguration geändern und abschließend der ROOTS Dienst wieder installiert werden.
RootsServiceStart.bat
Startet den ROOTS Service.
RootsServiceState.bat
Zeigt den Status des ROOTS Service an.
RootsServiceStop.bat
Beendet den ROOTS Service.
RootsServiceUninstall.bat
Deinstalliert den ROOTS Service.
Hinweis: Die Service-deinstallation wird in Windows Systemsteuerung nicht immer zeitnah angezeigt,
es kann durchaus einige Minute dauen bis der deinstallierte Dienst nicht mehr angezeigt wird.
Hintergrund: Aufgrund von Windows-Systemzuständen kann es passieren, dass der Dienst zunächst nur zum Löschen markiert wird und somit noch sichtbar ist.
Der Zustand "Zum Löschen markiert" wird in der Systemsteuerung nicht angezeigt.

Folgende Abbildung zeigt die in der Windows Version enthaltenen Dateien:

Konfiguration des Servers

Die Konfigurationseinstellungen für den Server befinden sich in den Dateien roots.properties (siehe Abschnitt "Struktur des installierten ROOTS Servers") und system/yajsw/conf/roots.conf.
Die Datei roots.properties sollte für einen reibungslosen Ablauf nicht geändert werden.

In der Datei system/yajsw/conf/roots.conf können folgende Properties vom Interesse für den Anwender sein:

Speicherplatzkonfiguration
wrapper.java.additional.1=-Xms256m
wrapper.java.additional.2=-Xmx1024m
Änderung dieser Properties ist notwendig, wenn die JVM (Java Virtual Machine) nicht genug Speicherplatz zur Verfügung hat.
Dies wird i.d.R. durch den Fehler "java.lang.OutOfMemoryError: Java heap space" angezeigt. Der Fehler wird in der log-Datei protokolliert.

Änderung des http Ports
wrapper.java.additional.4=-Dorg.osgi.service.http.port=8080
Änderung dieses Properties ist notwendig, wenn der Port 8080 bereits durch eine andere Anwendung belegt ist.
In der ROOTS Shell wird hierbei beim Start des ROOTS Servers eine Fehlermeldung mit dem enthaltenen Text "port already in use" angezeigt.

Änderung des Service Namens
wrapper.ntservice.name=ROOTS
wrapper.ntservice.displayname=ROOTS Server
Änderung dieses Properties ist notwendig, wenn bereits ein ROOTS Server unter dem Namen "ROOTS" bzw. "ROOTS Server" (default) als Service installiert ist, aber ein weiterer ROOTS Dienst installiert werden soll. In diesem Fall muss wie oben beschrieben der Port des zweiten ROOTS Servers und der Name des Services angepasst werden.

Änderung der Zugangsdaten für die ROOTS Web Konsole
wrapper.java.additional.13=-Dfelix.webconsole.username=admin
wrapper.java.additional.14=-Dfelix.webconsole.password=mypassword
Die Möglichkeit der Änderung der Zugangsdaten direkt über die ROOTS Web Konsole ist in Planung.
Die folgende Abbildung zeigt einen Ausschnitt aus der Konfigurationsdatei mit entsprechenden Konfigurationsparametern.

ROOTS Web Konsole

Die ROOTS Web Konsole ist unter folgender URL verfügbar, wobei <IP> die IP-Adresse des Rechners ist auf dem der ROOTS Server gestartet wurde:
http://<IP>:8080/system/console

Die Nutzung der ROOTS Web Konsole wird beschrieben in ROOTS Web Konsole.

Startet die Web Konsole nicht, bedeutet dies dass der Port 8080 durch einen anderen Prozess bereits belegt ist und die Web RApp des ROOTS Servers aus diesem Grund nicht gestartet werden konnte. Eine eindeutige Aussage zu dem Zustand des ROOTS Servers kann in dem Fall nicht erfolgen.

Wurde der ROOTS Server als Prozess und nicht als Service gestartet, ist in der ROOTS Shell die Fehlermeldung mit dem enthaltenen Text "port already in use" zu sehen.
Entsprechende Fehlermeldung ist auch in der log-Datei zu finden.

In diesem Fehlerfall muss der Port in ROOTS geändert werden. Die Änderung des Ports wird beschrieben im Abschnitt "Konfiguration des Servers".