Return to BrainAnnex Setup


Download / Install Neo4j


Requirements

Choosing the right version

Neo4j ports

Install Java

Install Neo4j

Install APOC libraries

Neo4j Database Configuration

Start/Stop the database

Test Neo4j access

Containerized Neo4j


Requirements

You can install Neo4j on either Windows (10 or later; sorry, won't work on Win7), or on Linux. Either on local computers or on a virtual machine on ANY cloud.

We test on Debian/Ubuntu and on Windows 11.


CHOOSING THE RIGHT SOURCE/VERSION of Neo4j

We do all our testing – and only support – Neo4j Community version 4.4. (Version 4.3 will also probably work, but we no longer support it. Note that use of the Enterprise version is NOT required for Brain Annex – the Community version will do just fine!)

We feel that Neo4j version 5 is too recent, and don't support it (yet.) Version 4.4 of the Neo4j database will continue to be supported by the Neo4j company thru June 2025 – and that's the only version that the Brain Annex project will support in the near future.

Some considerations: version 4.4 is the very mature end-of-line for major version 4 of Neo4j (perhaps "4" is their lucky number?!?) If you look at the Neo4j release history, you can see that version 4 has been polished in the course of almost 3 full years (2020, 2021, 2022), from its Jan. 2020 release thru the appearance of version 5.0 at the very end of 2022.
During these 3 years, there have been only 5 minor versions: 4.0 thru 4.4; by contrast, in the span of two years from Oct. 2022 to Oct. 2024, there have been a whopping 25 versions of 5.0 thru 5.25 ! This might speak of major version 5 as still unstable/unsettled... Yet another reason to wait!

You may install Neo4j on your local computer, or on a virtual machine on any Cloud (we use the Google cloud, as well as the inexpensive Oracle cloud); or you may use a Neo4j hosting service such as Neo4j Aura (PROVIDED that you can get Neo4j versions 4.4).

Note: for installations on a local machine, the "Neo4j Desktop" program is a convenient alternative – BUT be aware that it ties you to a trial copy of the Enterprise version of Neo4j, and it tries to push you towards products such as "Bloom", which also require the Enterprise version of Neo4j! Also, it's unclear if it supports versions 4.x of the database. At present, we don't support the "Neo4j Desktop" program; while it provides some convenience, it's largely a marketing tool to corral you towards the paid version of the database...



Neo4j ports to open, for remote access to server

By default, only connections from localhost are permitted, unless the config file is changed, as discussed in the section Neo4j Database Configuration.

Default ports used:

HTTPS: 7473
HTTP: 7474
Bolt Protocol: 7687


If you're installing Neo4j on a server, and want to enable remote access to the database, you must open some or all of those ports (7474, 7473, 7687), as needed.

Port opening will be needed if the database and the app are on different machines, or if you want to access the database over the internet from the Neo4j browser or other front ends.

Note: if you use the Brain Annex web app, depending on how you install it, you'll also need access to ports 5000 (for Flask/Werkzeug) or 80 (for HTTP) or 443 (for HTTPS).

If installing on a virtual machine on a cloud, consult your cloud provider for instructions on how to open the needed ports - typically thru a control panel.
In some cases, Linux commands may also have to be issued. In particular, if you're on Ubuntu, you may need extra steps to open ports; for example, to open port 80 issue: sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT (More info).
Special instructions for Ubuntu on the Oracle cloud


Install Java, as needed

The Neo4j database is internally written in the Java programming language – so, Java must be available on the system.

If doing your own installation, the Java SE Development Kit 11 is needed. (Some pre-made VM images already includes Java, but make sure that it's the right version.)

You can check if Java 11 (used by versions 4.x of the Neo4j database) is already installed by issuing:

java -version
on your Linux shell or Windows PowerShell or Command Prompt window.


On Ubuntu, Debian and some other Linux versions, Java 11 may be installed, if needed, with:

sudo apt install openjdk-11-jre-headless

On Windows, use this link from Oracle (then click on the "Windows" tab, and look for the .exe Windows x64 Installer.)
Oracle's website doesn't appear to work correctly from Firefox, but it's fine from Chrome. You'll have to register for an account from Oracle; annoying but free.
After you download the .exe file, double-check on it, to install Java.
If you have any PowerShell windows open, close them to register the change.


Installing Neo4j - PART 1 : the Database

As stated earlier, Brain Annex is for the time being staying with version 4 of the Neo4j database, and more specifically 4.4

Note: upon completing a new install, the default database login will be username 'neo4j' and the password also 'neo4j'



For Debian-based Linux distributions, incl. Ubuntu  (scroll down for other versions of Linux or for Windows):

On Debian or Debian-based Linux (incl. Ubuntu), go to the server and issue:
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo apt-key add -
(if wget isn't installed, it may be added with sudo apt-get install wget )

echo 'deb https://debian.neo4j.com stable 4.4' | sudo tee /etc/apt/sources.list.d/neo4j.list
The 2nd command (the echo) should show:    deb https://debian.neo4j.com stable 4.4

Then issue:
sudo apt-get update
sudo apt-get install neo4j
OPTIONAL, just for your information – you can verify which Neo4j versions are available by running:
apt list -a neo4j
In Ubuntu server installations you will also need to make sure that the `universe` repository is enabled.
sudo add-apt-repository universe
OPTIONAL, just for your information - to show all the installed neo4j components:
apt-cache search neo4j
The output should include the lines:
cypher-shell - command line shell for neo4j
and
neo4j - graph database server

We now have 3 executable files; to see them listed, issue:
ls -alp /usr/bin/neo4j*
You should see neo4j, neo4j-admin and neo4j-import

To find out exactly where neo4j got installed, run:
whereis neo4j
Items of interest:



For Other Linux distributions:

Use Neo4j download LINK.   IMPORTANT: make sure to get version 4.4.x (We feel that Neo4j version 5 is too recent, and don't support it yet; see box at the page's top for more info.)
From that page, scroll down to the section on "Graph Database Self-Managed", and pick the most recent version of the 4.4.x *COMMUNITY* (unless you specifically need Enterprise) branch, for your version of Linux. Download the file, and follow the directions on the download page.


For Windows:

Use Neo4j download LINK.   IMPORTANT: make sure to get version 4.4.x (We feel that Neo4j version 5 is too recent, and don't support it yet; see box at the page's top for more info.)
From that page, scroll down to the section on "Graph Database Self-Managed", and pick the most recent version of the 4.4.x *COMMUNITY* (unless you specifically need Enterprise) branch, for Windows. Download the file.
If you want to verify the checksum on the downloaded zip file (i.e. its integrity), we recommend the free Windows tool Bitser (beware of potentially misleading ads on that download page.)

Find the zip file you just downloaded and right-click, extract all.

Move all the extracted files to a permanent folder on your machine, for example D:\neo4 . That top-level directory for the Meo4j installation is referred to as NEO4J_HOME. Under that folder, you should see a "README.txt" file (you can double-check the version number inside of it), plus several other files and subfolders.

More info



Installing Neo4j - PART 2 : the Neo4j APOC libraries (optional but highly recommended, and required by some BrainAnnex modules)

The Neo4j "APOC" libraries add a good deal of extra functionality to the database: they provide a large set of functions that can be incorporated into Cypher queries. Those libraries are created and maintained by the Neo4j company itself, but somehow they're not part of the standard installation.

From the official documentation:
"[APOC procedures] are custom implementations of certain functionality, that can’t be (easily) expressed in Cypher itself.
They are implemented in Java and can be easily deployed into your Neo4j instance, and then be called from Cypher directly."

Currently, the APOC library is needed by several Brain Annex modules. We highly recommend that you install it, though you could do without if you're just using the database by itself thru the Neo4j browser.


Make sure that the database is stopped (see the section Start/Stop the database). If you just installed it, it will already be in a stopped state.

Locate the most recent version of the 4.4 series of APOC libraries (assuming that you're using version 4.4 of the Neo4j database) from this GitHub Releases page. Make a note of that version number; for example, as of early Jan. 2025, the most current version of the 4.4 series is 4.4.0.34

IMPORTANT: after you finish APOC's installation, make sure to change the Neo4j config file, as detailed in the next section!


To install the APOC libraries on Linux (we tested on Ubuntu and Debian):

cd /var/lib/neo4j/plugins

sudo wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/4.4.0.34/apoc-4.4.0.34-all.jar
(note the 4.4, matching the version of the Neo4j database that you're installing. The "34" minor version, in two places, may be replaced with the latest available version of the 4.4 series, as noted above)

If wget isn't available (such as on Debian Linux), one can install it with: sudo apt-get install wget

In that "plugins" folder, you should now see the ".jar" (Java) file that you just fetched.

Change that file's ownership (permissions) by issuing the command:

sudo chown -R neo4j:adm apoc-4.4.0.34-all.jar


To install the APOC libraries on Windows (we tested on Win 11), right-click on an empty space in the window where you installed Neo4j (in our examples below, D:\neo4j), and select "Open in Terminal". Then, in the PowerShell that comes up, run:

cd plugins To navigate to the NEO4J PLUGIN FOLDER! Example: D:\neo4j\plugins

Invoke-WebRequest -Uri "https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/4.4.0.34/apoc-4.4.0.34-all.jar" -OutFile "apoc-4.4.0.34-all.jar"
(note the 4.4, matching the version of the Neo4j database that you're installing. The "34" minor version, in three places, may be replaced with the latest available version of the 4.4 series, as noted above)

In that "plugins" folder, you should now see the ".jar" (Java) file that you just fetched.



IMPORTANT: make sure to do the changes in the Neo4j config file, as detailed in the next section, or you'll never see the APOC install!



Neo4j Database Configuration

Make sure that the database is stopped (see the section Start/Stop the database), if you need to edit the configuration file. If you just installed the database, it will already be in a stopped state.


Locate the Neo4j configuration file.

On Linux installations from the repository (we tested on Debian and Debian-derived versions, such as Ubuntu), the configuration file will be: /etc/neo4j/neo4j.conf

If you're having problems finding the Neo4j configuration file, you can get a list of applicable directories with:

whereis neo4j


For Windows installations from a downloaded: NEO4J_HOME\conf\neo4j.conf , where NEO4J_HOME is the folder you chose for your installation



IMPORTANT: By default, the neo4j server only listens to the local machine, and does NOT recognize the APOC libraries, even if installed as directed above!

If you need to make Neo4j accept remote connections (such as from the Neo4j browser interface), as typically done on a server installation, you'll need to edit the config file.
Similarly, if you want to make the APOC libraries available (highly recommended), you'll need to edit the config file.


To edit the config file on Windows, use your favorite text editor, such as notepad.
If you SSH to the server with the awesome client MobaXterm, a handy graphic text editor for remote files is included, though it might run into writing-permission issues.
Or, in the Linux shell:

cd /etc/neo4j    (or use the location of your Neo4j config file; see earlier section)

sudo vim neo4j.conf    (or use your favorite Linux editor)


Now that you're editing the Neo4j configuration file...

1) If you want to make Neo4j accept remote connections, UN-comment the line (i.e. remove the # in front of it):
dbms.default_listen_address=0.0.0.0
2) If you want to use the APOC libraries (assuming you installed them, as discussed in the previous section), add the following line anywhere in the config file; for example, at the very end:
dbms.security.procedures.unrestricted=apoc.*


After saving and closing the configuration file, it's good to verify the changes.
On Linux, you may verify the line you uncommented (for remote access) and the added (for APOC) with, respectively:
cat /etc/neo4j/neo4j.conf | grep dbms.default_listen_address

cat /etc/neo4j/neo4j.conf | grep dbms.security.procedures.unrestricted=apoc.*



Start/Stop the Neo4j database

Upon the initial install, the database will be in a stopped state.

On a side note, if you ended up using the "Neo4j Desktop" program (NOT covered in this guide) with a local database, it's quite convenient to use that program to stop/start the database. (But beware, as mentioned earlier, about being on the correct version of the Neo4j database!)

Otherwise, do the following:


Linux
TO START neo4j:
sudo neo4j start
To stop it (needed before making changes to the configurations file, or before stopping the Virtual Machine):
sudo neo4j stop
And to view the current status of the Neo4j database server:
sudo neo4j status
PROBLEMS STARTING THE DATABASE? You can check the log file (may not be present initially) with:
more /var/log/neo4j/neo4j.log
(the location of the log file may vary in different operating systems, as detailed earlier)


Windows
On Windows, Neo4j can be run as a console application or as a Windows service (to leave it running.)

ONE-TIME SETUP.

In the PowerShell (on Win10, it needs to be started in admin mode), issue the command:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
That's needed to over-ride the default block against running scripts.



OPTION 1 * Running Neo4j as a console app (change the sample highlighted part to your own chosen location!)

To start Neo4j, enter in the PowerShell:
D:\neo4j\bin\neo4j console
When it's ready, the console shows a message about visiting http://localhost:7474 in a web browser. (See Test Neo4j access)


To stop Neo4j, Use CONTROL-C on the PowerShell window where you started it.



OPTION 2 * To install Neo4j as an always-running Windows service (change the sample highlighted part to your own chosen location!):
D:\neo4j\bin\neo4j install-service
If you enter services at the Windows search, you can start the "Services" app, and you'll find a Windows service named "Neo4j Graph Database - neo4j". You can right-click on it to start/stop it. Or, MORE SIMPLY, just use the PowerShell:
To start Neo4j:
D:\neo4j\bin\neo4j start
Once started, it will be automatically re-started if the computer gets rebooted.

To stop it (for example, to make changes to the configurations file):
D:\neo4j\bin\neo4j stop
And to view the current status of the Neo4j database server:
D:\neo4j\bin\neo4j status
You can check the log file (may not be present initially) with:
cat D:\neo4j\logs\neo4j.log



Test Neo4j access thru its Browser Interface

Did the installation go well? You can test it by means of the "Neo4j Browser Interface" (a web app that comes with Neo4j), by opening a browser tab and going to either
localhost:7474   or   http://YOUR_IP_ADDDRESS:7474

If the page doesn't load up, and if not on localhost, did you remember to open up the needed ports (see section on Neo4j ports) and did you change the config file? (see section Neo4j Database Configuration)


Log in as follows:

Note that two separate port numbers are involved: 7474 (for the web app that comes with Neo4j), and 7687 (to transfer data from/to the database.)

Common mistake: forgetting to change the "Connect URL" pulldown menu to "bolt://"

If it's your first login, you'll be asked to change your password.

If you also installed the APOC library earlier (optional, but highly recommended), to verify that its installation worked, issue the following command inside the neo4j browser app:
RETURN apoc.version()
It should return the version number (such as 4.4.0.34)


Advanced topics: Containerized Neo4j

We have used, but don't currently support, Docker to provide a containerized version of the Neo4j database.

In a not-to-distant future, we expect to support this modality as a handy way to have multiple instances of Neo4j running on a virtual machine or desktop, to provide independent databases, or master/slave configurations, or perhaps even some sharding support.



Continue to BrainAnnex Setup