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 libraries, then the full installation of the entire stack is
NOT necessary; you can simply install the NeoAccess library (the lowest-level library) or
the full BrainAnnex library, from the standard
python repository (use your IDE installer, or do a pip install neoaccess or a pip install brainannex).
If you pip install the full BrainAnnex library, then the NeoAccess library will be automatically installed as well.
THE INSTRUCTIONS ON THIS PAGE ARE PURELY FOR THE BrainAnnex WEB APP INSTALL, if desired.
Make sure that you have the right version of Python installed. Earlier versions will NOT work!
python3 --version (on Linux)python --version (on the Windows command prompt or Power shell)
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).
This is in addition to any ports that had to be opened for Neo4j (see separate page.)
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_annexsudo git clone --verbose --config http.sslVerify=false https://github.com/BrainAnnex/brain-annex.git brain_annexsudo apt-get install git )ls -alF brain_annex
(you should see several files, incl. main.py, and several subdirectories)
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/documentssudo mkdir brain_annex_media/notessudo mkdir brain_annex_media/imagessudo 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)
/tmp/
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://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 |
| PORT_NUMBER |
ok to keep the default 5000, unless you have a conflict. Not applicable if you use gunicorn or other web server |
| DEPLOYMENT |
Either LOCAL or REMOTE 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 |
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. 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)
(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)
(venv) $ pip install --upgrade pip
(venv) $ pip install wheel
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:
neo4j://localhost when prompted about the host; then it will prompt for the dbase password.
If all goes well, it will show some diagnostic info)
| (venv) $ cd /home/brain_annex | CHANGE the directory name, if used a different one |
| (venv) $ cat config.ini | grep DEPLOYMENT |
to make sure that you have DEPLOYMENT = LOCAL in your Brain Annex config.ini file |
| (venv) $ export FLASK_APP=main.py | to inform Flask on how to start |
| (venv) $ flask run --host=0.0.0.0 --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 | leave the venv |
| $ cat flask_log.txt | optional, to check the log |
http://YOUR_SERVER_IP_ADDRESS:5000http://localhost:5000$ sudo lsof -i:5000 (to investigate the network)$ netstat -an | grep 5000 (to further investigate the network)DEPLOYMENT = REMOTE in your Brain Annex config.ini filecat /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; notice the changed prompt in the next line |
| root # cd /home/brain_annex | or whichever home location is being used |
| root # source venv/bin/activate | this will enter the virtual environment; notice the changed prompt in the next line |
| (venv) root # ls venv/lib | make a note of the version of python; MAKE SURE it's 3.9+ |
| (venv) root # export PYTHONPATH=$PYTHONPATH:`pwd`/venv/lib/python3.9/site-packages | OR whichever version was shown in the previous step |
gunicorn -w 1 -b 0.0.0.0:80 main:app &gunicorn --worker-class gthread --threads 3 -w 1 -b 0.0.0.0:80 main:app > brainannex_log.txt &http://YOUR_SERVER_IP_ADDRESS
gunicorn --certfile=/etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem --keyfile=/etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem
--error-logfile gunicorn_log.txt -b 0.0.0.0:443 main:app > brainannex_log.txt & gunicorn -w 5 --certfile=/etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem --keyfile=/etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem
--error-logfile gunicorn_log.txt -b 0.0.0.0:443 main:app > brainannex_log.txt & lscpu)
ps -e | grep gunicorn , you should see (1 + number of workers) gunicorn processes (running in the background.) For example, in the case
of the "minimalist" gunicorn invocation, there should be 2 processes.https://YOUR_DOMAINbrainannex_log.txt (contents get buffered; so, they may not be immediately visible)gunicorn_log.txt
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
(More info).
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.)
If this is your initial install of the web app, you must create a first user login account (the
first account creation will also initialize the database.)
You may also re-run the same script, to create additional login accounts:
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
It's recommended to set up the following indexes, if you haven't yet during earlier installs. You may use the Neo4j browser interface, and issue the Cypher commands:
CREATE CONSTRAINT unique_schema_uri ON (n:SCHEMA) ASSERT n.uri IS UNIQUECREATE CONSTRAINT unique_data_uri ON (n:BA) ASSERT n.uri IS UNIQUECREATE CONSTRAINT unique_bookmarks ON (n:`Site Link`) ASSERT n.url IS UNIQUESHOW CONSTRAINTS
ALL DONE! Now you can start using the multimedia content-management capability of Brain Annex. Again, this is JUST ONE use case of the Brain Annex technology stack!
If, at a later date, you upgrade the software, refer to the instructions in "Part 3", below.
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 | Show all gunicorn processes |
| sudo pkill -f gunicorn | To kill all gunicorn processes at once; it takes a bit of time |
| ps -e | grep flask | Show all flask processes |
| 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_annex | Or whatever location you used for your install |
| git reset --hard | To permanently discard all local changes to all files; typically not needed, but doesn't hurt |
| git pull --ff-only https://github.com/BrainAnnex/brain-annex.git | It 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 it's NOT part of the repository |
| cat brainannex/__init__.py | grep __version__ | Optional, to double-check the version number of your upgrade |
| exit | To return to the normal login account |
* IF NEEDED (not always): If this upgrade involves changes in the required libraries in requirements.txt
(see changelog), 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" |
| (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.
* Finally, proceed as shown in the earlier section Starting Brain Annex
For additional instructions, see the README file.