Entity resolution: Installing

This section is for administrators setting up Entity Resolution for the first time.

For configuring the feature once installed, see how to configure Entity Resolution.

Entity Resolution versions

When installing the Entity Resolution service, please refer to this table for compatibility between the Linkurious Enterprise server and the Entity Resolution server:

When updating from Linkurious Enterprise from v4.2.0 to v4.2.1, you must clear Entity Resolution results.

Installation steps

The following steps will help you run Entity Resolution using the docker command line.

If you are working with Kubernetes, you can start quickly with our public helm chart.

Step 1: Download the Docker image

The Entity Resolution server can only be download via the Linkurious private Docker repository. Follow the same instructions to deploy Linkurious Enterprise.

ℹ️ You will need to replace the linkurious-enterprise:4.2.8 image name with linkurious-entity-resolution:1.2.0.

Step 2: Prepare the database

The Entity Resolution server requires access to an existing MySQL or a MSSQL database.

⚠️ Despite MySQL is supported, MariaDB is not and is known for having compatibility issues.

ℹ️ For the first run, you will need to create a specific database for the entity resolution service (called my-database-name in the examples below).

To connect to the database, you need to set environment variables when starting the linkurious-entity-resolution docker container.

For simplicity, you can create a file called linkurious-er.env (used in below commands) to store the relevant environmental variables.

MySQL

Example configuration for MySQL:

SENZING_DATABASE_VENDOR=mysql
SENZING_DATABASE_HOST=127.0.0.1
SENZING_DATABASE_PORT=3306
SENZING_DATABASE_NAME=my-database-name
SENZING_DATABASE_USER=my-database-user
SENZING_DATABASE_PASSWORD=my-database-password

MSSQL

SENZING_DATABASE_TRUST_CERTIFICATE is optional, and only supported on MSSQL. When set to true, connecting to the database using a self-signed certificate is allowed. It is recommended to set this variable to false in production.

Example configuration for MSSQL:

SENZING_DATABASE_VENDOR=mssql
SENZING_DATABASE_HOST=127.0.0.1
SENZING_DATABASE_PORT=1433
SENZING_DATABASE_NAME=my-database-name
SENZING_DATABASE_USER=my-database-user
SENZING_DATABASE_PASSWORD=my-database-password
SENZING_DATABASE_TRUST_CERTIFICATE=true

Step 3: Start the Entity Resolution service

docker run -p 8080:8080 --env-file ./linkurious-er.env MY_PRIVATE_REGISTRY/linkurious/linkurious-entity-resolution:1.2.0

Visit http://localhost:8080/status to confirm the service is running (it will show the service uptime in seconds):

{"status":"API is up","uptime":10}

Step 4: Enable Entity Resolution and set up the service URL in the configuration

Go to Global configuration > Entity Resolution to enable Entity resolution in Linkurious Enterprise and set the service URL for your local setup.

{
  "enabled": true,
  "url": "http://localhost:8080"
}

For more information, see how to configure Entity Resolution.

Production setup

In production, it is strongly recommended to enable authentication and use private networking.

Authentication

You can enable authentication to make sure that API calls to the Entity Resolution service are only accepted if the call contains an API Key.

To enable authentication:

1. Start the linkurious-entity-resolution docker container with a LINKURIOUS_ENTITY_RESOLUTION_API_KEY environment variable (the key must be at least 32 characters long).
2. In Linkurious Enterprise, in the Global Configuration, edit the Entity Resolution section to use the same API Key:

   {
     "enabled": true,
     "url": "http://my-linkurious-entity-resolution-server.svc:8080",
     "serviceApiKey": "your api key here"
   }
   

Networking

The docker image exposes the port 8080 for HTTP connections, but you can use another port via docker mapping. Please visit the docker documentation to learn how publish the ports of a container.

In production, we strongly advise you to use a private network between Linkurious Enterprise and the Entity Resolution service.

Monitoring

The Entity Resolution container will deploy a Java based Web Server and the Senzing library. Standard Java configurations can be passed via environmental variables for more advanced deployments.

The Java Web Server can be monitored using Prometheus, which is an open source monitoring tool, by adding the following environment variable to the existing list:

PROMETHEUS_METRICS_ENABLED=true

When metrics are enabled, the docker image also exposes the port 9400 for HTTP connections, but you can use another port via docker mapping. The API endpoint on /metrics that can be scrapped by Prometheus (http://localhost:9400/metrics).

Scalability

The system is not designed to scale horizontally with automatic deployments of multiple replicas (docker scale option).

In case you have an high volume of data and experience some performance issues, please get in touch.