Keymaker Installation and Operation

This document describes how to install the Keymaker Docker distribution.

1. Prerequisites

  • You will need to have docker and docker-compose on your machine. You can get both by installing Docker Desktop.

  • Ensure you can run docker from the command line.

These instructions assume a Linux/Mac based install. If you have Unix shell support for Windows these instructions should also work.

2. Instructions

These instructions will take you through the steps of installing Keymaker using Docker.

2.1 Set up Neo4j Database

You will either spin up a free Aura DB instance or a Neo4j database instance using the Neo4j Desktop application.This database will serve as a backend storage for Keymaker.

  1. If you are running Aura or Neo4j Community, you will use the default database neo4j

  2. If you are running Neo4j Enterprise Edition, you can -

    • Use the default database neo4j or

    • Create a new database. See this link for instructions on how to create a Neo4j database

  3. For Neo4j Community or Enterprise Edition, you will also need to install APOC Core. For instructions on how to do this, please follow this link ( Aura DB users will already have this installed )

Once your database is set up correctly, we will need to run some cypher initialization scripts. Please follow the instructions listed in the cypher initialization scripts steps here

2.2 Keymaker Installation Using Docker

2.2.1 Download the Keymaker release

  1. Create a directory called keymaker

  2. Download the latest release here into keymaker

2.2.2 Unpack

  1. Open up a Terminal, and in the keymaker directory, run:

    tar xvf neo4j-keymaker-<version_number>.tar.gz

    You should see the following output:

    x create-user.sh
x docker-compose.yml
x keymaker.sh
x keymakerDocker.tar.gz
x keymaker_config.tar.gz
x keymaker_db.tar.gz

    The file keymaker should be executable, if not, run:

    chmod +x keymaker.sh
chmod +x create-user.sh

  2. Now run:

    ./keymaker.sh unpack

    This will unpack the database and the docker images

    Make sure to update the docker-compose.yml file with the environment variables for the following fields - NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD,NEO4J_DATABASE for both keymaker-admin-api and keymaker-engine-api. The environment configuration should reference the Neo4j database that we set up in previous section Note: If you have received a different license file, you can install it now by following these steps:

    1. Rename the license file you received to license.lic

    2. Replace the license.lic file in <keymaker_install>/config/keymaker-license with the received license.lic file

  3. Now run:

    ./keymaker.sh start

    You should see:

    Starting Keymaker services
Recreating keymaker_keymaker-engine-api_1 ... done
Starting keymaker_keymaker-admin-api_1            ... done
Recreating keymaker_keymaker-ui_1                 ... done
Keymaker should be available in a few minutes
  Keymaker Admin UI: http://localhost:36081

If you installed Keymaker on a local machine, you should be able to access the Keymaker Admin UI using the URL provided in the following sections. If you have installed Keymaker on a server or cloud machine you will need to perform some additional configuration to access the services. See Server Configuration later in this document.

3. Keymaker Admin UI

You can access the Keymaker Admin UI here: http://localhost:36081. You will be presented with a login screen, we need to set up users in order to login. Follow the steps below for creating a user on the database.

3.1 Creating Users for Neo4j Database

The create-user.sh command line utility has been provided to create users in Keymaker.

If you run ./create-user.sh with no arguments, it will display a usage message:

Usage: ./create-user.sh <email> <password> <name> [picture] [graphql port] [https]

The parameters display in square brackets are optional, however, for this deployment you will need to specify the [graphql port], and since the parameters are positional, the [picture] also. The graphql port is specified in the docker-compose.yml file. The value is 36402 unless someone changed it.

An example command looks like:

./create-user.sh [email protected] password "Keymaker Admin" "" 36402

The response looks like:

Creating [email protected]
{"data":{"createUserSignUp":{"email":"[email protected]","name":"Keymaker Admin","picture":""}}}
[source]

If you have configured HTTPS, you will need to specify 'https' as the last argument like this:

./create-user.sh [email protected] password "Keymaker Admin" "" 36402 https
[source]

Upon success, this will create a node in the database with the :User.

We will navigate to the Keymaker Admin UI here: http://localhost:36081 and enter the email and password that we created in the Creating Users step and hit or click the Submit button. You should now be logged in. Upon initial login, you may be prompted to accept the End-User License Agreement (EULA). Once the EULA is accepted, the Admin page will be opened.

4. Keymaker Engine API

The Keymaker Engine API is exposed here: http://localhost:36401/graphql.

5. Status and Shutting down

The keymaker command has two more options:

./keymaker.sh status

This will show the status of the docker images. If not running, nothing will be shown. If running, the list of docker images will be displayed.

./keymaker.sh stop

This will shutdown the keymaker docker images.

6. Verifying Installation and Using Keymaker

We can verify the Keymaker install by setting up some sample database connections and engines. Please refer to GitHub README and follow all the steps under Verifying Installation and Creating Database Connections and Engines for getting started with Keymaker.

7. Server Configuration

Stop keymaker by running:

./keymaker.sh stop

Next you need to ensure that the following ports are accessible between the server machine and the machine you will be testing with. In a cloud environment, this typically means adding firewall rules to the networking section of the cloud machine.

Please open the ports as specified in the following table:

Table 1. Keymaker Ports
Port Protocol Description

36081

TCP

HTTP port for the Keymaker Admin UI

36444

TCP

HTTPS port for the Keymaker Admin UI (you only need either 36081 or 36444 open)

36401

TCP

GraphQL port for the Keymaker Engine API

36402

TCP

GraphQL port for the Keymaker Admin API

36474

TCP

(Optional) Keymaker Neo4j Web Browser port. Only needed if you want to access the Neo4j database directly.

36473

TCP

(Optional) Keymaker Neo4j Web Browser secure port. Only needed if you want to access the Neo4j database directly.

36687

TCP

(Optional) Keymaker Neo4j Bolt port. Only needed if you want to access the Neo4j database directly.

Once you have opened up the firewall ports, there are a few changes you must make to the Keymaker configuration files to ensure the web applications can talk to the GraphQL endpoints. Please make the following changes to the configuration files located in the keymaker/config/ directory:

Table 2. Keymaker Configuration Files
File Parameter Value

keymaker-ui/env-config.js

REACT_APP_GRAPHQL_URI

http://<your-hostname>:36402/graphql

keymaker-ui/env-config.js

REACT_APP_RECOMMENDATION_URI

http://<your-hostname>:36401/graphql

Now restart keymaker by typing:

./keymaker.sh start

After a few minutes, you should be able to use your web browser to connect to:

For Keymaker Admin UI:

http://<your-hostname>:36081

8. Enabling HTTPS

This section describes how to turn on HTTPS for Keymaker.

8.1 Certificate

You can add your own SSL certificates for enabling HTTPS

There are two files that make up the certificate:

  • a certificate file ( cert file )

  • a private key

These files need to be under the keymaker install directory in two locations:

  • keymaker/config/keymaker-certificate

  • keymaker/config/keymaker-ui-nginx

8.2 Configuration

You need to make some configuration changes to enable HTTPS in both the env-config.js files and the docker-compose.yml file.

For the env-config.js files, everywhere there is an 'http' setting, change it to 'https' in the keymaker/config/ directory:

Table 3. Keymaker HTTPS Configuration
File Parameter Value

keymaker-ui/env-config.js

REACT_APP_GRAPHQL_URI

https://<your-hostname>:36402/graphql

keymaker-ui/env-config.js

REACT_APP_RECOMMENDATION_URI

https://<your-hostname>:36401/graphql

In docker-compose.yml, add these configuration blocks under keymaker-admin-api, keymaker-engine-api:

  - HOST_PROTOCOL=http
  #- HOST_PROTOCOL=https
  #- CERTIFICATE_DIR=/app/ssh_keys
  #- CERTIFICATE_KEY=app.com.key
  #- CERTIFICATE_CRT=app.com.crt

Update the HOST_PROTOCOL value to https. If you are using SSL certificates, you can specify the filenames here.

  #- HOST_PROTOCOL=http
  - HOST_PROTOCOL=https
  - CERTIFICATE_DIR=/app/ssh_keys
  - CERTIFICATE_KEY=app.com.key
  - CERTIFICATE_CRT=app.com.crt

Stop and start keymaker. You can now access the the Keymaker Admin UI at https://<your-hostname>:36444