Prerequisite

1. Python 3.7 or above

Additional required packages will all be installed during the installation script, therefore not listed. It is also noted that the default Python distribution on Ubuntu 18.04 is Python 3.6, therefore not satisfying the requirement. You need to either manually update the Python distribution so that python3 --version is up-to-date or use Ubuntu 20.04 LTS, which comes with Python 3.8.

2. MySQL Server

MySQL Community Server can be easily installed on any linux computer with the following commands.

      
  sudo apt-get update
  sudo apt-get install mysql-server
      
    

All procedure assume that your working directory is the main directory of the cloned Git folder (i.e.: /home/ubuntu/BRAVO_SSR).

In addition, it is recommended to manually create a SECRET_KEY variable for Django. You can either manually edit Line 17 of install.sh to put your own secret key, or use export command in bash command line to create that manually.

1. SQL Database

SQL Database will be used to store account information, patient entries, device entries, and various recording information. Due to the data size, neural recordings are not directly stored in database, but instead stored locally in binary format at the DataStorage folder. A data pointer that associate local files with patient recording will be stored in database for ease-of-access.

SQL Database will require manual creation prior to main server installation unless an existing database is used. You can access MySQL Database (the default database used for the installation script, but other database can be used.)

      
  sudo mysql -u root
  # this would prompt you to enter admin password here for superuser privilege.

  # Following commands are within mysql command-line-interface
  # Create database named "PerceptServer"
  mysql> CREATE DATABASE PerceptServer;

  # Create a user that can access the database called "DjangoUser" with an admin password called "AdminPassword"
  # Change these values to what you see fit.
  mysql> CREATE USER 'DjangoUser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'AdminPassword';
  mysql> GRANT ALL PRIVILEGES ON PerceptServer.* TO 'DjangoUser'@'localhost';
  mysql> FLUSH PRIVILEGES;

  # exit MySQL Interface 
  mysql> exit
      
    

Once the account is set-up and database is created. You can edit the mysql.config file to reflect actual accses credential for your database.

2. Installation Procedure

Change permission to the installation script to "can execute",and run the script as a shell script. The shell script will install other important dependencies first, so admin permission is required.

      
  sudo chmod +x ./install.sh
  ./install.sh
  # Installation script would prompt you to enter admin password here for superuser privilege.
      
    

During installation, 4 variables are required for configurations.

First, a default admin username (email) and password is asked. It is not "required" as the system can operate without any admin account. But for users who do not want to manually promote a new account as admin, this allow easy creation of one admin account for the platform. If you decide to skip through these configurations, a standard Admin account will still be created, except that the password is going to be cryptic due to random generator.

Then, the path to the DataStorage folder will be asked. This is defined as an empty directory for storing all Percept data and processed data. It is recommended to use a backup-enabled folder (such as a folder synced with HIPAA Compliant Dropbox or OneDrive server). This directory will be created by the installation script if a non-existing directory is given.

Lastly, a server IP address is required by the user. It is recommended to put your external static IP here for Django Server setup. If you are going to use localhost only, leave it as localhost will be fine.

During the auto-installation process, bash script will create a Python Virtual Environment called PerceptPlatformEnv and place it in the same root directory as Django project. Necessary Python packages (dependencies) will be installed. Then, the script will create a WSGI file (more about it later) called wsgi_production.py in PerceptServer_Pro folder. This file will serve as main entry point for Apache Server to run Django file, therefore, it will store all information you configured as environment variables for Python.

Afterward, it will also create a production configuration file for Apache 2 Server automatically while disable the default Apache 2 virtual host and enable Percept Analysis Platform in your virtual host.

Last bit of the installation script will perform clean up, such as creating static folders, giving Apache 2 permissions to your Django folder and your DataStorage folder.

Deployment

The Server-side renderring version of BRAVO is a standalone application using Django, which means you can simply deploy your application by calling the following code in commandline:

      
  # Assume you are in the Home Directory of the BRAVO Repository

  # Activate the Virtual Environment Created during installation script.
  source venv/bin/activate 

  # Start Django Server
  python3 manage.py runserver 0:8000
      
    

Now you can simply go to your browser and access http://localhost:8000 to see the server interface.

As of now, we do not recommend public deployment via cloud server. If you desire public deployment and have received institutional approval for public database, feel free to contact us to

Prerequisite

1. Python 3.70 or above (Anaconda Python Distribution is ok, but the same privilege limitation apply).

2. Apache Server and MySQL Database (XAMPP).

1. SQL Database

SQL Database will be used to store account information, patient entries, device entries, and various recording information. Due to the data size, neural recordings are not directly stored in database, but instead stored locally in binary format at the DataStorage folder. A data pointer that associate local files with patient recording will be stored in database for ease-of-access.

SQL Database will require manual creation prior to main server installation unless an existing database is used. You can access MySQL Database (the default database used for the installation script, but other database can be used.) through the following method. MySQL Database is installed along with Apache through XAMPP.

      
  # In Windows Command Prompt, where %XAMPP_PATH% is the full path to your XAMPP installation folder. 
  %XAMPP_PATH%\mysql.exe -u root
  # this would prompt you to enter admin password here for superuser privilege.

  # Following commands are within mysql command-line-interface
  # Create database named "PerceptServer"
  mysql> CREATE DATABASE PerceptServer;

  # Create a user that can access the database called "DjangoUser" with an admin password called "AdminPassword"
  # Change these values to what you see fit.
  mysql> CREATE USER 'DjangoUser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'AdminPassword';
  mysql> GRANT ALL PRIVILEGES ON PerceptServer.* TO 'DjangoUser'@'localhost';
  mysql> FLUSH PRIVILEGES;

  # exit MySQL Interface 
  mysql> exit
      
    

This link share a detail tutorial on creating the database without using command-line.

Once the account is set-up and database is created. You can edit the mysql.config file to reflect actual accses credential for your database.

2. Installation Procedure

All procedure assume that your working direcctory is the main directory of the cloned Git folder (i.e.: C:\Users\Username\Documents\GitHub\PerceptAnalysis_Server).

It is highly recommended to have Python installed with administrator privilege. This allow Apache Server service to be run as Local System Account, instead of being tied to a specific account. For use with specific account, additional steps are required (see below).

a. Python Environment Setup

Open Command Prompt as administrator (or not, if you are using it with specific account), verify with python --version that the installed Python Version is above 3.70 (minimum version required for DateTime conversion for Percept JSON structure). Install Python Virtual Environment tool with PyPI.

Install virtual environment with virtualenv. The following steps will install PerceptPlatformEnv folder in the Django root folder along with other server-side codes. Doing this instead of installing Python Environment at a shared location allow easier navigations and configurations for Apache. Once install, verified that you see (PerceptPlatformEnv) prepend to your command line prompt. Then you can install dependencies package in the new environment

      
  # In Anaconda Prompt, or Command Prompt, depends on how your Python is installed. 
  pip install virtualenv
  virtualenv PerceptPlatformEnv
  PerceptPlatformEnv\Scripts\activate.bat
  pip install django djangorestframework numpy scipy pandas spectrum mysqlclient requests websocket-client joblib
      
    

b. Django Settinngs and WSGI Settings

Navigate to PerceptPlatform/wsgi_windows.py file. Temporary environment variables are setup already for placeholder. The most important edit is to ensure SERVER_DIRECTORY is correctly labeled, it should be the path to your Django root folder (i.e.: C:\Users\Username\Documents\GitHub\PerceptAnalysis_Server). Leave PERCEPT_DIR and STATIC_ROOT unmodified, but change SERVER_ADDRESS to your computer's Private IPv4 address (internal network). Change DATASERVER_PATH to a backup-enabled folder (such as a folder synced with HIPAA Compliant Dropbox or OneDrive server).

Afterward, ensure all neccessary files are setup by running the following Django Comamnds:

      
  # In Anaconda Prompt, or Command Prompt, using "PerceptPlatformEnv" virtual environment
  python manage.py makemigrations
  python manage.py migrate
  python manage.py collectstatic
      
    

After that is done, try to start the Percept Analysis Platform on localhost to confirm all Python packages are installed without errors. Make sure PerceptServer_Pro/settings.py file has DEBUG = True (line 33) configured, otherwise the website will not function until Apache Server is setup to serve static files. You can view the platform on localhost:8000.

      
  # In Anaconda Prompt, or Command Prompt, using "PerceptPlatformEnv" virtual environment
  python manage.py runserver
      
    

c. Apache Server Setup

The Apache Server used in this example is the XAMPP (Apache Friend) for easy-to-use GUI. Many different network development distributions are available in the same package, but only Apache is needed in this case. The default installation folder is usually C:/xampp, which is how we will refer to in this section.

Once XAMPP installation is done, confirm Apache Server is in C:/xampp/apache folder. Now, we need to create an environment variable that point to the Apache Server for Python modules. Create an environment variable called MOD_WSGI_APACHE_ROOTDIR and set its value to C:/xampp/apache. [System Properties -> Environment Variables... -> System Variables -> New...]

Return back to the command prompt, now install mod_wsgi package for Python. You may need to restart command prompt so the new Environment Variable is registered, otherwise mod_wsgi building will have errors.

      
  # In Anaconda Prompt, or Command Prompt, using "PerceptPlatformEnv" virtual environment
  pip install mod_wsgi
      
    

Once mod_wsgi is installed, verify the module configuration with command mod_wsgi-express module-config and copy its content (except the WSGIPythonHome) to C:/xampp/apache/conf/httpd.conf. It should look like something below.

      
  # In Anaconda Prompt, or Command Prompt, using "PerceptPlatformEnv" virtual environment
  mod_wsgi-express module-config

  # Expect the following output:
  LoadFile "C:/Program Files/Python310/python310.dll"
  LoadModule wsgi_module "C:/Users/Username/Documents/GitHub/BRAVO_SSR/PerceptPlatformEnv/lib/site-packages/mod_wsgi/server/mod_wsgi.cp310-win_amd64.pyd"
      
    

Now, configure the httpd-vhosts.conf file in the cloned directory. The following information are needed:

1. ServerName

Change localhost to the IP address you set for SERVER_ADDRESS in PerceptAnalysis/wsgi_windows.py file.

2. Directory Path

Essentially, all occurrence of C:/Users/Username/Documents/GitHub/PerceptAnalysis_Server in the template file should be changed to where you store your cloned Django root folder. This occur multiple times in the file, make sure they are all changed (Line 3, Line 5, Line 6, Line 10, Line 17) but make sure their suffix folders or filename are untouched.

Now that all contents are changed, copy httpd-vhosts.conf file to C:/xampp/apache/conf/extra/httpd-vhosts.conf and replace the original file (the original file has no actual content, so you can simply copy the text content of your modified file and append at the end of the original file as well).

Deployment

Open XAMPP as Administrator, this will allow you to install Apache as a Windows Service. If you do not wish to have Apache as Windows Service, you can open it as local user. If you are Admin, you can see a red cross mark to the left of Apache module, clicking it will install Apache Windows Service. If not, clicking Start to the right of Apache will start Apache in Port 80 (HTTP) and Port 443 (HTTPS) with your application configurations. You can now view your data through http://%SERVER_ADDRESS%/ (registration may be required or you can use the admin account you set up during installation).

For Python installed on individual user, Apache will most likely have no permission to view your Python executable when used as Local System Account, and therefore lead to error in deployment as Windows Service (most typically, Fatal Python error: initfsencoding: unable to load the file system codec ModuleNotFoundError: No module named 'encodings'). For this situation, open Windows Service tab and Right click on Apache service ApacheX.Y (sub X and Y to your Apache version) and view Properties. Go to Log On tab and specify a specific account using This Account option instead of Local System Account. This is also the same place where you can input a domain account to access Network Resources.