Brain Annex : Full-Stack Data/Knowledge Management with Neo4j

Download / Install

PART 1 - Install the Neo4j Database

PART 2 - First-Time Deployment of the Brain Annex Full-Stack Technology (including web app)

PART 3 - Routine Deployments on a Server (UPDATES from changes in code base)

PART 1 – Install the Neo4j Database


You can install Neo4j on either Windows (10 or later; sorry, won't work on Win7), or on Linux (desktop or virtual machine on any cloud.)


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 Brain Annex 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 barely a year from Oct. 2022 to Sept. 2023, there have been a whopping 12 versions of 5.0 thru 5.11 ! 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 the 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.

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

Installing Neo4j

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

The following detailed instructions are ONLY for Debian-based Linux distributions (incl. Ubuntu); for other versions of Linux or for Windows, scroll down.

On Debian or Debian-based Linux (incl. Ubuntu), go to the server and issue:

wget -O - | sudo apt-key add -
(if wget isn't installed, it may be added with sudo apt-get install wget )

echo 'deb stable 4.4' | sudo tee /etc/apt/sources.list.d/neo4j.list
The 2nd command (the echo) should show:    deb 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 line:    cypher-shell - command line shell for neo4j

We now have 3 executable files; to see them listed, issue:
ls -alp /usr/bin/neo*
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.)
From that page, pick the most recent version of the 4.4.x 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.)
From that page, pick the most recent version of the 4.4.x branch, for Windows. Download the file, and follow the directions on the download page.
More info

Database Configuration

Make sure that the database is stopped (see the next section), if you need to edit the configuration file. (Of course, if you just installed it, it will 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): /etc/neo4j/neo4j.conf
For local Windows installations from a downloaded: NEO4J_HOME\conf\neo4j.conf , where NEO4J_HOME is the folder you chose for your installation

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

whereis neo4j

IMPORTANT: By default, the neo4j server only listens to the local machine.
If you need to make it accept remote connections (such as from the Neo4j browser interface), as typically done, you'll need to edit the config file, and UN-comment the line (i.e. remove the # in front of it):

Also, if using the APOC database procedures (needed by various modules), add the following line to the config file:*
You can use your favorite text editor. On Windows, for example, use Notepad; on Debian/Ubuntu Linux, for example:     sudo vim /etc/neo4j/neo4j.conf (if you SSH to the server with the awesome client MobaXterm, a handy graphic text editor for remote files is included.)

Then (on Linux) verify by showing the edited line with:
cat /etc/neo4j/neo4j.conf | grep dbms.default_listen_address
Also, don't forget the open up the needed ports! (See the next section.)

Neo4j ports, for remote access to server installations

By default, the Neo4j server runs on port 7474. Only connections from localhost are permitted, unless the config file is changed, as discussed in the previous section!
Other available ports are the following:

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 all of those ports (7474, 7473, 7687).
This 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)

Start the Neo4j database

If you ended up using the "Neo4j Desktop" program with a local database, it's very convenient to use that Neo4j Desktop program to stop/start the database. (But beware, as mentioned earlier, about being on the correct version of the Neo4j database!)

If you installed Neo4j on a Linux machine, it can typically be started with:

sudo neo4j start
To stop it (needed before making changes to the configurations files, or before stopping the Virtual Machine, if needed):
sudo neo4j stop
And to view the current status of the Neo4j database server:
sudo neo4j status
On Linux, you can check the log file (may not be present initially) with:
more /var/log/neo4j/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 ,
and then log inas follows:

Install the Neo4j APOC libraries (optional but highly recommended)

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 the Brain Annex web app for making a JSON dump of all the Neo4j data, or of just the schema, using Brain Annex's admin control panel.

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

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

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

Add the following line at the very end of the file:*

Then, at the Linux shell command prompt, issue:

tail neo4j.conf    (to verify the addition of the last line)

sudo neo4j stop    (the database needs to be stopped; will be restarted a few lines below)

cd /var/lib/neo4j/plugins

sudo wget    (note the 4.4, matching the version of the Neo4j database that BrainAnnex uses)

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

sudo chown -R neo4j:adm apoc-

sudo neo4j start
To verify that the installation worked, issue the following command in the neo4j browser:
RETURN apoc.version()
[No need to disconnect/reconnect the browser, if already running.] It should return the version number (

To install the APOC libraries on Windows, please see the official documentation

After installing APOC, don't forget to add the line*   to the Neo4j config file, as explained in another section.

PART 2 – First-Time Deployment of the Brain Annex Full-Stack Technology (including web app)

IMPORTANT: This section covers the initial setup. If you're doing a routine upgrade (i.e. to bring up-to-date from UPDATES from changes in code base), skip forward to Part 3.

Note: if you only want to use the lowest-level library, NeoAccess, then the full installation of the entire stack is NOT necessary; you can simply install the NeoAccess library from the standard python repository (use your IDE installer, or do a pip install neoaccess )

Verify you have Python 3.8+

Make sure that you have the right version of Python installed.

python3 --version (on Linux)

python --version (on the Windows command prompt or Power shell)

Clone the repository

Clone the repository to either your local machine or to your server.

To clone to a Windows machine, we recommend using the awesome program GitHub Desktop.

To clone to a Linux machine, you may use commands such as:

cd /home/ (change the location directory, if desired)

sudo mkdir brain_annex

sudo git clone --verbose --config http.sslVerify=false brain_annex

(Note: if git is not already installed, install it with:    sudo apt-get install git  )

ls -alF brain_annex (you should see several files, incl., and several subdirectories)

Folder setup

Create or designate:

1 - A folder for the media files. In the examples below, we use brain_annex_media, but it could be something else; make sure it matches what you will specify in the configuration file!

IMPORTANT: for now, the media folder MUST include a subfolder called "resized"

EXAMPLE (on Windows): create a folder named "brain_annex_media" on the "D" drive, and a subfolder named "resized" inside it.

EXAMPLE (on Linux):

cd /home/ (the parents of the desired location; change as needed)

sudo mkdir brain_annex_media (or whatever name one wants to use; make sure it matches the one in the config file)

sudo mkdir brain_annex_media/documents

sudo mkdir brain_annex_media/notes

sudo mkdir brain_annex_media/images

sudo mkdir brain_annex_media/images/resized (a subfolder of the previous one)

ls -alF brain_annex_media (you should see 3 subfolders)

ls -alF brain_annex_media/images (you should see the "resized" subfolder)

sudo chmod -R o+w brain_annex_media (a more restrictive permission might be used, if desired)

2 - A folder for the uploaded files.

EXAMPLE (on Windows): create a folder named "tmp" on the "D" drive

EXAMPLE (on Linux): do nothing! Will just use /tmp/

Brain Annex Configuration File

Go to the brain_annex folder that you created earlier.

Duplicate the file `config.defaults.ini` and rename the copy as `config.ini`
(on Linux, after navigating to that folder, do:   sudo cp config.defaults.ini config.ini )

Edit config.ini (for example, open with "notepad" on Windows, or sudo vim config.ini on Linux), to change, as needed, values for:

NEO4J_HOST the default `neo4j://localhost:7687` is for setups where the database is on the same machine as the Brain Annex web app; if it is on another machine, use values such as bolt://123.456.0.29:7687 or bolt://
NEO4J_USER `neo4j` is a typical default, unless you've changed it
NEO4J_PASSWORD Neo4j makes people change the password the first time they log in thru the Neo4j browser, as discussed in earlier section
PORT_NUMBER ok to keep the default 5000, unless you have a conflict.
Not applicable if you use gunicorn or other web server
Use LOCAL if starting the app with Flask (regardless of where the app runs);
use REMOTE if starting the app with gunicorn (regardless of where the app runs)
MEDIA_FOLDER where the user-submitted images, formatted text, documents, etc, are stored. IMPORTANT: names MUST end with a slash

EXAMPLE (on Windows): MEDIA_FOLDER = D:/media/
EXAMPLE (on Linux):   MEDIA_FOLDER = /home/brain_annex_media/
UPLOAD_FOLDER temporary location for uploads

EXAMPLE (on Windows): UPLOAD_FOLDER = D:/tmp/
EXAMPLE (on Linux):   UPLOAD_FOLDER = /tmp/
INTAKE_FOLDER optional, if "continuous data ingestion" is used
OUTTAKE_FOLDER optional, if "continuous data ingestion" is used
BRANDING optional, if a different branding is desired. Branding is shown on the Login page
(Note: an alternate way to set the database credentials is thru environment variables; for example, if you're running locally, using PyCharm, you can set the environment variables from Run > Edit Configurations...)

Install all dependencies in the virtual environment

All dependencies (such as Flask, pandas, etc) are specified in the file `requirements.txt`

If you're running Brain Annex locally, your IDE will probably prompt you as to whether you want to install the requirements (at least, PyCharm does.)

If you're installing Brain Annex on a Linux server, you need to manually create a virtual environment, using pip3 or your favorite command.

For example (IMPORTANT: make sure to change as needed /home/brain_annex in all instructions, if you used a different location):

$   ls /home/brain_annex (all project files should be there, incl., but NO venv folder; change the name if you used a different location)

$   sudo chmod go+w /home/brain_annex (because brain_annex is owned by the root; to avoid trouble during pip3 install later!)

$   python3 -m venv /home/brain_annex/venv (IMPORTANT: do NOT use sudo here, or permissions will get messed up! It creates a new virtual environment, but doesn't install any Packages)

$ sudo apt-get install python3-venv (only needed if the previous command failed! Then re-issue the previous command)

$   ls -alF /home/brain_annex/venv/bin (it shows the various "Activate" files, and the links to the python executables)

$   cd /home/brain_annex

$   source venv/bin/activate (to enter the context of the new virtual environment)

[Notice how the shell prompt is now prefixed with the name of your environment (venv, in our case). This is the indicator that venv is currently active, which means the python executable will only use this environment's packages and settings.]

(venv) $   pip3 install -r requirements.txt

ERRORS? no worries if you see "ERROR: Failed building wheel for neo4j"; it automatically recovers from it!
HOWEVER, in some cases, it says "Failed to build psutil" ; in that case, run:
sudo apt-get install gcc python3-dev
and then repeat the previous command.

(venv) $   pip3 list (to see all the installed packages; note that neo4j is there, even if it had previously said "Failed building wheel for neo4j")

(venv) $   deactivate (to leave the context of the new virtual environment)
In case of failures during the installation, try:
(venv) $   pip install --upgrade pip
(venv) $   pip install wheel

Starting the Brain Annex web app

The first order of business is to test the connection to the Neo4j Database from Python.

IMPORTANT: make sure that the Neo4j server is running! (see the earlier section on "Install the Neo4j Database")

For LOCAL installations:

Run ``, which starts Flask and the included Werkzeug web server.
If it doesn't find the database (e.g., if you forgot to start Neo4j),
it'll give you an error message such as:

In case of database-connection problems, you may also try to run the following diagnostic files:

For LINUX SERVER installations:
On a Linux server, you can do the following (OPTIONAL, but recommended) testing; but, first, make sure that the Neo4j server is running, as discussed in the section on Neo4j:
(you may skip the first 2 steps, if you never deactivated the virtual environment from earlier)
$   cd /home/brain_annex   [CHANGE the directory name, if used a different one]
$   source venv/bin/activate

(venv) $   ls venv/lib (make a note of your version of python; make sure it's 3.8+)
(venv) $   export PYTHONPATH=$PYTHONPATH:`pwd`/venv/lib/python3.8/site-packages [OR whichever version was shown in the previous step]

(venv) $   python3 (just for testing, if desired; make sure that the /home/brain_annex folder, or whichever home folder you used, appears in the sys.path)

(venv) $   cat config.ini (just for testing, if desired; verify the dbase credentials)

(venv) $   python3 tests_manual/ (just for testing, if desired; enter neo4j://localhost when prompted about the host; then it will prompt for the dbase password)
(venv) $   python3 tests_manual/ (just for testing, if desired; it uses the dbase credentials in the Brain Annex config file)

(Continue to one of the options below: either Flask's built-in server or to gunicorn...)

(OPTION 1 - using Flask's built-in server Werkzeug)
Make sure that you have DEPLOYMENT = LOCAL in your Brain Annex config.ini file
You may double-check with: cat /home/brain_annex/config.ini | grep DEPLOYMENT
Make sure that port 5000, or whichever port is used below, is open; check the firewall rules on your VM

(venv) $   export
(venv) $   flask run --host= --port 5000 &> flask_log.txt & (to redirect both stdout and stderr; change port if desired - but be aware that 80 won't work)
(venv) $   ps -e | grep flask (to double-check there's a 'flask' process running in the background)
(venv) $   deactivate

$   cat flask_log.txt (optional, to check the log)

If running remotely, set your browser to   http://YOUR_SERVER_IP_ADDRESS:5000
If running locally, set your browser to   http://localhost:5000

Problems? Try the following diagnostics (change the port # if needed; the port should be shown as being listened to):

$   sudo lsof -i:5000 (to investigate the network)
$   netstat -an | grep 5000 (to further investigate the network)

They both should show "LISTEN"

(note: replace 5000 with whatever port number you used in your configuration.)

(OPTION 2 - using Gunicorn; common initial steps for all Gunicorn variations below)
Make sure that you have DEPLOYMENT = REMOTE in your Brain Annex config.ini file
You may double-check with: cat /home/brain_annex/config.ini | grep DEPLOYMENT

deactivate (if needed, from previously being in a venv)
$   sudo su - (To elevate permissions to the root account)
root #   cd /home/brain_annex (Or whichever home location is being used)
root #   source venv/bin/activate
(venv) root #   ls venv/lib (make a note of the version of python; make sure it's 3.8+)
(venv) root #   export PYTHONPATH=$PYTHONPATH:`pwd`/venv/lib/python3.8/site-packages (OR whichever version was shown in the previous step)

If you're following Option 2 (i.e. Gunicorn), finish up with either 2a or 2b:

(OPTION 2a - using Gunicorn with HTTP, on port 80)
Make sure to follow the common initial steps of Option 2, above.
Make sure that port 80 is open; check the firewall rules on your VM

(venv) root #   gunicorn -w 1 -b main:app &

OR (recommended)
(venv) root #   gunicorn --worker-class gthread --threads 3 -w 1 -b main:app > brainannex_log.txt &
to use multiple threads; it's recommended to replace the 3 with: (2 x $num_cores) + 1 . To find the number of cores, you can use lscpu

Set your web browser to http://YOUR_SERVER_IP_ADDRESS

(OPTION 2b - using Gunicorn with HTTPS, on port 443)
Make sure to follow the common initial steps of Option 2, above.
Make sure that port 443 is open; check the firewall rules on your VM
Get a digital certificate (we recommend the free and convenient Let's Encrypt)

(venv) root #   gunicorn --certfile=/etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem --keyfile=/etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem --error-logfile gunicorn_log.txt -b main:app   > brainannex_log.txt &
(Replace YOUR_DOMAIN with whatever you're actually using, such as

* If you run   ps -e | grep gunicorn   , you should see 2 gunicorn processes (running in the background)
* Set your web browser to https://YOUR_DOMAIN
* App log can be found in: brainannex_log.txt (contents get buffered; so, they may not be immediately visible)
* For Gunicorn log (incl. errors): gunicorn_log.txt

  1. is the port number that you're using open on your server's firewall?
  2. 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
  3. did you start the Neo4j server?
  4. (if this is an upgrade) did you check the Change Log for any special instructions?

Using the Brain Annex web app

You should see a simple web pages with a message and a few links.

Click on "Test page", which doesn't require login. Then use the back button on your browser; but, in order to log into the app, first, you'll need to create login accounts (see the next section.)

Create user login account

For the time being, user login accounts need to be manually created from the Neo4j browser interface (see earlier section.)

Use Cypher queries such as:

CREATE (n:`User Login` {user_id: 1, username: "the_desired_username", password: "the_desired_password"})
Increase the user_id for any additional user. For example, you might want to create a user named admin (but can use any name.)

Test the login functionality

Go the the login page from the earlier section.

If running remotely, you can also use the direct URL : http://YOUR_SERVER_IP_ADDRESS:5000
If running locally, you can also use the direct URL : http://localhost:5000
(note: replace 5000 with whatever port number you used in your configuration.)

Log in using any of the accounts that you created in the previous section Log into Brain Annex

Import the Schema (Optional but Recommended)

Brain Annex is schema-based, and it's critical that you import the standard schema, IF you want to use the built-in functionality as a multimedia content-management system.
(Note: in the earlier versions of Brain Annex, being a multimedia content-management system was its core functionality; however, in its latest version, that capability is regarded as just one possible use case.)

For general testing, to explore the capabilities of the system, we provide a sample file named SAMPLE_SCHEMA_TO_IMPORT.json, which contains everything that is regarded as fundamental in a typical Brain Annex installation, as well as various examples of user-added schema – again, if you want to include the built-in functionality of a multimedia content-management system.

Click on the above links to display that JSON file. Then click on the "Download raw file" button (near top/right), to save the file to your local device.

Note: in addition to the Schema,the above file contains the ROOT node for the Categories, typically referred to as the "HOME" Category (which is regarded as a data point, not part of the Schema.)

Now that you have your desired .json file on your local device, go to the "Admin" page of the Brain Annex UI (the layout of this page may be different):

Brain Annex Admin page

Use the "IMPORT from JSON" box on that "Admin" page.

At the end of the import operation, you should see a message about having imported a certain number of nodes and relationships.

Note - the imported schema may be seen by going to the Neo4j browser interface, and issuing the Cypher command:

RETURN c1, c2, p, n

Now you can start using the multimedia content-management capability of Brain Annex, which is in late Beta as of Fall 2023. Again, this is JUST ONE use case of the Brain Annex technology stack.

PART 3 – Routine Deployments on a Server (UPDATES from changes in code base)

Use PuTTY or other client (we recommend the free MobaXterm) to SSH to the server.

* First, stop Gunicorn (or Flask's built-in server, whichever you're using)

if using Gunicorn:

ps -e | grep gunicorn
sudo pkill -f gunicorn (To kill all gunicorn processes at once; it takes a bit of time)
OR, if using Flask's built-in server (Werkzeug):
ps -e | grep flask
kill 12345 (Replace the number with the process ID returned by the previous command!)

* Update the code base from the latest release:

sudo su -To elevate permissions to the root account
cd /home/brain_annexOr whatever location you used for your install
git reset --hardTo permanently discard all local changes to all files; typically not needed, but doesn't hurt
git pull --ff-only fetches the remote repo, and merges it with the current one; the "--ff-only" means only update to the new history if there is no divergent local history

NOTE: your personalized "config.ini" file on the servers won't be affected, because not part of the repository
cat VERSION_NUMBER.txtOptional, to double-check the version number of your upgrade
exitTo return to the normal login account

* IF NEEDED (not always): If the new release involved changes in the required libraries in requirements.txt, then one needs to perform installs/uninstalls in venv as needed (safe to do even if not needed!):

$   cd /home/brain_annex Or whatever location you used
$   source venv/bin/activate This will enter the virtual environment; notice the changed prompt in the next line
(venv) $   pip3 install -r requirements.txt It should print out "Successfully uninstalled XYZ" and "Successfully installed ABC"

To double-check:
(venv) $   pip3 list Optional: to see all the installed packages
(venv) $   pip3 show SOME_PACKAGE_NAME Optional: to see more info about that particular package
(venv) $   deactivate To exit the virtual environment

* IF NEEDED (usually not): if you have existing data and/or media, follow the MIGRATION PROTOCOL, if any, for the current upgrade.

Check any special instructions in the Change Log of Version 5, for the current release, as well as any release between the latest one and the one you're upgrading from.

Rarely needed, but there have been cases of needed file changes and/or Cypher queries to manually run (using the Neo4j browser interface.)

* Finally, proceed as shown in the earlier section Starting Brain Annex

For additional instructions, see the README file.