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
-
Create a directory called keymaker
-
Download the file here into keymaker
2.2 Unpack
-
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
-
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:
-
Rename the license file you received to license.lic
-
Replace the license.lic file in <keymaker_install>/config/keymaker-license with the received license.lic file
-
-
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:
-
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
-
Using the returned id, run:
docker exec -it <returned id> /bin/sh
-
At the prompt open a cypher-shell:
./bin/cypher-shell
-
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.
-
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.
-
Type :exit to exit the neo4j prompt, and exit to exit the shell.
-
In the docker-compose.yml file, replace the old password with the new password everywhere you see NEO4J_PASSWORD. Save your changes.
-
Restart keymaker by running:
./keymaker.sh stop ./keymaker.sh start
-
Once keymaker starts, login to the Keymaker Admin UI.
-
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:
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:
File | Parameter | Value |
---|---|---|
keymaker-ui/env-config.js |
REACT_APP_GRAPHQL_URI |
|
keymaker-ui/env-config.js |
REACT_APP_RECOMMENDATION_URI |
|
movies-ui/env-config.js |
REACT_APP_GRAPHQL_URI |
|
movies-ui/env-config.js |
REACT_APP_RECOMMENDATION_URI |
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:
File | Parameter | Value |
---|---|---|
keymaker-ui/env-config.js |
REACT_APP_GRAPHQL_URI |
|
keymaker-ui/env-config.js |
REACT_APP_RECOMMENDATION_URI |
|
movies-ui/env-config.js |
REACT_APP_GRAPHQL_URI |
|
movies-ui/env-config.js |
REACT_APP_RECOMMENDATION_URI |
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. |