MigratoryData Server

Installation Guide

Version 5.0
July 19, 2019







Copyright Information

Copyright © 2007-2019 Migratory Data Systems. ALL RIGHTS RESERVED.

THIS DOCUMENT IS PROVIDED ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE DOCUMENT. MIGRATORY DATA SYSTEMS MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT DESCRIBED IN THIS DOCUMENT AT ANY TIME.


Contents

Introduction

This guide describes the installation of MigratoryData Server. It is recommended to read MigratoryData Architecture Guide before reading this document for a better understanding of the concepts and to have a more comprehensive background.

Release

This guide is part of the documentation set for MigratoryData Server version 5.0.

Related Documents

Requirements and recommendations

Supported Operating Systems

Written in Java, MigratoryData Server runs on all major operating systems: Linux/Unix, Mac OS, Windows, and potentially any other platform 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.

The recommended operating systems for production deployments are Red Hat Enterprise Linux or 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.

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 large deployments with lots 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.

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

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

Capacity Planning

You can estimate the hardware and the number of MigratoryData Server instances required for your use case by using MigratoryData Benchmark Kit, a software tool able to:

Linux

RPM Based Linux

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

Install OpenJDK Java Runtime Environment

As discussed in Section 2.2.1, 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_181"
OpenJDK Runtime Environment (build 1.8.0_181-8u181-b13-2 deb9u1-b13)
OpenJDK 64-Bit Server VM (build 25.181-b13, mixed mode)

Install OpenSSL for Native TLS/SSL Communication

As discussed in Section 2.2.2, the OpenSSL and APR libraries are required to enable 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. Please refer to MigratoryData Configuration Guide, Section "Using Configuration File", to learn how to customize it
/etc/sysconfig/migratorydata The default system configuration file. Please refer to MigratoryData Configuration Guide, Section "Using Environment Variables", to learn how to customize it
/var/log/migratorydata/ The logs folder
/usr/share/migratorydata/ The folder which contains the object code of MigratoryData Server as a JAR file
/usr/bin/migratorydata A script used by the init.d daemon script
/etc/init.d/migratorydata The init.d daemon script used to start, stop, and restart the MigratoryData Server service
/usr/share/doc/migratorydata Folder containing docs, examples, and licenses

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:

    /etc/init.d/migratorydata start

    /etc/init.d/migratorydata stop

    /etc/init.d/migratorydata restart

    /etc/init.d/migratorydata status

  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

    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 connected to push.example.com:

    http://push.example.com:8800

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

  3. The next step is to build your clients to communicate with your MigratoryData Server installation. Please refer to the Developer's Guide and Reference Manual of the client library that you intend to use to learn how to build clients 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

DEB Based Linux

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 Section 2.2.1, 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_181"
OpenJDK Runtime Environment (build 1.8.0_181-8u181-b13-2 deb9u1-b13)
OpenJDK 64-Bit Server VM (build 25.181-b13, mixed mode)

Install OpenSSL for Native TLS/SSL Communication

As discussed in Section 2.2.2, the OpenSSL and APR libraries are required to enable 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. Please refer to MigratoryData Configuration Guide, Section "Using Configuration File", to learn how to customize it
/etc/default/migratorydata The default system configuration file. Please refer to MigratoryData Configuration Guide, Section "Using Environment Variables", to learn how to customize it
/var/log/migratorydata/ The logs folder
/usr/share/migratorydata/ The folder which contains the object code of MigratoryData Server as a JAR file
/usr/bin/migratorydata A script used by the init.d daemon script
/etc/init.d/migratorydata The init.d daemon script used to start, stop, and restart the MigratoryData Server service
/usr/share/doc/migratorydata Folder containing docs, examples, and licenses

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:

    /etc/init.d/migratorydata start

    /etc/init.d/migratorydata stop

    /etc/init.d/migratorydata restart

    /etc/init.d/migratorydata status

  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

    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 connected to push.example.com:

    http://push.example.com:8800

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

  3. The next step is to build your clients to communicate with your MigratoryData Server installation. Please refer to the Developer's Guide and Reference Manual of the client library that you intend to use to learn how to build clients 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

Platform Independent

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

Install OpenJDK Java Runtime Environment

As discussed in Section 2.2.1, 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.

Install MigratoryData Server

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

Location Description
doc Folder containing the documentation set for MigratoryData Server
html Folder containing the home page of MigratoryData Server including documentations and examples
logs The logs folder
THIRD-PARTY-LICENSES Folder containing the licenses of the third-party components embedded in MigratoryData Server
LICENSE.txt Use of MigratoryData Server is subject to the license terms defined by this file
migratorydata.conf The default configuration file. Please refer to MigratoryData Configuration Guide to learn how to customize it
migratorydata.jar The object code of MigratoryData Server
README.txt A short introduction to the product
start-migratorydata.bat The start script of MigratoryData Server for Windows systems
start-migratorydata.sh The bash start script of MigratoryData Server for Linux/Unix systems

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 according to your operating system:

    start-migratorydata.bat

    Windows)

    ./start-migratorydata.sh

    (Linux/Unix)

  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

    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 connected to push.example.com:

    http://push.example.com:8800

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

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



mihai 2019-07-19