Docker Container

For super fast deployment we also offer a Docker Container which you can access on our Docker Page here.

The Docker image is designed to be used in a micro-service environment. There are two versions of the image you can choose from.

The hub Repository: Contains stable releases of our Hub Service REST API. It is easy to start the service and full documentation on the REST API can be found here. Tag names correspond to the release version of the software. There is no latest tag to avoid confusion when patches are made to older releases.

The hub-prerelease repository: Contains automated builds with our most recent development updates. This means that it must not be used in a production environment but can be used for testing upcoming features. As this repository is under constant development it is particularly susceptible to new issues that will be fixed before a stable release is produced.

To use either of these images, you must provide a valid activation code after the service has started. /Refer to Activation for more information. If you are not an existing customer and require an activation code, then contact Syniti Support and register on the site.

Activation

Whether you are an existing customer or not, contact Syniti Support for the activation code for the matchIT Hub user authentication service and to receive the Docker image.

Register on the site, and select these options. For assistance with any registration issues, you can email T1@syniti.com.

When you first create a matching engine you must provide an activation code before it will start accepting data. This can either be done in the Engine Creation resource or the activation code can be provided later using the Initialization resource.

Update to a newer version of the Hub Service

The Hub Service runs an in-memory database and data is not stored persistently / on disk. You must make a copy of your data before attempting an upgrade.

To update the Hub Service container:

Make a copy of your data.
Pull the new image from the repository
Start the new image
Add your data to it.
Discard the old container.

Here is an example.

$ Docker pull 360science/hub:<new_tag>

$ Docker stop <old_container>

$ Docker rm <old_container>

$ Docker run <OPTIONS> -d 360science/hub:<new_tag>

There is no persistent relationship between versions of Hub Service so runtime options e.g., exposing a different port on the Docker host as port 8080 in the container, can freely change between versions.

Configure HTTPS and SSL for Docker

Documentation on configuring HTTPS/SSL in a generic environment can be found on our website here. This section contains steps to configure Docker.

Prerequisites

You have already created your jks keystore and have the password available to you.
The keystore password and key password are the same.
You have already pulled the Docker image of 360science/hub you wish to use

To configure HTTPS and SSL:

Create a config file like the one below. The path for the keystore will be where we mount it on the container. Refer to this example:

<?xml version="1.0" encoding="UTF-8"?>

<config>

<service>

<host>https://0.0.0.0:8080</host>

<keystoreLocation>/mnt/keystore/keystore.jks</keystoreLocation>

<keystorePassword>password</keystorePassword>

<authenticate>false</authenticate>

<credentialLocation>/mnt/keystore/pass.enc</credentialLocation>

<compressionMinSize>1048576</compressionMinSize>

</service>

</config>
Create a new Docker volume (to be mounted later to our Hub Service container). Replace <volume> in the example below with your volume name.

$ Docker volume create <volume>
keystore
Add the keystore and config file to the volume.

$ Docker run --name hubService -v <volume>:/mnt/keystore --entrypoint /bin/sh -d -it 360science/hub:<tagname>

9e2178b1afc0e2b89da09894350f95741709db1eff3e083dedc1c4caefbb88ea

$ Docker cp </your/path/to/keystore.jks> hubService:/mnt/keystore/keystore.jks

$ Docker cp </your/path/to/config.xml> hubService:/mnt/keystore/config.xml
Confirm that the files are in the correct location and that the path contained in the config.xml matches the actual path to the keystore:

$ Docker exec hubService ls /mnt/keystore

keystore.jks

config.xml
Stop this container. With the previous steps, the Docker volume has been persistently changed so we can stop and remove this container without losing changes to the volume.

$ Docker stop hubService

hubService

$ Docker rm hubService

hubService
Start a new container using the default entrypoint, mounting the volume again and letting the service know where the config file is:

$ Docker run -v <volume>:/mnt/keystore --name hubService -p 8080:8080 -d 360science/hub:<tagname> -config=/mnt/keystore/config.xml

2b788515bf948ea7fd8d72551020146923d261f1fcbb71f5a02f6d06165067e2
After running the preceding step, the service is up. Use curl from the host to check that it's accessible:

$ curl -X GET https://localhost:8080/matchITHub/status

<html><head><title>matchIT Hub Service status</title>

...

NOTE: You may get an error similar to the one below. This likely implies you're using a self certified certificate that cannot be trusted. Using the curl -k option will allow trusting of this certificate but it is insecure. Once you have replaced your keystore with a certificate that is signed by a trusted third party this error will go away.

$ curl -X GET https://localhost:8080/matchITHub/status

curl: (77) schannel: next InitializeSecurityContext failed: SEC_E_UNTRUSTED_ROOT (0x80090325) - The certificate chain was issued by an authority that is not trusted.

$ curl -k -X GET https://localhost:8080/matchITHub/status

<html><head><title>matchIT Hub Service status</title>

Enabling User Authentication

Add user credentials that can be used for authentication after the container has restarted.

$ curl -X POST https://localhost:8080/matchITHub/users --data-urlencode user=admin --data-urlencode role=admin --data-urlencode password=examplepassword123

$ curl -X POST https://localhost:8080/matchITHub/users --data-urlencode user=user --data-urlencode role=user --data-urlencode password=examplepassword456
Update the config file to enable authentication i.e., <authenticate>true</authenticate> . This may be simplest by editing the file on your local machine and then copying to the container:

$ Docker cp </your/path/to/config.xml> hubService:/mnt/keystore/config.xml
Restart the container.

$ Docker restart hubService

hubService
Provide credentials to access the service.

$ curl -X GET https://localhost:8080/matchITHub/status

Request requires login.

$ curl -X GET https://localhost:8080/matchITHub/status -u admin:examplepassword123

<html><head><title>matchIT Hub Service status</title>

Using the Image

All images contain a Java web server and, by default, expose port 8080. To start the container type:

$ Docker run -p 8080:8080 -d 360science/hub:<tagname>

After it has started, you can access Hub Service at http://localhost:8080/matchITHub from your host system.

To initially confirm that it is up you can query http://localhost:8080/matchITHub/status. This is the same endpoint as used for the default Health Check.

For further information on the REST API exposed by this Hub Service please read our documentation starting with an introduction. Alternatively, you can skip the introduction and go straight to the technical information here.

Migrate an Existing Installation

If you're already using Hub Service and want to switch to Docker follow these steps:

If necessary, upgrade your existing environments to the latest version of Hub Service.
Confirm your existing environments work with the latest release,
Pull that release version from the hub repository.

$ Docker pull 360science/hub:<new_tag>
If https / SSL is required then please refer to the configuration guide.
Start your container and test the endpoint is up at http://localhost:8080/matchITHub/status!

matchIT Hub Index