Installation

This guide describes the installation of the MigratoryData server. Before reading this document, it is recommended to read the Architecture Guide for a better understanding of the concepts and to have a more comprehensive background.

Requirements

Supported Operating Systems

Written in Java, MigratoryData Server runs on all major operating systems: Linux/Unix, Mac OS, Windows, and potentially on any other operating system having support for OpenJDK Java Runtime Environment (JRE) version 8 or later.

MigratoryData Server comes with 64-bit installers for rpm-based and deb-based Linux distributions. Also, a platform-independent tarball is available.

Important

For production deployments, Linux is the only operating system which is currently supported. The recommended Linux distributions are 64-bit Red Hat Enterprise Linux (RHEL) / CentOS 6 or later, and Debian 7 or later.

Installation Requirements

OpenJDK

You need to install Java Runtime Environment (JRE) version 8 or higher on your system before you can install and run MigratoryData Server.

Note

The recommended JRE is OpenJDK version 8.

OpenSSL (Optional)

MigratoryData Server comes with full support for TLS/SSL communication which can be used for most deployments and for all supported platforms.

However, for Linux production deployments handling a high number of users, in order to make best use of the available hardware resources, MigratoryData Server can be configured to use native TLS/SSL communication provided by the OpenSSL library. The integration with OpenSSL is made via the Apache Portable Runtime (APR) library. In this way, the requirement is that you install OpenSSL and APR libraries on your system before you can use the native TLS/SSL communication. To enable the native TLS/SSL communication, add to the configuration file of MigratoryData Server:

Native.Ssl = true

Hardware

CPU

In a production environment it is recommended to have a server with at least 4 CPU cores, but the recommendation can grow to more CPU cores depending on the load of data on the server and how much simultaneous clients will be connected.

Hint

For development or small deployments there are no special requirements concerning CPU, you can use any decent workstation hardware.

RAM

In a production environment it is recommended to have 8 GB or more memory depending on the load of data on the server and how much simultaneous clients will be connected.

Hint

For development or small deployments it is recommended to have at least 512 MB memory.

Linux

Installation guide for Linux.

Linux Deb: Ubuntu, Debian

The installation procedure described in this section has been tested on Debian and Ubuntu 64-bit distributions.

Install OpenJDK Java Runtime Environment

As discussed in the requirements section, the Java Runtime Environment (JRE) version 8 (or later) is required for running MigratoryData Server. To install the JRE version 8 of OpenJDK, run as root:

apt-get install openjdk-8-jre-headless

Validate your installation with the following command:

java -version

The output should be something like:

openjdk version "1.8.0_212"
OpenJDK Runtime Environment (build 1.8.0_212-b04)
OpenJDK 64-Bit Server VM (build 25.212-b04, mixed mode)

Install OpenSSL for Native TLS/SSL Communication

As discussed in the requirements section, the OpenSSL and APR libraries are required to enable the native TLS/SSL communication. To install these libraries, run as root:

apt-get install libapr1 openssl

Install MigratoryData Server

Download the DEB package of MigratoryData Server and run as root the following command to install it:

dpkg -i migratorydata-Version-Architecture.deb

This will deploy MigratoryData Server as follows:

Location

Description

/etc/migratorydata/migratorydata.conf

The default configuration file

/etc/default/migratorydata

The default system configuration file

/var/log/migratorydata/

The folder where the logs will reside

/usr/share/migratorydata/migratorydata.jar

The object code of the MigratoryData server

/usr/share/migratorydata/extensions

The folder where extensions/plugins reside

/usr/bin/migratorydata

The MigratoryData start script

/lib/systemd/system/migratorydata.service

The systemd unit file

/usr/share/doc/migratorydata

The folder where docs & license info reside

Note

Please refer to Configuration Guide, Sections “Using Configuration File” and “Using Environment Variables” to learn how to customize the default configuration file and the default system configuration file.

After installation:

1. The service will start automatically when the machine reboots. To manually start, stop, restart, and get the status of the service, run as root one of the following commands:

systemctl start migratorydata
systemctl stop migratorydata
systemctl restart migratorydata
systemctl status migratorydata

2. To test the installation start a web browser on the machine where MigratoryData Server has been installed and open the following URL:

http://localhost:8800

This will open the home page of MigratoryData Server which contains docs and demos.

Hint

If a browser is not available on the machine where MigratoryData Server has been installed, then, supposing the address of the machine is push.example.com and the port 8800 is not blocked by the firewall of the machine, you can remotely test the installation by opening the following URL from a remote machine:

http://push.example.com:8800

3. The next step is to build your client applications to communicate with your MigratoryData Server installation. Please refer to the Developer’s Guide and Reference Manual of the MigratoryData client SDK that you intend to use to learn how to build client applications for MigratoryData Server.

Upgrade MigratoryData Server

To upgrade MigratoryData Server to a newer version, run as root the following command:

dpkg -i migratorydata-NewVersion-Architecture.deb

Note

The upgrade process will preserve your customized configuration files to ensure the continuity of your service. A copy of the default configuration of the new version is also provided with the extension .dpkg-dist if it differs from the default configuration of the installed version.

Uninstall MigratoryData Server

To remove MigratoryData Server from your system, run as root the following command:

dpkg --purge migratorydata

Linux RPM: RHEL, CentOS

The installation procedure described in this section has been tested on Red Hat Enterprise Linux (RHEL) and CentOS 64-bit distributions.

Install OpenJDK Java Runtime Environment

As discussed in the requirements section, the Java Runtime Environment (JRE) version 8 (or later) is required for running MigratoryData Server. To install the JRE version 8 of OpenJDK, run as root:

yum install java-1.8.0-openjdk-headless

Validate your installation with the following command:

java -version

The output should be something like:

openjdk version "1.8.0_212"
OpenJDK Runtime Environment (build 1.8.0_212-b04)
OpenJDK 64-Bit Server VM (build 25.212-b04, mixed mode)

Install OpenSSL for Native TLS/SSL Communication

As discussed in the requirements section, the OpenSSL and APR libraries are required to enable the native TLS/SSL communication. To install these libraries, run as root:

yum install apr openssl

Install MigratoryData Server

Download the RPM package of MigratoryData Server and run as root the following command to install it:

rpm -vi migratorydata-Version-Architecture.rpm

This will deploy MigratoryData Server as follows:

Location

Description

/etc/migratorydata/migratorydata.conf

The default configuration file

/etc/sysconfig/migratorydata

The default system configuration file

/var/log/migratorydata/

The folder where the logs will reside

/usr/share/migratorydata/migratorydata.jar

The object code of the MigratoryData server

/usr/share/migratorydata/extensions

The folder where extensions/plugins reside

/usr/bin/migratorydata

The MigratoryData start script

/lib/systemd/system/migratorydata.service

The systemd unit file

/usr/share/doc/migratorydata

The folder where docs & license info reside

Note

Please refer to Configuration Guide, Sections “Using Configuration File” and “Using Environment Variables” to learn how to customize the default configuration file and the default system configuration file.

After installation:

1. The service will start automatically when the machine reboots. To manually start, stop, restart, and get the status of the service, run as root one of the following commands:

systemctl start migratorydata
systemctl stop migratorydata
systemctl restart migratorydata
systemctl status migratorydata

2. To test the installation start a web browser on the machine where MigratoryData Server has been installed and open the following URL:

http://localhost:8800

This will open the home page of MigratoryData Server which contains docs and demos.

Hint

If a browser is not available on the machine where MigratoryData Server has been installed, then, supposing the address of the machine is push.example.com and the port 8800 is not blocked by the firewall of the machine, you can remotely test the installation by opening the following URL from a remote machine:

http://push.example.com:8800

3. The next step is to build your client applications to communicate with your MigratoryData Server installation. Please refer to the Developer’s Guide and Reference Manual of the MigratoryData client SDK that you intend to use to learn how to build client applications for MigratoryData Server.

Upgrade MigratoryData Server

To upgrade MigratoryData Server to a newer version, run as root the following command:

rmp -vU migratorydata-NewVersion-Architecture.rpm

Note

The upgrade process will preserve your customized configuration files to ensure the continuity of your service. A copy of the default configuration of the new version is also provided with the extension .rpmnew if it differs from the default configuration of the installed version.

Uninstall MigratoryData Server

To remove MigratoryData Server from your system, run as root the following command:

rpm -ve migratorydata

Platform Independent

The installation procedure described in this section has been tested on Windows, Linux, and Mac OS.

As discussed in the requirements section, the Java Runtime Environment (JRE) version 8 (or later) is required for running MigratoryData Server. To install the JRE version 8 of OpenJDK, follow the specific instructions for your operating system.

Download and extract the tarball distribution of MigratoryData Server to any folder. You will have the following layout in your installation folder:

Location

Description

html

Folder where the welcome page resides

logs

The folder where the logs will reside

migratorydata.conf

The default configuration file

migratorydata.jar

The object code of the MigratoryData server

extensions

The folder where extensions/plugins reside

start-migratorydata.bat

The start script for Windows

start-migratorydata.sh

The start script Linux/Unix/MacOS

README.txt

A short introduction to the product

LICENSE.txt

The MigratoryData license info

THIRD-PARTY-LICENSES

Folder with the third party license info

Note

Please refer to Configuration Guide, Sections “Using Configuration File” to learn how to customize the default configuration file and the default system configuration file.

After installation:

1. To start MigratoryData Server, open a console/terminal, change to the directory where MigratoryData Server package has been extracted, and run one of the following commands:

For Windows:

start-migratorydata.bat

For Linux/Unix/MacOS:

./start-migratorydata.sh

2. To test the installation start a web browser on the machine where MigratoryData Server has been installed and open the following URL:

http://localhost:8800

This will open the home page of MigratoryData Server which contains docs and demos.

Hint

If a browser is not available on the machine where MigratoryData Server has been installed, then, supposing the address of the machine is push.example.com and the port 8800 is not blocked by the firewall of the machine, you can remotely test the installation by opening the following URL from a remote machine:

http://push.example.com:8800

3. The next step is to build your client applications to communicate with your MigratoryData Server installation. Please refer to the Developer’s Guide and Reference Manual of the MigratoryData client SDK that you intend to use to learn how to build client applications for MigratoryData Server.

Cloud

This section is a guideline for running the MigratoryData server on cloud infrastructure (either private or public).

Docker and Kubernetes

Please refer to the MigratoryData documentation available on the Docker hub.