Setup - Brain Annex

Install the Neo4j Database ♦ First-Time App Deployment ♦ Routine Upgrades ♦ Start Web App

First-Time Deployment of the Brain Annex 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 and/or database), go to Routine Upgrades.

THE INSTRUCTIONS IN THIS PAGE ARE PURELY FOR THE BrainAnnex WEB APP INSTALL, if the web app is what you need.

If you only want to use the BrainAnnex python LIBRARY, then the full installation of the entire software stack is NOT necessary; you can simply pip install either brainannex-neo4jv4 or brainannex-neo4jv5, depending on your version of the database.

Verify you have Python 3.10+

Make sure that you have the right version of Python installed. Earlier versions will NOT work! We develop and test on 3.10 and 3.11

python3 --version (on Linux)

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

Needed ports, for the web servers

If you're installing Neo4j on a server, you'll need access to ports 5000 (for Flask/Werkzeug) or 80 (for HTTP) or 443 (for HTTPS) or 8000 (if you use Caddy and you want to bypass it for testing.)

This is in addition to any ports that had to be opened for Neo4j (see separate page.)

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.
Alternatively, you can download the latest zipped release from GitHub, and unzip it to some folder on your machine.

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 https://github.com/BrainAnnex/brain-annex.git 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. main.py, and several subdirectories)

If you're using version 5 of Neo4j, make a few changes to the cloned repository

IMPORTANT! What version of Neo4j are you using?

The files in the repository are configured for version 4.4 of the Neo4j database.

If you want to use version 5 of Neo4j (which we recently started supporting) with the BrainAnnex web app, make sure to apply the following changes to the files from the repo:

In the file brainannex/__init.py__ , comment out the line that mentions intergraph_neo4j_4, and uncomment the line that mentions intergraph_neo4j_5
In the files requirements.txt, comment out the line that mentions version 4 of Neo4j, and uncomment the line that mentions version 5

Folder Setup (for media and uploads)

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!

EXAMPLE: create a folder named "brain_annex_media" on the "D" drive.

EXAMPLE:

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 chmod -R o+w brain_annex_media (a more restrictive permission might be used, if desired)

2 - A folder for the uploaded files.

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

EXAMPLE: do nothing! Will just use the standard /tmp/ directory

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 )

The file config.ini will be your PRIVATE file that will NOT be affected by any future pull from the repository (it is on the list of excluded files in the Git configuration file .gitignore)

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://your_domain.com:7687`
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
DEPLOYMENT	Use either FLASK (typically for local dev runs) or EXTERNAL (typically for production on a remote server) : - use FLASK if employing the built-in WSGI HTTP server that comes with Flask ("Werkzeug"). NOT meant for production! In that case the Flask web app will get started directly. - use EXTERNAL if the WSGI HTTP server is external to the Flask application (e.g. gunicorn, waitress, hypercorn, etc) In that case the Flask web app will get started by gunicorn or other external software. Note: this is totally UN-related to running the Brain Annex web app locally or on a remote server; it's often the case that one uses Flask built-in capabilities in a local development environment.
PORT_NUMBER	ONLY applicable if you chose the DEPLOYMENT = FLASK option, above (i.e. not relevant if you use "gunicorn" or other WSGI HTTP server) Ok to keep the default 5000, unless you have a conflict.
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, and in the fix top bar of every 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 Library Dependencies in your Virtual Environment

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

STOP: if you're using Neo4j version 5, did you make the needed changes to requirements.txt and another file, as spelled out in a previous section??

LOCAL INSTALL with an IDE: Your IDE will probably prompt you as to whether you want to install the requirements (at least, PyCharm does.)

No IDE: If you're installing Brain Annex on a server, or doing a local install without an IDE, you need to manually create a virtual environment, using pip3 or your favorite command.

For example, on Linux (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. README.md, 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

Create Database Schema (optional but highly recommended)

Since this is your initial install of the web app, there are a few dozen nodes and relationships that will have to be added to the database if you want to use the various core modules and plugins for the "multimedia content management" part of the BrainAnnex web app; if your only intended use are the control panels of the web app, then it's NOT needed.
More info on Schema Layer

(you may skip these 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) $ python3 initialize_schema.py

Use .\venv\Scripts\Activate.ps1 (assuming you are already in the right folder, as stated above; there should be a "venv" subfolder.)
If you get a policy error, first run:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
Then run: python initialize_schema.py

Starting the Brain Annex App

All done with the first-time setup! Now you're ready to Start Web App

Install the Neo4j Database ♦ First-Time App Deployment ♦ Routine Upgrades ♦ Start Web App