Deploy on Docker

This tutorial shows how to deploy MigratoryData using Docker.

Prerequisites

Before installing MigratoryData, ensure that you have the Docker runtime installed.

Pull image

Pull the image of the latest version of the MigratoryData server from Docker Hub:

docker pull migratorydata/server:latest

Install

Install the MigratoryData server in a Docker container named migratorydata, accepting clients on port 8800, as follows:

docker run -d \
--name migratorydata -p 8800:8800 migratorydata/server:latest

Verify installation

Check the running containers to ensure the migratorydata container is up:

docker ps

Test installation

If you have installed MigratoryData locally, access the following URL in your web browser:

http://localhost:8800

Otherwise, if you have installed MigratoryData on a remote machine, and assuming the host name for that machine is push.example.com (and the firewall does not block the port 8800), access the following URL in your web browser:

http://push.example.com:8800

In either scenario, you should see a welcome page that features a demo application under the Debug Console menu for publishing real-time messages to and consuming real-time messages from your MigratoryData installation.

Check the logs

You can see the logs of the migratorydata container using the following command:

docker logs migratorydata

Uninstall

To stop and remove the migratorydata container use:

docker stop migratorydata
docker rm migratorydata

Custom Configuration

It is possible to customize every aspect of the MigratoryData server running in a Docker container as described below.

Extra options

To customize the MigratoryData server within a Docker container, the environment variable MIGRATORYDATA_EXTRA_OPTS offers the flexibility to define specific parameters or adjust the default value of any parameter listed in the Configuration Guide.

For example, if you wish to install a MigratoryData container with a given license key (e.g., mykey) and allocate a specified amount of memory (e.g., 2048 MB), you can modify the default values of the LicenseKey and Memory parameters as follows:

docker run -d \
-e MIGRATORYDATA_EXTRA_OPTS='-DLicenseKey=mykey -DMemory=2048MB' \
--name migratorydata -p 8800:8800 migratorydata/server:latest

Java extra options

There are three environment variables MIGRATORYDATA_JAVA_GC_LOG_OPTS, MIGRATORYDATA_JAVA_GC_OPTS, and MIGRATORYDATA_JAVA_EXTRA_OPTS which can be used to customize the garbage collection logging options, the garbage collectors to be used, and respectively various other Java options.

All of these Java options come with default values which are sufficient for most use cases. Therefore, in most instances, it is not necessary to define these Java-related environment variables.

License key

To use a license key with this Docker image, override the parameter LicenseKey
of the default configuration file using an extra options as follows:

docker run -d \
-e MIGRATORYDATA_EXTRA_OPTS='-DLicenseKey=yourlicensekey' \
--name migratorydata -p 8800:8800 migratorydata/server:latest

where yourlicensekey is the license key obtained from MigratoryData for evaluation, test, or production usages.

Monitoring

To enable for example the JMX monitoring for MigratoryData, you should define the JMX related parameters as usual and publish the JMX port 3000 to the host as follows:

docker run -d \
-e MIGRATORYDATA_EXTRA_OPTS='-DLicenseKey=yourlicensekey -DMonitor=JMX -DMonitorUsername=admin -DMonitorPassword=pass -DMonitorJMX.Listen=*:3000 -DMonitorJMX.Authentication=true -DMonitorJMX.Encryption=false' \
--name migratorydata -p 8800:8800 -p 3000:3000 migratorydata/server:latest

You should now be able to connect with any JMX client to 127.0.0.1:3000 using the credentials defined here admin/pass.

In certain environments, to access the the JMX monitoring with Java’s JMX client jconsole, you should provide with MIGRATORYDATA_JAVA_EXTRA_OPTS two Java extra options as follows:

docker run -d \
-e MIGRATORYDATA_EXTRA_OPTS='-DLicenseKey=yourlicensekey -DMonitor=JMX -DMonitorUsername=admin -DMonitorPassword=pass -DMonitorJMX.Listen=*:3000 -DMonitorJMX.Authentication=true -DMonitorJMX.Encryption=false' \
-e MIGRATORYDATA_JAVA_EXTRA_OPTS='-Djava.net.preferIPv4Stack=true -Djava.rmi.server.hostname=127.0.0.1' \
--name migratorydata -p 8800:8800 -p 3000:3000 migratorydata/server:latest

Logging

Besides the logs provided to the standard output which are accessible with the command docker logs migratorydata, this image also writes the logs to a folder which defaults to /migratorydata/logs folder. You can change the log folder location, as follows:

docker run -d \
-e MIGRATORYDATA_EXTRA_OPTS='-DLicenseKey=yourlicensekey -DLogFolder=/myvolume/migratorydata/logs' \
--name migratorydata -p 8800:8800 migratorydata/server:latest

Extensions

In order to deploy one or more extensions for the MigratoryData server you should mount a volume with the extensions into the MigratoryData standard extensions folder which is /migratorydata/extensions.

For example, supposing you developed an authorization extension using MigratoryData’s Auth API and deployed authorization.jar to the folder /myvolume/migratorydata/extensions, then, in order to load this authorization extension, run:

docker run -d \
-e MIGRATORYDATA_EXTRA_OPTS='-DLicenseKey=yourlicensekey -DEntitlement=Custom' \
-v /myvolume/migratorydata/extensions:/migratorydata/extensions \
--name migratorydata -p 8800:8800 migratorydata/server:latest

Alternatively, you might load your authorization extension by creating a new image derived from migratorydata as follows:

FROM migratorydata
COPY authorization.jar /migratorydata/extensions/authorization.jar

Then, build it with docker build -t custom_migratorydata . and run:

docker run --name my_custom_migratorydata -d custom_migratorydata

Build realtime apps

Use any of the MigratoryData’s client APIs to develop real-time applications for communication with this MigratoryData container.