Installation of MorphIT

MorphIT Installation

The following steps are necessary to get MorphIT up and running:

• Install NodeJS
• From MorphIT 4.0.0
  • Configure MorphIT Server
  • Configure MorphIT Launcher
  • Start or install MorphIT
• Before MorphIT 4.0.0
  • Install MorphIT Server
  • Install MorphIT Launcher
• adapt cxp-file

Install NodeJS

In order to use MorphIT, NodeJS must first be installed on the "host system".

• Recommended version: 16.17.0 (LTS)
• Backwards compatible up to: 6 .9.5

NodeJS is a Javascript Runtime Environment for all common operating systems and is available at https://nodejs.org/.

No configuration is required during installation, so you can simply click through the installation.

Setup from MorphIT 4.0.0

With MorphIT 4.0.0 the deployment has been changed to simplify installation and setup. MorphIT is now always delivered with all components and comes with a morphit.bat, which facilitates the administration of MorphIT.

Before servers or launchers are started, the components should be configured accordingly.

Configuration of the server

The server can be customised using the /config/custom/config.js file. This file has the same format as the default configuration in /config/config.jss except for the main node and can overwrite any values of the default configuration. All values that are not specified are loaded from the default configuration. In the default configuration file all allowed values are briefly described.

The most important values are:

• port - The port you have to use to access the server in your browser to open MorphIT
• path - The path to the static content (html, css, ...) that the server should deliver for HTTP requests. (Relative to the MorphIT main directory)
• ws.classix.port - The port under which free ClassiX instances should report to the server
• ssl.enabled - Decides whether MorphIT is accessed via HTTPS & WSS or HTTP & WS.
• widgetPath - Should be set to CX_ROOTDIR/WebWidgets Otherwise the web widgets cannot be used.
• static.enabled - If set, activates the static MorphIT mode This must first be prepared in detail as described in the link.
• static.webservice - Web service configuration for static mode.

SSL

As of version 3.3.3, SSL (TLS to be precise) can be enabled for each port individually. ssl.enabled can be assigned an array of port numbers and all endpoints running on one of the listed ports are started with SSL.

Example: Here only the HTTP port and the MorphIT port are set to SSL.

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

  ssl:{enabled:[8080, 8081]}
}

The array may also contain strings with the names of the endpoints for which SSL should be enabled. If multiple endpoints are running on the same port, then all endpoints will be started under SSL as soon as one of the endpoints is listed in ssl.enabled.

Permitted names are:

• http - The port on which MorphIT is accessed via the web browser
• morphit - The port under which the MorphIT client establishes a web socket connection with the NodeJS server
• classix - The port under which new ClassiX instances establish a web socket connection with the NodeJS server
• launcher - The port under the NodeJS launcher to establish a web socket connection with the NodeJS server
• admin - The port on which the administration console should connect to the NodeJS server

Example: Same configuration as above, but with name

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

  ssl:{enabled:['http', 'morphit']}
}

By using names, ssl.enabled does not need to be adjusted when changing the ports for the endpoints.

The following equivalencies apply:

ssl.enabled = true

ssl.enabled = [ 'http' ]

ssl.enabled = false

ssl.enabled = [ ]

Redirect HTTP to HTTPS

If the HTTP endpoint is set to HTTPS(ssl.enabled = true), it may be desirable to be able to access the server via http:// anyway and then be redirected to the correct address. For this purpose there is the option ssl.http_redirect. This is set to false by default and can be set to any port on , on which the HTTP server should then be accessible. By default this is port 80, but you can also simply set ssl.http_redirect = true for port 80.

The following conditions must be met before the diversion can be set up:

1. ssl.http_redirect ≠ must be false.
2. port must be listed in ssl.enabled (the HTTP server must be running under HTTPS)
3. The port specified in ssl.http_redirect must not be listed under ssl.enabled.
4. The port specified in ssl.http_redirect must not be used elsewhere in config.js (http/morphIt/classix/launcher/admin).
5. The port specified in ssl.http_redirect must not be used by another program on this machine.

Verify client certificates (mTLS)

Via ssl.mtls.enabled = true, mTLS can be activated on the HTTP port(config.port) if TLS is active there. With mTLS, the client must authenticate itself to the server with a certificate accepted by the server in order to establish a connection.

The use of mTLS is particularly suitable if the MorphIT server is mainly used as a web service endpoint for automated queries and a certification infrastructure already exists. In this case, access to the web service can be restricted to those clients that can present valid certificates.

For normal (interactive) MorphIT operation, mTLS is not recommended, as each user must configure an appropriate certificate in the browser to use MorphIT and the certificate does not replace the user's regular login.

Attention: mTLS can only be activated for whole ports. If mTLS is activated for the HTTP port, this applies to both the web service interface and MorphIT.

Configure root certificates

The accepted root CA certificates are defined in ssl.mtls.ca_certificates. Either a single path or an array of paths to the certificate files of the root CAs whose certificates are accepted when establishing a connection can be specified here. If the client certificate was not signed by any certificate specified here, then the connection is rejected.

If the client's certificate was signed/issued by an intermediate certification authority, then either

• the certificate of the intermediate certification authority must be included in ca_certificates
• or the client must send this certificate to the server when establishing the connection.

so that the server can verify the entire certification path up to the root CA.

If a certificate file cannot be found/read, this is logged as an error when the server is started and the certificate is ignored. If no certificate can be successfully loaded, then mTLS is automatically deactivated.

In ssl.mtls.ca_certificates the identifier 'default' is additionally allowed, whereby the root CA certificates from Mozilla delivered by default with the NodeJS version (from v12.3.0) are included in the list of certificates accepted by the server. 'default' is the default value for ssl.mtls.ca_certificates.

Behind a reverse proxy

If the MorphIT server is operated behind a reverse proxy, then only the IP addresses of the reverse proxy are visible in the server logs and in the admin console for incoming MorphIT connections, as the reverse proxy establishes the connection to the server. To see the actual IP addresses of the clients, you can configure the server(ws.trust_proxy=true) to evaluate the X-Forwarded-For header of the proxy. This header is normally ignored for security reasons, because the client could set the header itself and therefore the header may only be evaluated if one can assume that the own proxy has set the header correctly.

This header is not set correctly by every proxy by default. In an NGINX proxy, for example, the following entry must be entered in the forwarding configuration:

proxy_set_header X-Forwarded-For $remote_addr;

You should take into account that $remote_addr is used and not $proxy_add_x_forwarded_for, as the latter implies that your own proxy trusts the information of all previous proxies and should only be set if you have connected several of your own proxies in a row.

Dev-Mode

For troubleshooting, the server can be set to development mode via the configuration value dev = true, which causes all HTTP requests to be logged on the server. For message validation schemaPath(3.3.0 or higher) can be set to the path to a valid message schema, which causes the server to validate every message that ClassiX and MorphIT exchange. Faulty messages are logged.

This mode should only be activated for troubleshooting purposes, as it can greatly reduce the performance of the server.

Configuration of the Launcher

MorphIT can only be used effectively with many concurrent users if the ClassiX instances are distributed over several powerful computers and do not run on the same machine as the MorphIT server. This only works if a MorphIT launcher is installed on each machine

The launcher is also configured via the file /config/custom/config.js, which has the same format as the default configuration under /config/launcher.js.

The relevant settings for the launcher are:

• host - The hostname/IP under which the launcher can reach the server
• ws.launcher.port - The port on which the launcher connects to the server
• ws.launcher.endpoint - The name of the endpoint through which the launcher connects to the server
• ws.launcher.max_instances - The maximum number of ClassiX instances this launcher should start
• ws.launcher.launch - The definition of how a new ClassiX instance should be started.

The server allows only one launcher connection per IP address, so the entry ws.launcher.max_instances limits the number of instances per machine. Of course this limitation does not apply to several MorphIT servers, then one launcher can be started per MorphIT server.

In ws.launcher.launch (formerly under /launcher/config/custom/launch.js) the environment variables for the process to be started can be defined in env and in cwd the working directory and in cmd the command to be started must be entered, this can also be the name of a batch file to be started. The environment variables set in env can be used in cmd.

The Launcher automatically sets the following environment variables for started ClassiX instances:

Start or install MorphIT

The server can be started directly via morphit start server. The script installs the required NodeJS modules from the internet. If the target computer has no internet connection, a pre-installed MorphIT installation should be used.

To set up the server as a service, a CMD with administrator rights must be run and morphit install server must be executed in the MorphIT directory. You will then be guided through the installation. If this was successful, the service will be started directly. To remove the service, run morphit uninstall server with administrator rights.

Similarly the Launcher is started, installed and uninstalled via morphit start launcher, morphit install launcher, morphit uninstall launcher.

All currently installed but not started services can be started via morphit start services.

Setup before MorphIT 4.0.0

MorphIT server

If you have installed NodeJS on the "host system", the next step is to get the NodeJS server of ClassiX running. Normally this server is synced into the subdirectory webservice/ in every ClassiX project.

To do this, get the necessary files from Perforce at

 perforce:\\iv\main\WebService\morphIT 

Since NodeJS hosts MorphIT from the local directory, it does not matter where the folder is located on the "host system".

If the folder exists, go to the directory with a command line like "CMD" and give the command

 npm install 

or starts the script setup_depencies.bat. If the command "npm" cannot be found, the path variable must be extended by the npm.exe, which is located in the NodeJS folder (of the installation).

As soon as the command has run without error message, you can start the NodeJS server via console with the command

 node server 

or by double-clicking on the script start_server.bat. Status messages are displayed directly on the console.

Configuration

The configuration is largely the same as described in 4.0.0. With the following exceptions:

• instead of the /config/custom/config.js the /morphit/custom/config.js must be adapted
• The paths in config.js are relative to the /morphit directory

Institution as a service

If the server is to be started automatically when the system is started and restarted automatically in the event of a crash, it must be installed as a service. For this the script install_service.bat must be executed as administrator. The server is then set up as a service using the tool NSSM under the name cxserver (display name: ClassiX Server).

The console output of the server is stored as log files in the directory .../webservice/morphit/server/logs. The log file without timestamp suffix is the most current log.

The service can easily be stopped and restarted via the Windows Services SnapIn. To remove the service, the uninstall.bat script must be run with administrator privileges.

MorphIT launcher

The MorphIT launcher is located in Perforce under:

 perforce:\\iv\main\WebService\launcher 

The launcher is configured using the /launcher/config/custom/launcher.js file, which has the same format as the default configuration in /launcher/config/launcher.js. There it is configured on which computer & port the MorphIT server runs, so that the launcher can log in there. Furthermore, you can set the maximum number of ClassiX instances to be started on this machine. Since only one launcher per machine can connect to the server at a time, it is useless to start a second launcher process.

Via the batch file /launcher/setup_dependencies.bat the node dependencies can be installed. The launcher can then be started via /launcher/start_launcher.bat.

If the launcher is configured correctly, it can be installed as a service by running /launcher/install_service.bat as an administrator. The uninstall.bat will stop and remove an installed launcher service.

Installation as a service has the advantage that the service is automatically started at system startup and the launcher is automatically restarted in case of a crash. For the simple setup as a service the tool NSSM is used. The service is set up under the name cxlauncher (display name: ClassiX Launcher). All output of the service is stored in .log files in /morphit/launcher/logs/. If the launcher is simply started, the output is only written to the console. If the service does not start, check whether the launcher can be started manually and correct any configuration errors.

Configuration in ClassiX (from 3.1.0)

Since release 3.1.0 of MorphIT the communication between browser and ClassiX runs via web sockets and requires a different configuration. In the .cxp file the following call must be added:

The changeover also means that it is no longer necessary to start the WebServer in order to use MorphIT. In contrast to the web server, any number of local ClassiX instances can now be started in MorphIT mode without interfering with each other. Previously this was not possible because a web server was opened and thus the port was blocked by the first instance. If the ClassiX instances are started via the MorphIT launcher (from 3.2.0), no further configuration is necessary. Only the launcher must be started and correctly configured. If the ClassiX is started via the launcher, an additional environment variable CX_MORPHIT_BACKGROUND=1 is set in the ClassiX. This must not be set manually, otherwise the NodeJS server will refuse the connection.

If a manually started ClassiX is to connect to the server, the following environment variables must be used to configure where the server can be found

Afterwards the connection between locally started instances and incoming MorphIT connections must be allowed in the NodeJS server. For this the value ws.classix.interactive.connect_to_morphit must be set to true in /server/custom/config.js.

It is recommended to deactivate the ClassiX tray for installations where only MorphIT is used:

set CX_TRAY_DISABLE=1

Configuration in ClassiX (before 3.1.0)

In order for MorphIT to access ClassiX, only the WebService has to run on the corresponding port. This can either be created manually via System → Tools → Web Service Cockpit or the environment variable CX_WEBSRV_PORT is used, which is queried in the provider webService:

SET CX_WEBSRV_PORT=444

In the project file (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
                }

                ...