Install the Semarchy xDI Runtime

This document details how to install Semarchy xDI Runtime.

Before the installation, make sure to understand the architecture and carefully review the system requirements.

Download the Runtime

The Runtime is shipped as an archive file. It runs on any platform with a supported Java Virtual Machine.

Install the Runtime

  1. Uncompress the Runtime archive and uncompress it to a temporary directory.

  2. Move the archive content to the target installation directory.

  3. Check and set, if needed, the execution permission on all the .bat (Windows) and .sh (Linux or macOS) scripts located at the root of the installation directory.

  4. Check and set, if needed, write permission on the following sub-directories:

    • ./temp

    • ./build

    • ./sessions

  5. Configure the Runtime if necessary.

  6. 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. We recommend configuring the runtime security with the settings corresponding to your requirements.
For security concerns, it is recommended to install and start the runtime with a dedicated user having only the necessary operating system permissions.

Runtime as a service

Windows

You can install xDI Runtime as a Windows service. To do so, run these scripts from the runtime installation folder as an administrator:

  1. installEngineAsService.bat -i [<Service Name>] to add a runtime service.

  2. installEngineAsService.bat -r [<service Name>] to remove a runtime service.

The optional <Service Name> parameter allows you to set different service names, to install multiple runtimes on the same machine. When the parameter is left blank, the service name defaults to Semarchy xDI Runtime.

Any change in the runtime configuration file or script files (.properties or .bat files) requires removing and again adding the runtime service.
When starting multiple runtime services, make sure to configure the services for each runtime on different ports.
The user configured to start the runtime Windows service must have network capabilities. It is typically a domain user.

Linux and macOS

To have xDI Runtime start automatically under Linux and macOS, see the service setup for your operating system. This requires a startup script and a shutdown script for the runtime process.

  • The runtime startup script is startengine.sh.

  • The runtime shutdown script is stopengine.sh.

For security reasons, you should install and launch the runtime from a user account that has the minimum required permissions.

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 1. Linux or macOS command
./startengine.sh &> start.log
Example 2. 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.