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 Syniti Match API 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 Syniti Match API 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!