Install Semarchy xDI Runtime

This page explains how to install Semarchy xDI Runtime, as well as how to run it.

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

Installation types

You can install xDI Runtime in two ways:

  • From an extractable software package.

  • Using a Docker image.

The software package puts all Runtime files on disk. This makes it easier to manage and make edits to files, and gives you easier access to run included script files. However, you must manage the software environment yourself.

The Docker image is useful for portability. Docker manages software dependencies, and makes it more convenient to run multiple instances of xDI Runtime at the same time. Use this installation method to deploy Runtime configurations and integration flows created ahead of time.

Install xDI Runtime from the main software package

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

  1. Download the xDI Runtime archive file from the main Semarchy website.

  2. Extract the archive to a temporary directory.

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

  4. Check that all .bat (Windows) and .sh (Linux or macOS) script files, located at the root of the installation directory, have execution permissions.

  5. Check and set, if needed, write permission on the following subdirectories:

    • ./temp

    • ./build

    • ./sessions

  6. Configure the runtime if necessary.

  7. 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.

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.

For improved security, start the runtime as a user with the fewest possible operating system permissions.

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.

Install xDI Runtime with Docker

Docker images for xDI Runtime are available from DockerHub. They are based on an image of Debian Linux that integrates a supported OpenJDK version.

You can use provided Docker Compose files to set up a runtime image. These files define a PostgreSQL database, but you can change it as needed.

  1. Download and extract the Tutorial Resources ZIP file.

  2. Open the quick-install/docker/<version>/xdi-runtime/docker-compose/ directory in the extracted files. It contains a docker-compose.yml file, as well as a shared-resources directory. You need them for the next steps.

  3. Add needed xDI Runtime modules to a shared-resources/modules directory.

    The sample configuration expects a module directory named BACKEND-DATABASE with a PostgreSQL JDBC driver. Set up this module, or change the configuration in the next steps.

  4. Edit the docker-compose.yml file to change environment information and runtime ports.

  5. Configure xDI Runtime by editing the configuration files in the shared-resources/properties directory.

  6. Open a terminal to the directory with the Docker Compose file.

  7. Run the following command to build and start the Docker image:

    docker compose -f <your_docker_compose>.yml up

Image tags

The xDI Runtime images support different version tags:

Version tag Image name example Description

latest

xdi-runtime:latest

The latest tag references the most recent version of xDI Runtime. This image updates itself automatically when a newer version is published.

Minor version tag (year.quarter)

xdi-runtime:2023.3

This tag references a specific quarterly version of xDI Runtime. This image updates itself automatically when a patch for this quarterly version is released.

Full version tag (year.quarter.patch)

xdi-runtime:2023.1.4

This tag references a specific patch version of xDI Runtime, and does not update itself when a patch is released.
In production environments, use the full version tag to avoid overwriting your image with an update.

Troubleshooting Runtime startup on Docker

Many runtime startup issues on Docker are due to shared resources that were not properly set up beforehand. Double-check that you placed all needed resources in the shared-resources directory, and retry the build process.

You can also consult the xDI Runtime logs for troubleshooting. These logs are redirected to the Docker container logs. For more information, see the Docker article about logging.

Install xDI Runtime as service

Semarchy xDI Runtime does not have explicit settings to run as an operating system service. However you can set up your environment to run it automatically based on your requirements.

Running software as a service often requires administrative or elevated privileges, which also carries its own security risks. If you launch xDI Runtime automatically, you should have it run under its own user account with only the necessary permissions.

General guidelines

When creating a service or command that controls xDI Runtime, you must take the following things into account:

  • The command needs to know the directory that holds the runtime control scripts.

  • Commands that stop the runtime should use the stopengine script, and explicitly define the port the runtime listens on.

  • Depending on your operating system, make sure the runtime process detaches from the terminal that invokes it.

Guidelines by operating system

Windows

Windows provides a built-in mechanism for creating services. You can use the sc command or create a service using the Services Control Panel. Refer to the Windows Services documentation for detailed instructions.

You can also use third-party tools, such as NSSM, to wrap your software as a service. These tools may simplify service creation and management.

Linux

Most modern Linux distributions use systemd. Create a systemd service unit file (usually located in /etc/systemd/system) to define your service. Enable and start the service using systemctl. Refer to the systemd documentation for specifics.

For other systems, you can use init scripts (such as /etc/init.d). These scripts control service startup and shutdown.

Sample start and stop commands may look like this:

# sample variables - replace with your own
# runtime directory
export rdir=/data/xdi-runtime-dir
# runtime port
export rport=42501

# commands
cd $rdir;nohup ./startengine.sh &
cd $rdir;./stopengine.sh -port $rport

macOS

MacOS uses launchd for managing services. Create a plist file (usually in /Library/LaunchDaemons) to define your service, and load the service using launchctl. Refer to the Apple Developer documentation for details.