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

Starting the Brain Annex web app

STOP! Have you done a first-time deployment or an upgrade of the Brain Annex web app? If so, you are in the right place, ready to start the web app.

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

For Windows, here we'll only cover installations employing the built-in WSGI HTTP server that comes with Flask ("Werkzeug"). Typically, LOCAL installations NOT meant for production :

Make sure that the Neo4j server is running, as discussed in the section on Neo4j.

Make sure that your `config.ini` file contains the line: DEPLOYMENT = FLASK

Run `main.py`, in the context of your virtual environment, which starts Flask and the included Werkzeug web server.
If you're using an IDE such as PyCharm, the virtual environment is automatically taken care of, if you simpy run `main.py`

Set your browser to   http://localhost:5000

If it doesn't find the database (e.g., if you forgot to start Neo4j), it'll give you an error message such as:
"Exception: CHECK WHETHER NEO4J IS RUNNING!"

In case of database-connection problems, you may also try to run the following diagnostic files (in the top folder of the installation):

• diagnostics.py
  
• diagnostics_db_connect_1_MANUAL.py
• diagnostics_db_connect_3_FROM_CONFIG.py

Now you can skip to the next section, Using the Brain Annex web app!





For Linux, here we'll cover multiple cases: installations employing the built-in WSGI HTTP server that comes with Flask ("Werkzeug"), OR using an external WSGI HTTP server such as gunicorn. Typically, SERVER installations


First make sure that the Neo4j server is running, as discussed in the section on Neo4j.

Next, you can do the following testing (OPTIONAL, but highly recommended for first installations):

[OPTIONAL SECTION]

( you may skip the following 2 first steps, if you never deactivated the virtual environment from earlier)

$   cd /home/brain_annex	CHANGE the directory name, if you used a different one
$   source venv/bin/activate	To start the virtual environment

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

(venv) $   python3 diagnostics.py (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 diagnostics_db_connect_1_MANUAL.py
(just for testing, if desired; enter   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) $   python3 diagnostics_db_connect_3_FROM_CONFIG.py
(just for testing, if desired; it uses the dbase credentials in the Brain Annex config file. If all goes well, it will show some diagnostic info)

(venv) $   deactivate

END of TESTING part for the Linux server installation. Continue to one of the 2 options below: either Flask's built-in server or to Gunicorn...

---

(OPTION 1 of 2 – server installation using Flask's built-in server Werkzeug)
Make sure that port 5000, or whichever port is used below, is open; check the firewall rules on your VM

$   cd /home/brain_annex	CHANGE the directory name, if you used a different one
(venv) $   source venv/bin/activate	To start the virtual environment
(venv) $   cat config.ini | grep DEPLOYMENT	to make sure that you have DEPLOYMENT = FLASK 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

TESTING IT
Set your browser to   http://YOUR_SERVER_IP_ADDRESS: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 of 2 – server installation using Gunicorn, with or without Caddy; COMMON INITIAL STEPS for all Gunicorn variations below)

$   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 #   cat config.ini | grep DEPLOYMENT	make sure it says:   DEPLOYMENT = EXTERNAL
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.10+
(venv) root #   export PYTHONPATH=$PYTHONPATH:`pwd`/venv/lib/python3.10/site-packages	OR whichever version was shown in the previous step; it MUST be 3.10+

If you're following Option 2 (i.e. server installation using Gunicorn, with or without Caddy), finish up with EITHER 2a OR 2b OR 2c:


(OPTION 2a - IF using Gunicorn with HTTP, on port 80, NO Caddy)

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 0.0.0.0:80 main:app &

OR variations such as:
(venv) root #   gunicorn --worker-class gthread --threads 3 -w 1 -b 0.0.0.0:80 main:app > brainannex_log.txt &
(Parameter recommendations in the gunicorn docs)

TESTING IT
Set your web browser to http://YOUR_SERVER_IP_ADDRESS

(OPTION 2b - IF using Gunicorn with HTTPS, on port 443, NO Caddy)

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
Make sure that you have a domain name, pointing to your VM
Get a digital certificate (we recommend the free and convenient Let's Encrypt)

EITHER DO A "MINIMALIST" INVOCATION of gunicorn:
(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 0.0.0.0:443 main:app   > brainannex_log.txt &
(Replace YOUR_DOMAIN with whatever you're actually using, such as example.com)

OR, ALTERNATIVELY, USE MULTIPLE WORKERS (for example, 5):
(venv) root #   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 &
(The gunicorn docs recommend  (2 x $num_cores + 1)  as the number of workers to start off with.   To find the number of cores, you can use lscpu)

TESTING IT
* If you run   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.
* 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

(OPTION 2c - IF using Caddy alongiside Gunicorn. In this case, Gunicorn will use HTTP, on port 8000)

Make sure to follow the common initial steps of Option 2, above.
Make sure that port 8000 is open; check the firewall rules on your VM
Make sure that you have a domain name, pointing to your VM
(Note: Caddy takes care of automatically getting a digital certificate for you, if you have a domain name)

If you don't already have a file named "Caddyfile" in your project top folder (for example /home/brain_annex), make sure to create one. A generic one, fine-tuned for using the BrainAnnex app with your own domain name, is https://github.com/BrainAnnex/brain-annex/blob/main/Caddyfile (make sure to change the domain name to your own.)

(venv) root #   gunicorn -w 7 --error-logfile gunicorn_log.txt -b 0.0.0.0:8000 main:app   > brainannex_log.txt &
(The gunicorn docs recommend  (2 x $num_cores + 1)  as the number of workers to start off with.   To find the number of cores, you can use lscpu)

Start Caddy (if not already running from a previous installation):   sudo caddy start


TESTING IT
* Is Gunicorn running? If you enter into the Linux shell:   ps -e | grep gunicorn   , and you should see (1 + number of workers) gunicorn processes (running in the background.)
* To bypass Caddy and only test the gunicorn server, set your browser to http://YOUR_IP_NUMBER:8000
* Is Caddy running? Try the Linux command:   curl localhost:2019/config/ | jq
* To test the complete system, 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

If you followed the directions in the previous sections, when you set your browser to the URL specified in the instructions in that section for your specific installation scenario, you should see a simple web pages with a message and a few links.

Depending on the deployment you used, the URL could be:

• https://YOUR_DOMAIN
• http://YOUR_SERVER_IP_ADDRESS
• http://localhost:5000

Create User Login Account (first user or additional users)

If this is your initial install of the web app, you must create a first user login account (the first account creation will also add the "Schema" data necessary for User management.)

You may also re-run the same script, below, at any later time to create additional login accounts:

(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_installation.py
(to create a new app user, it will prompt you for a new username, a desired password, and an optional email)

---

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_installation.py

Test the Login Functionality

Go the the login page from the earlier section. (The specific URL will depend on your installation specifics.)

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

ALL DONE!

Congratulations, now you can start using the various control panels offered by the Brain Annex web app.
If you also ran the optional earlier step "Create Database Schema", you will in addition have access to the multimedia content-management capability of Brain Annex.

If, at a later date, you upgrade the software, refer to the page for Routine Upgrades.