Install the Semarchy xDI Runtime

This document details how to install Semarchy xDI Runtime.

Before the installation, make sure to review the xDI architecture, as well as the system requirements.

Download the Runtime

The Runtime comes in an archive file. It runs on any platform with a supported Java Virtual Machine.

Install the Runtime

Decompress the Runtime archive to a temporary directory.
Move the archive content to the target installation directory.
Check that all .bat (Windows) and .sh (Linux or macOS) script files, located at the root of the installation directory, have execution permissions.
Check and set, if needed, write permission on the following subdirectories:
- ./temp
- ./build
- ./sessions
Configure the runtime if necessary.
Add modules to the runtime, if you need them.

With the default configuration, the Runtime only listens on localhost and requires to logging in with the default users defined in the configuration file. This default configuration is for security purposes. You should configure runtime security settings according to your requirements.

For improved security, install and start the runtime as a user with the minimum necessary operating system permissions.

Start and stop the Runtime

To start the Runtime, go to the directory where you installed it, and run startengine.bat (Windows) or startengine.sh (Linux or macOS).

To stop the runtime, run stopengine.bat (Windows) or stopengine.sh from the same directory.

The startengine and stopengine scripts can take different options:

startengine.bat/.sh

Example 1. Usage

startengine [-usage] [-port <httpPort>] [-conf <propertyFileName>] [-updatedb]

Option Description

-usage

Prints the list of options for this command.

-port <Port>

Port on which the runtime should listen to requests.

This option overrides the httpServerPort option from the configuration file.

-conf <propertyFileName>

Specifies which configuration file the runtime uses.

-updatedb

Attempts to update the runtime database schema, then stops the runtime.

The runtime database schema may change between product versions. The runtime automatically updates it where applicable, but you can use this option to manually attempt an update without leaving the runtime running.

stopengine.bat/.sh

Example 2. Usage

stopengine [-usage] [-host <Host>] [-port <Port>] [-user <User>] [-password <Password>] [-uncryptedPassword <UncryptedPassword>] [-immediate]

Table 1. stopengine options
Option	Description
`-usage`	Prints the list of options for this command.
`-host <Host>`	Host or IP address of the runtime you are trying to access.
`-port <Port>`	Port of the runtime you are trying to access.
`-user <User>`	Username for the runtime.
`-password <Password>`	Password for the runtime, in plain text or in its encrypted form.
`-uncryptedPassword <UncryptedPassword>`	(Deprecated) Password for the runtime, in plain text.
`-immediate`	Stops the runtime immediately, without cleanly stopping active sessions.

Troubleshooting Runtime startup

If the runtime process stops a few seconds after startup, or the window closes unexpectedly, you need to create a log to investigate errors. Start the runtime by running the following commands from the command line:

Example 3. Linux or macOS command

./startengine.sh &> start.log

Example 4. Windows command

startengine.bat > start.log 2>&1

These commands save the runtime output to a start.log file. Consult this file to investigate the errors.

If you need further assistance, Contact Semarchy support, and provide the log file to help with troubleshooting.