Keymaker Installation and Operation

This document describes how to install the Keymaker + Movies 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.

2.1 Download

  1. Create a directory called keymaker

  2. Download the file here into keymaker

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

    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
    Starting keymaker_keymaker-neo-db_1 ... done
    Starting keymaker_movies-api_1                    ... done
    Recreating keymaker_keymaker-engine-api_1 ... done
    Starting keymaker_keymaker-admin-api_1            ... done
    Recreating keymaker_movies-ui_1                   ... done
    Recreating keymaker_keymaker-ui_1                 ... done
    Keymaker should be available in a few minutes
      Keymaker Admin UI: http://localhost:36081
      Movies Demo UI: http://localhost:36080
      Neo4j Database UI: http://localhost:36474 (bolt://localhost:36687)

If you installed Keymaker on a local machine, you should be able to access the Keymaker Admin UI and the Movies Demo UI using the URLs 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.

2.3 Change Neo4j password

It is highly recommended that you change the Neo4j password for the Neo4j instance that comes bundled with Keymaker. To change the password you will shell into the Neo4j docker instance, change it, then update the configuration files with the new password. Follow these steps:

  1. Run this command to find the docker id of Neo4j

    docker ps | grep neo4j | cut -d " " -f1

    The output will look similar to this:

    0d98c3a6df4e
  2. Using the returned id, run:

    docker exec -it <returned id> /bin/sh
  3. At the prompt open a cypher-shell:

    ./bin/cypher-shell
  4. Type the username and password. The username should be neo4j and the password can be found in the docker-compose.yml file as the value of NEO4J_PASSWORD.

  5. At the prompt type:

    ALTER CURRENT USER SET PASSWORD FROM '<old password>' to '<new password>';

    Where <old password> is the value of the NEO4J_PASSWORD you found in docker-compose.yml, and <new password> is the password you have chosen.

  6. Type :exit to exit the neo4j prompt, and exit to exit the shell.

  7. In the docker-compose.yml file, replace the old password with the new password everywhere you see NEO4J_PASSWORD. Save your changes.

  8. Restart keymaker by running:

    ./keymaker.sh stop
    ./keymaker.sh start
  9. Once keymaker starts, login to the Keymaker Admin UI.

  10. Under Database Connections, edit Movies DB using the pencil icon, click Update Credentials, then enter neo4j and your new password. When finished, click Submit. You may have to refresh the page to see the icon turn to a green checkmark.

3. Keymaker Admin UI

You can access the Keymaker Admin UI here: http://localhost:36081.

The first time you login, you will be prompted with a screen "What’s your email?" You can enter any valid email address here, for example, [email protected]. Remember this email as you will need it to log back in later. There is no password protection and there is only a single email account allowed for this installation.

Upon initial login, you will 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. Movies Demo

The install comes pre-configured with the Movies Keymaker demo. You can access that demo here: http://localhost:36080.

6. Accessing Neo4j

Neo4j can be accessed via the Neo4j Browser here: http://localhost:36474.

To login use these parameters:

  • Connection URL: bolt://localhost:36687

  • Username: neo4j

  • Password: use value of NEO4J_PASSWORD in docker-compose.yml

The default database, neo4j, contains the data for Keymaker. The movies demo database is called movies.

You can access the movies database, by typing :use movies in the Neo4j Browser. Type :use neo4j to get back to the Keymaker database.

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

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

36080

TCP

HTTP port for the Movies Demo UI

36081

TCP

HTTP port for the Keymaker Admin UI

36443

TCP

HTTPS port for the Movies Demo UI (you only need either 36080 or 36443 open)

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

movies-ui/env-config.js

REACT_APP_GRAPHQL_URI

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

movies-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 Movies Demo UI:

http://<your-hostname>:36080

For Keymaker Admin UI:

http://<your-hostname>:36081

9. Enabling HTTPS

This section describes how to turn on HTTPS for Keymaker.

9.1 Certificate

The keymaker bundle comes with a self-signed certificate. You can use this certificate to enable HTTPS, or you can replace it with your own certificate. Important: Note that if you use the self-signed certificate, you will need to tell your web browser that the certificate should be trusted. The steps on how to do that are beyond the scope of this document.

There are two files that make up the certificate:

  • neo4j.com.crt

  • neo4j.com.key

These files are located under the keymaker install directory in three locations:

  • keymaker/config/keymaker-certificate

  • keymaker/config/keymaker-ui-nginx

  • keymaker/config/movies-ui-nginx

If you use your own certificate, you should replace the neo4j.com.* versions in all three directories.

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

movies-ui/env-config.js

REACT_APP_GRAPHQL_URI

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

movies-ui/env-config.js

REACT_APP_RECOMMENDATION_URI

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

In docker-compose.yml, look for these configuration blocks under keymaker-admin-api, keymaker-engine-api, and movies-api:

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

Change it so that http is commented out and https is uncommented. If you are using your own certificates, you can specify the filenames here.

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

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

10. Users (Enterprise only)

The create-user.sh command line utility has been provided to create users in Keymaker. This feature is only available in the Enterprise version. If you run it under Keymaker Basic, you will get an error.

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]
Currently Keymaker Basic allows a single user with no specified password. If you upgrade to Enterprise, you will need to run the ./create-user.sh command to set the password for the email you used with Keymaker Basic.