360science/hub repository overview

⁠Quick reference

• Maintained by:
  360Science⁠

• Where to get help:
  the Docker Community Forums⁠, the Docker Community Slack⁠, or Stack Overflow⁠

• Where to file issues:
  Support⁠

• Supported architectures: amd64⁠. If other architectures are required please Contact Us⁠

⁠What is 360Science?

Data Matching, Reimagined.

Discover Enterprise-Grade Performance for Accurate Data Matching at Scale.

360Science fuses the power of data science and artificial intelligence to deliver matchit® – the only matching engine built from the ground up for customer data applications. Match, unify, and merge customer data without the need for correction, standardization, manipulation or enrichment. The AI matching logic is tolerant to the wide variations found in working with customer data – yet amazingly accurate.

⁠How to use this image

This 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⁠. There is no latest tag to avoid confusion when patches are made to older releases. Tag names correspond to the release version of the software.

The second option is the hub-pre-release repository. This 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 a valid activation code must be provided after the service has started. If you are not an existing customer and require an activation code then please Contact Us⁠. Alternatively, if you are an existing customer then please email us:

• US Support⁠
• UK Support⁠

⁠Using the image

All images contain a java webserver and, by default, expose port 8080. To start the container type:

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

Now 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⁠

⁠Activation

If you are not an existing customer and require an activation code then please Contact Us⁠. Alternatively, if you are an existing customer then please email us:

• US Support⁠
• UK Support⁠

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

Hub Service runs an in-memory database and data is not stored persistently / on disk. Please ensure you have a copy of your data before attempting an upgrade. Updating the Hub Service container can be simply done by pulling the new image from the repository, starting the new image and adding your data to it. The old container can then be discarded.

$ 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 can freely change between versions e.g. Exposing a different port on the Docker host as port 8080 in the container.

⁠HTTPS and SSL configuration

Documentation on configuring HTTPS/SSL in a generic environment can be found on our website here⁠. In this section we will go into detail on specifically configuring this for 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 image of 360science/hub you wish to use

⁠Steps

1. Create a config file like the one below. The path for the keystore will be where we mount it to on the container. For now we will assume you use the same paths as us.

   <?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>
   		<compressionMinSize>1048576</compressionMinSize>
   	</service>
   </config>
   

   Copy

2. Create a new docker volume. We will later mount this to our Hub Service container. Replace <volume> with what you want to call this volume.

   $ docker volume --name <volume>
   keystore
   

   Copy

3. Now we 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
   

   Copy

   We can double check that the files are where we expect. Make sure 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
   

   Copy

   Let's stop this container. 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
   

   Copy

4. Start a new container using the default entrypoint but we need to mount the volume again and let 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
   

   Copy

5. We're done! The service is up and we can 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>
   ...
   

   Copy

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

   Copy

⁠Migrating an existing installation

You're already using Hub Service and want to switch to docker? Here's what to do:

1. If necessary, first upgrade your existing environments to the latest version of Hub Service.

2. Now that we have confirmed your existing environments work with the latest release, pull that release version from the hub⁠ repository.

   $ docker pull 360science/hub:<new_tag>
   

   Copy

3. If https / SSL is required then please refer to the above configuration guide⁠.

4. Start your container and test the endpoint is up at http://localhost:8080/matchITHub/status⁠!

⁠Questions / Issues

If you have any questions or problems using the images, please Contact Us⁠.

⁠License

Please find our licensing terms here:

The Americas, Australia and New Zealand⁠

United Kingdom, Africa, Asia and Europe⁠