Lade...
 

Installation von MorphIT

MorphIT Installation

Um MorphIT in Betrieb zu nehmen, sind folgende Schritte erforderlich:

 

NodeJS installieren

Um MorphIT benutzen zu können, muss zuerst NodeJS auf dem "Host-System" installiert werden.

  • empfohlene Version: 16.17.0 (LTS)
  • rückwärtskompatibel bis:  6.9.5

NodeJS ist eine Javascript Runtime Environment für alle geläufigen Betriebssysteme und unter https://nodejs.org/ zu beziehen.

Bei der Installation müssen keine Konfigurationen vorgenommen werden, sodass man die Installation einfach durchklicken kann.

Einrichtung ab MorphIT 4.0.0

Mit MorphIT 4.0.0 wurde das Deployment verändert, um die Installation und die Einrichtung zu vereinfachen. MorphIT wird nun immer mit allen Komponenten ausgeliefert und wird mit einer morphit.bat ausgeliefert, die die Verwaltung von MorphIT erleichtert.

Bevor Server oder Launcher gestartet werden, sollten die Komponenten entsprechend konfiguriert werden.

Konfiguration des Servers

Der Server lässt sich über die Datei /config/custom/config.js anpassen. Diese Datei hat bis auf den Hauptknoten das gleiche Format, wie die Standardkonfiguration in /config/config.js und kann beliebige Werte der Standardkonfiguration überschreiben. Alle Werte, die nicht angegeben sind, werden aus der Standardkonfiguration geladen. In der Standardkonfigurationsdatei sind alle erlaubten Werte kurz beschrieben.

Die wichtigsten Werte sind:

  • port - Der Port über den man den Server im Browser ansurfen muss, um MorphIT zu öffnen
  • path - Der Pfad zu den statischen Inhalten (html, css, ...), die der Server bei HTTP-Anfragen ausliefern soll. (Relativ zum MorphIT-Hauptverzeichnis)
  • ws.classix.port - Der Port unter dem sich freie ClassiX Instanzen beim Server melden sollen
  • ssl.enabled - Entscheidet, ob MorphIT über HTTPS & WSS oder HTTP & WS angesprochen wird.
  • widgetPath - Sollte auf CX_ROOTDIR/WebWidgets gesetzt werden. Ansonsten können die Web-Widgets nicht verwendet werden.
  • static.enabled - Aktiviert, falls gesetzt, den statischen MorphIT-Modus. Dieser muss zunächst, wie im Link beschrieben, ausführlich vorbereitet werden.
  • static.webservice - Webservice-Konfiguration für den statischen Modus.
SSL

Ab Version 3.3.3 lässt sich SSL (genau genommen TLS) für jeden Port einzeln aktivieren. ssl.enabled kann ein Array von Portnummern zugewiesen werden und alle Endpunkte, die auf einem der Aufgeführten Ports ausgeführt werden, werden mit SSL gestartet.

Beispiel: Hier werden nur der HTTP-Port und der MorphIT-Port auf SSL gesetzt.

{ port: 8080, //HTTP-Port ws: { morphit:{port:8081} classix:{port:8082}, launcher:{port:8083}, admin:{port:8082} }, ssl:{enabled:[8080, 8081]} }

 

Das Array darf auch Strings mit den Namen der Endpunkten enthalten, für die SSL aktiviert sein soll. Falls mehrere Endpunkte auf dem gleichen Port laufen, dann werden alle Endpunkte unter SSL gestartet, sobald einer der Endpunkte in ssl.enabled aufgeführt wird.

Erlaubte Namen sind:

  • http - Der Port auf dem man MorphIT über den Webbrowser ansteuert
  • morphit - Der Port unter dem der MorphIT-Client eine Websocket-Verbindung mit dem NodeJS-Server aufbaut
  • classix  - Der Port unter dem neue ClassiX-Instanzen eine Websocket-Verbindung mit dem NodeJS-Server aufbauen
  • launcher - Der Port unter dem NodeJS-Launcher eine Websocket-Verbindung mit dem NodeJS-Server aufbauen
  • admin -  Der Port unter dem die Administrationkonsole sich mit dem NodeJS-Server verbinden soll

Beispiel: Gleiche Konfiguration, wie oben, nur mit Namen

{ port: 8080, //HTTP-Port ws: { morphit:{port:8081} classix:{port:8082}, launcher:{port:8083}, admin:{port:8082} }, ssl:{enabled:['http', 'morphit']} }

Durch die Verwendung von Namen muss ssl.enabled bei einer Änderung der Ports für die Endpunkte nicht angepasst werden.

Es gelten folgende Äquivalenzen:

ssl.enabled = true
ist äquivalent zu
ssl.enabled = [ 'http' ]
ssl.enabled = false
ist äquivalent zu
ssl.enabled = [ ]

 

HTTP auf HTTPS umleiten

Ist der HTTP-Endpunkt auf HTTPS eingestellt (ssl.enabled = true), dann kann es wünschenswert sein, dass man den Server trotzdem per http:// ansteuern kann und dann auf die korrekte Adresse umgeleitet wird. Hierfür gibt es die Option ssl.http_redirect. Diese ist standardmäßig auf false gesetzt und kann auf einen beliebigen Port gesetzt werden, auf welchem der HTTP-Server dann erreichbar sein soll. Dies ist standardmäßig der Port 80. Für Port 80 kann auch einfach ssl.http_redirect = true gesetzt werden.

Damit die Umleitung eingerichtet werden kann, müssen folgende Bedingungen erfüllt sein:

  1. ssl.http_redirect muss ≠ false sein.
  2. port muss in ssl.enabled aufgeführt sein (der HTTP-Server muss unter HTTPS laufen).
  3. Der in ssl.http_redirect angegebene Port darf nicht unter ssl.enabled aufgeführt sein.
  4. Der in ssl.http_redirect angegebene Port darf nicht anderweitig in der config.js verwendet werden (http/morphIt/classix/launcher/admin).
  5. Der in ssl.http_redirect angegebene Port darf nicht von einem anderen Programm auf dieser Maschine verwendet werden.
Client-Zertifikate verifizieren (mTLS)
4.14.0

Über ssl.mtls.enabled = true lässt sich mTLS auf dem HTTP-Port (config.port) aktivieren, falls dort TLS aktiv ist. Bei mTLS muss sich der Client gegenüber dem Server mit einem vom Server akzeptierten Zertifikat authentifizieren, um eine Verbindung aufzubauen.

Die Verwendung von mTLS bietet sich besonders dann an, falls der MorphIT-Server hauptsächlich als Webservice-Endpunkt für automatisierte Abfragen verwendet wird und eine Zertifizierungsinfrastruktur bereits vorhanden ist. In diesem Fall kann der Zugriff auf den Webservice auf die Clients eingeschränkt werden, die gültige Zertifikate vorweisen können.

Für den normalen (interaktiven) MorphIT-Betrieb wird mTLS nicht empfohlen, da jeder Nutzer ein entsprechendes Zertifikat im Browser konfigurieren muss, um MorphIT zu verwenden und das Zertifikat ersetzt nicht die reguläre Anmeldung des Nutzers.

Achtung: mTLS lässt sich nur für ganze Ports aktivieren. Wird mTLS für den HTTP-Port aktiviert wird, dann gilt dies sowohl für die Webservice-Schnittstelle, als auch für MorphIT.

Root-Zertifikate konfigurieren

Die akzeptierten Root-CA-Zertifikate werden in ssl.mtls.ca_certificates definiert. Hier kann entweder ein einzelner Pfad oder ein Array von Pfaden zu den Zertifikatsdateien der Root-CAs angegeben werden, deren Zertifikate beim Verbindungsaufbau akzeptiert werden. Falls das Client-Zertifikat von keinem hier angegebenen Zertifikat signiert wurde, dann wird die Verbindung abgelehnt.

Falls das Zertifikat des Clients von einer Zwischenzertifizierungsstelle signiert/ausgestellt wurde, dann muss entweder

  • das Zertifikat der Zwischenzertifizierungsstelle in ca_certificates mit aufgenommen werden
  • oder der Client muss dieses Zertifikat dem Server beim Verbindungsaufbau mitsenden

,damit der Server den gesamten Zertifizierungspfad bis zur Root-CA verifizieren kann.

Falls eine Zertifikatsdatei nicht gefunden/gelesen werden kann, dann wird dies beim Start des Servers als Fehler geloggt und das Zertifikat ignoriert. Falls kein Zertifikat erfolgreich geladen werden kann, dann wird mTLS automatisch deaktiviert.

In ssl.mtls.ca_certificates ist zusätzlich der Identifier 'default' erlaubt, wodurch die mit der NodeJS-Version (ab v12.3.0) standardmäßig ausgelieferten Root-CA-Zertifikate von Mozilla in die Liste der vom Server akzeptierten Zertifikate aufgenommen wird. 'default' ist der Standardwert für ssl.mtls.ca_certificates.

Hinter einem Reverse-Proxy
4.1.2

Wird der MorphIT-Server hinter einem Reverse-Proxy betrieben, dann werden in den Server-Logs und in der Admin-Konsole für die eingehenden MorphIT-Verbindungen nur die IP-Adressen des Reverse-Proxies sichtbar, da dieser die Verbindung zum Server aufbaut. Um die tatsächlichen IP-Adressen der Clients zu sehen, kann man den Server so konfigurieren (ws.trust_proxy=true), dass er den X-Forwarded-For-Header des Proxies auswertet. Dieser Header wird aus Sicherheitsgründen im Normalfall ignoriert, da der Client den Header selbst setzen könnte und der Header deshalb nur dann ausgwertet werden darf, wenn man davon ausgehen kann, dass der eigene Proxy den Header korrekt gesetzt hat.

Dieser Header wird nicht von jedem Proxy standardmäßig korrekt gesetzt. In einem NGINX-Proxy muss beispielsweise folgender Eintrag in die Weiterleitungskonfiguration eingetragen werden:

proxy_set_header X-Forwarded-For $remote_addr;

Hierbei sollte berücksichtigt werden, dass $remote_addr verwendet wird und nicht $proxy_add_x_forwarded_for, da letzteres impliziert, dass der eigene Proxy den Angaben aller vorherigen Proxies vertraut und sollte nur gesetzt werden, wenn man mehrere eigene Proxies hintereinander geschaltet hat.

 

Dev-Mode

Zur Fehlersuche kann der Server über den Konfigurationswert dev = true in den Development-Mode versetzt werden, was dazu führt, dass alle HTTP-Anfragen am Server geloggt werden. Zur Validierung der Nachrichten kann schemaPath(ab 3.3.0) auf den Pfad zu einem gültigen Nachrichtenschema gesetzt werden, was dazu führt, dass der Server jede Nachricht, die ClassiX und MorphIT austauschen, validiert wird. Fehlerhafte Nachrichten werden geloggt.

Dieser Modus sollte nur zur Fehlersuche aktiviert werden, da er die Performance des Server stark reduzieren kann.

 

Konfiguration des Launchers

MorphIT kann bei vielen gleichzeitigen Nutzern nur dann effektiv verwendet werden, wenn die ClassiX-Instanzen auf mehrere leistungsstarke Rechner verteilt sind und nicht auf der gleichen Maschine laufen wie der MorphIT-Server. Das funktioniert nur, wenn auf jeder Maschine ein MorphIT-Launcher eingerichtet ist

Der Launcher wird ebenfalls über die Datei /config/custom/config.js konfiguriert, die das gleiche Format wie die Standardkonfiguration unter /config/launcher.js hat.

Die für den Launcher relevanten Einstellungen sind:

  • host - Der Hostname/IP unter dem der Launcher den Server erreichen kann
  • ws.launcher.port - Der Port auf dem sich der Launcher zum Server verbindet
  • ws.launcher.endpoint - Die Bezeichnung des Endpunkts, über den sich der Launcher zum Server verbindet
  • ws.launcher.max_instances - Die maximale Anzahl an ClassiX-Instanzen, die dieser Launcher starten soll
  • ws.launcher.launch - Die Definition, wie eine neue ClassiX-Instanz gestartet werden soll.

Pro IP-Adresse lässt der Server nur eine Launcher-Verbindung zu, sodass der Eintrag ws.launcher.max_instances die Anzahl der Instanzen pro Maschine limitiert. Diese Limitierung gilt natürlich nicht für mehrere MorphIT-Server, dann kann pro MorphIT-Server ein Launcher gestartet werden.

In ws.launcher.launch (früher unter /launcher/config/custom/launch.js) können in env die Umgebungsvariablen für den zu startenden Prozess definiert werden und in cwd das Arbeitsverzeichnis und in cmd muss der zu startende Befehl eingetragen werden, dies kann auch der Name einer zu startenden Batch-Datei sein. Die in env gesetzten Umgebungsvariablen können in cmd verwendet werden.

Der Launcher setzt automatisch folgende Umgebungsvariablen für gestartete ClassiX Instanzen:

Variable Beschreibung
CX_MORPHIT_HOST Der Hostname des MorphIT-Servers zu dem sich die ClassiX-Instanz verbinden soll
CX_MORPHIT_PORT Der Port auf welchem sich die ClassiX-Instanz mit dem MorphIT-Server verbinden soll
CX_MORPHIT_ENDPOINT Der Name des Websocket-Endpunktes an welchen sich die ClassiX-Instanz verbinden soll
CX_MORPHIT_SSL 1, falls die Verbindung zum Server über wss:// erfolgen soll, ansonsten nicht gesetzt
CX_MORPHIT_BACKGROUND 1 - gibt an, dass die ClassiX-Instanz über den Launcher gestartet wurde
CX_MORPHIT_NONCE Ein Nonce-Wert der zur Authentifizierung der ClassiX-Instanz beim Server dient
CX_START_WAIT "/WAIT " - Hierüber kann in der Start-Batch sichergestellt werden, dass der gestartete Prozess nicht sofort beendet wird, falls er über den Launcher gestartet wird. (START /WAIT). (definiert in config/launch.js)
Wichtig: Der vom Launcher gestartete Prozess darf sich nicht beenden, solange die ClassiX-Instanz läuft, um sicherzustellen, dass die eingebauten Korrekturmechanismen korrekt funktionieren. Dies kann über ein START /WAIT erreicht werden (siehe CX_START_WAIT).

 

MorphIT starten oder installieren

Der Server kann direkt über morphit start server gestartet werden. Das Script installiert dabei bei Bedarf benötigte NodeJS-Module aus dem Internet. Falls der Zielrechner keine Internetverbindung hat, sollte eine vorinstallierte MorphIT-Installation verwendet werden.

Um den Server als Dienst einzurichten, muss eine CMD mit Administratorrechten ausgeführt werden und im MorphIT-Verzeichnis morphit install server ausgeführt werden. Man wird dann durch die Installation geführt. Falls dies erfolgreich war, wird der Dienst direkt gestartet. Um den Dienst wieder zu entfernen, muss morphit uninstall server mit Administratorrechten ausgeführt werden.

Analog dazu wird der Launcher über morphit start launchermorphit install launchermorphit uninstall launcher gestartet, installiert und deinstalliert. 

Über morphit start services können alle aktuell installierten aber nicht gestarteten Dienste gestartet werden.

Hinweis: Gestartete ClassiX-Prozesse übernehmen erhalten die Rechte des startenden Prozesses. In Normalfall läuft damit das ClassiX unter dem Benutzer "SYSTEM". Dieser Nutzer hat grundsätzlich keinen Zugriff auf Netzwerkfreigaben. Falls die ClassiX-Prozesse auf Netzwerkfreigaben zugreifen müssen, muss der Nutzer auf ein anderes lokales Konto geändert werden.
Dies geht über die Dienstverwaltung -> Eigenschaften -> Anmelden -> "Dieses Konto".

Einrichtung vor MorphIT 4.0.0

 

MorphIT-Server

Wenn man auf dem "Host-System" NodeJS installiert hat, muss man als nächstes den NodeJS Server von ClassiX zum Laufen bringen. Dieser wird normaler Weise in jedem ClassiX-Projekt in das Unterverzeichnis webservice/ gesynct.

Dafür holt man sich die erforderlichen Dateien aus Perforce unter

perforce:\\iv\main\WebService\morphIT

Da NodeJS MorphIT aus dem lokalen Verzeichnis hostet, ist es egal wo der Ordner auf dem "Host-System" liegt.

Wenn der Ordner vorhanden ist, geht man mit einer Commandozeile wie "CMD" in das Verzeichnis und gibt den Befehl

npm install

ein oder startet das Script setup_depencies.bat. Falls der Befehl "npm" nicht gefunden werden kann, muss man die Pfadvariable um die npm.exe, welche sich im NodeJS Ordner (der Installation) befindet, erweitern.

Sobald der Befehl ohne Fehlermeldung durchgelaufen ist, kann man den NodeJS Server per Console mit dem Befehl

node server

starten oder über einen Doppelklick auf das Script start_server.bat hierbei werden Statusmeldungen direkt auf die Konsole ausgegeben.

Konfiguration

Die Konfiguration erfolgt größtenteils genauso, wie unter 4.0.0 beschrieben. Mit den folgenden Ausnahmen:

  • statt der /config/custom/config.js muss die /morphit/custom/config.js angepasst werden
  • Die Pfade in der config.js sind relativ zum /morphit-Verzeichnis
Einrichtung als Dienst

Soll der Server beim Systemstart automatisch gestartet werden und im Falle eines Absturzes selbstständig neu starten, dann muss er als Dienst installiert werden. Hierfür muss das Script install_service.bat als Administrator ausgeführt werden. Der Server wird dann über das Tool NSSM unter dem Namen cxserver als Dienst eingerichtet (Anzeigename: ClassiX Server).

Die Konsolenausgabe des Servers wird in Form von Log-Dateien im Verzeichnis .../webservice/morphit/server/logs abgelegt. Dabei ist die Log-Datei ohne Zeitstempel-Suffix das aktuellste log.

Der Dienst kann einfach über das Windows-Dienste-SnapIn beendet und neu gestartet werden. Um den Dienst zu entfernen, muss das Script uninstall.bat mit Administratorrechten ausgeführt werden.

 

MorphIT-Launcher

Der MorphIT-Launcher befindet sich in Perforce unter:

perforce:\\iv\main\WebService\launcher

Der Launcher wird über die Datei /launcher/config/custom/launcher.js konfiguriert, die das gleiche Format wie die Standardkonfiguration unter /launcher/config/launcher.js hat. Dort wird konfiguriert, auf welchem Rechner & Port der MorphIT-Server läuft, damit der Launcher sich dort anmelden kann. Zudem lässt sich einstellen, wie viele ClassiX instanzen maximal auf dieser Maschine gestartet werden sollen. Da sich immer nur ein Launcher pro Maschine mit dem Server verbinden kann, bringt es nichts, einen zweiten Launcher-Prozess zu starten.

Über die Batch-Datei /launcher/setup_dependencies.bat können die node-Abhängigkeiten installiert werden. Der Launcher kann anschließend über /launcher/start_launcher.bat gestartet werden.

Ist der Launcher korrekt eingerichtet, kann er als Dienst installiert werden, indem /launcher/install_service.bat als Administrator ausgeführt wird. Die uninstall.bat stoppt und entfernt einen installierten Launcher-Dienst.

Die Installation als Dienst hat den Vorteil, dass der Dienst beim Systemstart automatisch gestartet wird und der Launcher im Falle eines Absturzes automatisch neu gestartet wird. Für die einfache Einrichtung als Dienst wird das Tool NSSM verwendet. Der Dienst wird unter dem Namen cxlauncher eingerichtet (Anzeigename: ClassiX Launcher). Alle Ausgaben des Dienstes werden in .log Dateien in /morphit/launcher/logs/ abgelegt. Wird der Launcher einfach nur gestartet, dann wird die Ausgabe nur auf die Konsole geschrieben. Sollte der Dienst nicht starten, dann sollte untersucht werden, ob sich der Launcher manuell starten lässt und eventuelle Konfigurationsfehler beheben.

 

Konfiguration in ClassiX (ab 3.1.0)

Seit dem Release 3.1.0 von MorphIT läuft die Kommunikation zwischen Browser und ClassiX über Websockets und erfordert eine andere Konfiguration. In der .cxp-Datei muss der folgende Aufruf hinzugefügt werden: 

INITIALIZE: ...
            //Connect to NodeJS server via websockets
            webService::StartMorphITAutomatically


Durch die Umstellung ist es auch nicht mehr notwendig, den WebServer zu starten, um MorphIT zu verwenden. Im Gegensatz zum Webserver können jetzt auch beliebig viele lokale ClassiX-Instanzen im MorphIT-Modus gestartet werden, ohne sich zu stören. Bisher ging dies nicht, weil ein Webserver geöffnet wurde und dadurch der Port von der ersten Instanz blockiert wurde. Falls die ClassiX-Instanzen über den MorphIT-Launcher gestartet werden (ab 3.2.0), ist keine weitere Konfiguration notwendig. Es muss lediglich der Launcher gestartet und korrekt konfiguriert sein. Wenn das ClassiX über den Launcher gestartet wird, dann ist im ClassiX eine zusätzliche Umgebungsvariable CX_MORPHIT_BACKGROUND=1 gesetzt. Diese darf nicht manuell gesetzt werden, da der NodeJS-Server ansonsten die Verbindung verweigert.

Soll sich ein manuell gestartes ClassiX mit dem Server verbinden, dann muss über die folgenden Umgebungsvariablen konfiguriert werden, wo der Server zu finden ist.

SET CX_MORPHIT_HOST=localhost
SET CX_MORPHIT_PORT=8081
SET CX_MORPHIT_ENDPOINT=/morphit/cx


Anschließend muss im NodeJS-Server noch die Verbindung zwischen lokal gestarteten Instanzen und eingehenden MorphIT-Verbindungen erlaubt werden. Dafür muss in der /server/custom/config.js der Wert ws.classix.interactive.connect_to_morphit auf true gesetzt werden.

module.exports = {
  'ws': { 'classix': { 'interactive': { 'connect_to_morphit' : true } } }
};

Es empfiehlt sich bei Installationen, bei denen nur MorphIT benutzt wird, den ClassiX-Tray zu deaktivieren:

set CX_TRAY_DISABLE=1

Konfiguration in ClassiX (vor 3.1.0)

Damit MorphIT auf ClassiX zugreifen kann, muss lediglich der WebService auf dem entsprechenden Port laufen. Dies kann entweder über System → Tools → Web Service Cockpit manuell erzeugen oder es wird die Umgebungsvariable CX_WEBSRV_PORT benutzt, die im Provider webService abgefragt wird:

SET CX_WEBSRV_PORT=444

In der Projekt-Datei (cxp):

// Messages interface
// ---

    INITIALIZE: ...
                // Start web server if CX_WEBSRV_PORT exists
                webService::StartWebServerAutomatically 0 > if
                {
                  T("Ein anderer Webserver verwendet den Port und die Url bereits!", "Another web service still using port and url!")
                  Attention(AbortTXN) cancel
                }

                ...