Installation

This document describes how to install and operate the Cypher Workbench 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.
You will need a Neo4j Database to store the data you create in Cypher Workbench. You can use either Neo4j AuraDB or a Neo4j database system you administer yourself, such as Neo4j Enterprise Edition, Neo4j Desktop, or Neo4j Community.

Once you have Docker installed and a Neo4j database instance, you can proceed with the installation.

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

2.1 Download

Create a directory called workbench
Download the file here into workbench

2.2 Unpack

Open up a Terminal, and in the workbench directory, run:

tar xvf neo4j-cypher-workbench-1.5.0.tar

You should see the following output:

x cw-config.tar.gz
x docker-compose.yml
x envConfig.sh
x makeEnv.sh
x makeEnvConfig.sh
x makeNginxConf.sh
x workbenchDocker.tar.gz
x workbench_labs

The file workbench_labs and all of the .sh scripts should be executable, if not, run:

chmod +x workbench_labs
chmod +x *.sh

Now run:

./workbench_labs unpack

This will unpack the database and the docker images. You should see:

*** Unpacking config ***

x cw-config/
x cw-config/cw-db-setup/
x cw-config/cw-ui-nginx/
x cw-config/cw-certificate/
x cw-config/cw-ui-template/
x cw-config/cw-api/
x cw-config/cw-ui/
x cw-config/cw-ui-nginx-template/
x cw-config/cw-ui-nginx-template/nginx.conf.template
x cw-config/cw-api/license.lic
x cw-config/cw-ui-template/env-config.js.template
x cw-config/cw-certificate/workbench.crt
x cw-config/cw-certificate/workbench.key
x cw-config/cw-ui-nginx/dhparam.pem
x cw-config/cw-ui-nginx/workbench.crt
x cw-config/cw-ui-nginx/workbench.key
x cw-config/cw-ui-nginx/workbench-ssl-params.conf
x cw-config/cw-db-setup/cypher_constraints_v4.3.cypher
x cw-config/cw-db-setup/cypher_init_data.cypher
x cw-config/cw-db-setup/cypher_constraints_v4.4_to_5.cypher
x scripts/
x scripts/make-credential-file.sh
x scripts/create-user.sh

*** Unpacking docker images ***

Loaded image: cypher-workbench-ui:1.5.0_labs
Loaded image: cypher-workbench-api:1.5.0_labs

2.3 Setup a Neo4j database

You will need to setup an Aura instance or a Neo4j database to use as the backend storage for Cypher Workbench.

If you are running Aura or Neo4j Community, you will use the default database neo4j.
If you are running Neo4j Enterprise Edition, you can:
- Use the default database neo4j
- Create a new database. See this link for instructions on how to create a Neo4j database.
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 users will already have this installed.

Once the database is ready you need to configure the docker-compose.yml file and you need to run some Cypher initialization scripts.

docker-compose.yml configuration

Edit the docker-compose.yml file. Using the information for your Neo4j database instance, please update these fields in the docker-compose.yml file:

NEO4J_URI=<uri of database>
NEO4J_USER=<neo4j user>
NEO4J_PASSWORD=<neo4j user password>
NEO4J_DATABASE=<neo4j database>

Example 1 - using a Neo4j database called workbench on your local machine:

NEO4J_URI=bolt://host.docker.internal:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=workbench

Example 2 - using a Neo4j AuraDB:

NEO4J_URI=neo4j+s://abcdefgh.databases.neo4j.io
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=

After making the changes, save the file.

Note: in the first example, host.docker.internal points to the localhost of the machine running the docker images. If you were to use localhost by itself, it would point within the docker image itself, which is not running a Neo4j database.

Cypher initialization scripts

Within the folder cw-config/cw-db-setup/ you will find a few Cypher scripts:

cypher_constraints_v4.3.cypher
cypher_constraints_v4.4_to_5.cypher
cypher_init_data.cypher

Pick the cypher_constraints file that matches the database version you are running. If you are running a version older than 4.3, you may have to manually adjust the syntax to match the expected syntax of your Neo4j version.

Follow these steps to run the Cypher:

Run either Neo4j Browser or Workspace and connect to your Neo4j database
Copy/paste the correct cypher_constraints_vX.X.cypher into Browser/Workspace and execute it
- If running in Browser, make sure this setting is checked: "Enable multi statement query editor"
Copy/paste the cypher_init_data.cypher file into Browser/Workspace and execute it

You are now ready to start Cypher Workbench.

2.4 Starting Cypher Workbench

Once your database is configured and setup, and you have made the necessary docker-compose.yml changes, you are ready to start Cypher Workbench. Cypher Workbench consists of two docker images configured to work together using docker compose. The two images are:

cypher-workbench-ui:1.5.0_labs
cypher-workbench-api:1.5.0_labs

The first docker image hosts the React web application which contains the user interface you will access from your web browser. The second docker image is a GraphQL API layer that communicates to the Neo4j database you set up. The React web application layer makes requests to the GraphQL API layer.

To start Cypher Workbench open up a Terminal, and in the workbench directory, run:

./workbench_labs start

You should see:

Starting Cypher Workbench services
Starting cypher-workbench_cypher-workbench-api_1 ... done
Starting cypher-workbench_cypher-workbench-ui_1  ... done
Cypher Workbench should be available at http://localhost:80 in a few minutes

Wait about 30 seconds, then click http://localhost:80. You should be redirected to the user login page. You will not be able to login until you have set up at least one user. Setting up users is discussed in the next session.

2.5 Logging In

Assuming you installed this locally, use your web browser to navigate to http://localhost:80. You will be presented with a login screen.

The initialization script created a default user called admin with password neo4j. Enter admin for email and neo4j for password and hit <Enter> or click the Continue button. You should now be logged in.

For a discussion on how to add other Admin users, and a discussion on the overall security model of Cypher Workbench, see Security.

2.6 Setting up users

This section shows how to create additional normal (non-admin) users.

Method 1

To create a user, follow these steps:

Run this command to find the docker id of the cypher-workbench-api docker image
```
docker ps | grep cypher-workbench-api | cut -d " " -f1
```
The output will look similar to this:
```
0d98c3a6df4e
```
Using the returned id, run:
```
docker exec -it <returned id> /bin/sh
```
You will see a # prompt. You will be running the createUser.js script which requires a few arguments. The arguments are:
- primaryOrganization: name of the organization to add the user to. On initial setup, there is only valid organization: Neo4j
- email: the email address of the user
- password: the password for the user
- name: the user’s name. This needs to be enclosed in quotes if there are spaces.
- adminEmail: the email of a user with Admin privilege. Enter admin for this. (Note: If you deleted all :User nodes from the database, you can leave this blank, and it will create the first :User with :Admin privilege.)
  
  The syntax of the command looks like:
  
  node users/createUser.js <primary organization> <email> <password> "<full name>" <adminEmail>

Run the createUser command and replace email, password, and full name with the appropriate values:

node users/createUser.js Neo4j <email> <password> "<full name>" admin

The method will print out the arguments and a JSON response, as shown in the following output:

process.env.NEO4J_URI: bolt://host.docker.internal:7687
[ 'Neo4j', '[email protected]', 'password', 'First Last' ]
args:  Neo4j [email protected] password First Last
{
  name: 'First Last',
  primaryOrganization: 'Neo4j',
  email: '[email protected]',
  picture: '',
  encryptedPassword: 'U2FsdGVkX1/GZpCrLSPcAhm0LLbEawqSZZ1Rn7X7Yi4='
}

You can now exit the docker shell by typing exit and hitting <Enter>.

You should now be able to use this username and password and login to Cypher Workbench at http://localhost:80.

Method 2

There is also a shell script that calls a GraphQL endpoint that can be invoked to create users. This section describes how to invoke the create-user.sh shell script.

Security Note: Unless you have configured Cypher Workbench to run using HTTPS, then it is recommended you use the createUser.js method by shelling into the cypher-workbench-api Docker image as described in the previous section. This method uses HTTP Basic Authentication and the username:password will be passed using a Base-64 encoding scheme, and they will not be encrypted.

Follow these steps to create a user:

Goto the scripts directory
```
cd scripts
```

Make a credential file of the Admin username and password

./make-credential-file.sh <admin-email> <admin-password> <output-credential-file.txt>

Run the create-user.sh command

./create-user.sh <credentials.txt> <primaryOrganization> <email> <password> <name> [picture] [host] [graphql port] [https]

Example:

./create-user.sh ./my_credentials.txt Neo4j [email protected] userpassword "First Last"

Example output:

Creating [email protected]
{"data":{"createUserSignUp":{"email":"[email protected]","name":"First Last","picture":""}}}

Parameter description:

credentials.txt: The credentials file created from make_credential_file.sh
primaryOrganization: name of the organization to add the user under. Currently there is only valid organization: Neo4j
email: the email address of the user
password: the password for the user
name: the user’s name. This needs to be enclosed in quotes if there are spaces.
picture: Set to "".
host: the host the DS workbench API run on. Defaults to localhost if not entered.
graphql port: the port the DS workbench API runs on. Defaults to 80 if not entered.
https: if entered, indicates to change the protocol to https instead of http.

Resetting a User’s Password or Name

Using either method, you can also reset a user’s password or name. Ensure that the primaryOrganization and email are exactly the same as when the user was first created, and run the command with the new password and full name.

Logging In

Click this link http://localhost:80 to see the Cypher Workbench login page. Enter the username and password of any user you have set up. When successfully logged in, you will be taken to the Cypher Workbench main page.

3. Status and Shutting down

The workbench command has two more options:

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

./workbench_labs stop

This will shutdown the workbench_labs docker images.

4. Enabling HTTPS

This section describes how to turn on HTTPS for Cypher Workbench.

4.1 Certificate

The workbench_labs 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:

workbench.crt
workbench.key

These files are located under the workbench install directory in two locations:

./sw-config/sw-certificate
./sw-config/sw-ui-nginx

If you use your own certificate, you should replace the workbench.* versions in both directories.

You will also need to modify the sw-config/sw-ui-nginx-template/nginx.conf.template file and replace the workbench.crt and workbench.key entries with your own values.

        ssl_certificate     <your-cert>.crt;
        ssl_certificate_key <your-cert>.key;

Note: It’s optional to replace the files in sw-certificate folder, as they won’t be used unless you have a non-standard deployment, where you deploy the GraphQL server on a separate server from the React UI server.

4.2 Configuration

You need to make configuration changes in the envConfig.sh file to enable HTTPS. Change these configuration settings:

WORKBENCH_PROTOCOL=https
WORKBENCH_PORT_EXTERNAL=443
WORKBENCH_PORT_INTERNAL=443

Once you’ve made the changes, stop and start workbench_labs. You can now access the the Cypher Workbench UI at https://<your-hostname>:443.

Note: It is not necessary to modify the CERTIFICATE_* settings in the docker-compose.yml file or the GRAPHQL_PORT setting unless you have a non-standard deployment, where you deploy the GraphQL server on a separate server from the React UI server. In a normal deployment, the GraphQL server is only accessible via the internal docker-compose network and there is no need to make it https enabled.

5. Troubleshooting

This section describes how to deal with some error messages.

Table 1. Troubleshooting
Issue	Description	Fix
Upon login, you get the message 'No licensed tools'	A known bug where old credentials may have been cached, resulting in this error	Log out and log in again