Neo4J 4.0 and OpenCypher on FreeBSD

Adding graph databases to the FreeBSD platform.

Posted on May 25, 2020

If you are like us, you love getting your hands on some new technology; and graph databases like Neo4J are no different. However, we had a bit of issues with getting it to work on FreeBSD. This is how we solved it.

The goal:

Install Neo4J 4.0 and OpenCypher on a machine running FreeBSD 12.

The problem:

Neo4J does not have native support for FreeBSD and the available package is very outdated and (seemingly) unmaintained.

The solution:

Here are the instructions to install Neo4J on FreeBSD:

  1. Get the tarball of the Neo4J edition you wish to install (community edition in our case). We used the Linux/Mac version (at the time of writing, it was the most recent 4.0.4).
  2. Download using wget, or download locally and transfer using s/ftp.
  3. Extract in the directory you want to save all the files in. (We did this in /usr/local/etc/).
  4. Head on over to /usr/bin and system link the Neo4J commands found in {extracted_directory_of_neo4j}/bin/neo4j to neo4j.
    • We did this for neo4j and neo4j-admin.
    • neo4j: ln -s {extracted_directory_of_neo4j}/bin/neo4j neo4j
    • neo4j-admin: ln -s {extracted_directory_of_neo4j}/bin/neo4j-admin neo4j-admin
  5. Run neo4j console to ensure the installation and command linking was successful.
  6. You will notice that if you just try to use neo4j start you will likely run into an error. You must sent an environment variable for NEO4J_HOME. This is accomplished by running setenv NEO4J_HOME {extracted_directory_of_neo4j}
  7. Ensure that neo4j start works. The Neo4J server should now startup and let you know that it's working! If you want access to Neo4J's OpenCypher, continue below.

Here are the instruction to install OpenCypher on FreeBSD:

  1. Clone the forked OpenCypher repo from our Github into a separate directory.
  2. Ensure you have gmake installed (If not, pkg install gmake).
  3. Run gmake build within the directory you cloned.
  4. Navigate to {location_you_extracted_neo4j_in} and create the directories {extracted_directory_of_neo4j}/libexec/tools.
    • From {location_you_extracted_neo4j_in}: mkdir libexec
    • Change into that directory and run: mkdir tools
  5. Move the contents of {OpenCyper_git_clone_folder}/cypher-shell/build/install/* to {extracted_directory_of_neo4j}/libexec/tools.
    • mv {OpenCyper_git_clone_folder}/cypher-shell/build/install/* {extracted_directory_of_neo4j}/libexec/tools/
  6. Finally, head back to /usr/bin and system link the CyperShell command to the script in your {extracted_directory_of_neo4j}/libexec/tools/ folder:
    • ln -s {extracted_directory_of_neo4j}/libexec/tools/cyper-shell cypher-shell
  7. Attempt to connect to your database using cyper-shell. All should be working now.

Why this works:

The installation of neo4j was a lot of system configuring and not much problem solving. We just needed to set the NEO4J_HOME environment variable to the proper directory, and ensure we were not using the pkg. The rest of the system linking were just creature comforts, really.

The installation of CypherShell required a small bit of code that was added into the cypher-shell script. The changes can be seen on Github, but here is the code that was added:

if [[ "$OSTYPE" == "FreeBSD"* ]]; then
APP_HOME="${NEO4J_HOME}/libexec/tools"
JARPATH="$(find "${APP_HOME}" -name "cypher-shell.jar" )"
fi

What we have done here is we changed the location of the jar (JARPATH) to follow our {NEO4J_HOME}/libexec/tools directory thanks to our environment variable. This only occurs when the OSTYPE is FreeBSD.

Helpful links: