BCO Portal Local Deployment

Configuration

In order to work with BCO API locally on a Mac OS, please follow the following steps to set up:

BCO_API

1. Clone the GitHub Repository
   1. Open Terminal, enter the following commands:
      1. git clone https://github.com/biocompute-objects/bco_api
      2. cd bco_api
2. Switch to the latest release branch:
   1. git switch 22.10
3. Enter the repository, create a virtual environment, and install the required packages:
   1. pyenv local 3.9.4 (Note: will show as pyenv: command not found if already installed)
   2. python3.9 -m venv env
   3. source env/bin/activate (activated virtual environment by showing (env) (base) MacBook-Pro-3:bco_api)
   4. python -m pip install -r requirements.txt (if installation failed, make sure you are in the correct path: /Users/Username/bco_api)
4. Modify Configuration file
   1. Once in the virtual environment, make sure you are on the path:/Users/Username/bco_api
   2. Edit the server.conf file: vim bco_api/bco_api/server.conf
5. Quick check to make sure the server can run
   1. cd bco_api/bco_api (Note after this command, should under path /Users/Username/bco_api/bco_api)
   2. Make migrations: python3.9 manage.py migrate
   3. If run successfully, should observe the following:
      
6. Create a super user for the API: python3.9 manage.py createsuperuser
   1. Follow the prompts
7. python3.9 manage.py runserver 8000:
   
   1. Once see the messages as shown in the figure above, go to http://localhost:8000/api/admin/ on the local browser to see if BCO API is set up successfully

UserDB

1. Clone the GitHub Repository
   1. Open Terminal, enter the following commands:
      1. git clone https://github.com/biocompute-objects/userdb
      2. cd userdb/
2. Switch to the desired branch: e.g. git switch 22.10
3. Enter the repository, create a virtual environment, and install the required packages:
   1. pyenv local 3.9.4
   2. python3.9 -m venv env
   3. source env/bin/activate
   4. python -m pip install -r requirements.txt
4. Modify the Config file: vim portalusers/settings.py
5. Make migrations: python3.9 manage.py migrate
6. Create a super user for the API: python3.9 manage.py createsuperuser (Note: this step can be skipped if a superuser is already created or not superuser account is not necessary)
7. Run server: python3.9 manage.py runserver 8181
   1. If ran successfully, you should observe as shown in the following figure:
      
   2. Once see the messages as shown in the figure above, go to http://localhost:8181/users/admin/ on the local browser to see if BCO API is set up successfully (Note: If it worked you should be able to login using the SuperUser credentials you created above)

Portal Deployment Instructions

1. Clone the repository
   1. git clone https://github.com/biocompute-objects/portal
   2. cd portal/
2. Switch to the desired branch: e.g. git switch 22.10
3. Install packages with either of the following commands:
   1. npm install
   2. npm install --legacy-peer-deps
4. Edit /portal/src/App.js line 87 based on your need :
   1. For local, sending = hostnames.local
   2. For the test site, sending = hostnames.test
   3. For the production site, sending = hostnames.production
5. Start running: npm run start

Production Portal Deployment

The BCO API repository contains a top-level folder “admin_only” which contains service definitions for gunicorn and Django. Thus, we can first clone the repository, then perform a few administrative steps to start the API.

1. Connect to 'go.vpn.gwu.edu/SMHS_BIOC' VPN first.
2. Enter test/production server via: ssh USERNAME@test.portal.biochemistry.gwu.edu (for test server)/ssh USERNAME@portal.biochemistry.gwu.edu (for production server) (Note: /home and /etc are shared between the two servers)
3. Backup and archive DB:
   1. cd /var/www/bcoeditor/db_backups
   2. cp ../bco_api/bco_api/db.sqlite3 db.sqlite3.bak.api.[TODAY'S DATE] (e.g. cp ../bco_api/bco_api/db.sqlite3 db.sqlite3.bak.api.22.10.25)
   3. cp ../userdb/db.sqlite3 db.sqlite3.bak.udb.[TODAY'S DATE]
   4. cp ../bco_api/bco_api/server.conf server.conf.bak.[TODAY'S DATE]
4. Pull the repository
   1. cd /var/www/bcoeditor/bco_api
   2. git clone https://github.com/biocompute-objects/bco_api (if cloned already, step not needed)
5. Enter the repository, create a virtual environment and install the required packages：
   1. First switch to the proper user account via su - bco_api_user （If you need to use this account, please contact the BCO team for the password)
   2. Switch to the desired branch: git switch 22.11
   3. source env/bin/activate
   4. pip3.9 install -r requirements.txt
6. Check the Configuration files:
   1. Edit the server.conf file: vim /var/www/bcoeditor/bco_api/bco_api/server.conf
      1. Change the version number to match the version you are modifying
7. Make sure the server can run and Make Migrations:
   1. cd /var/www/bcoeditor/bco_api/bco_api
   2. python3.9 manage.py migrate
   3. python3.9 manage.py collectstatic
   4. python3.9 manage.py runserver 8000
   5. Go to https://test.portal.biochemistry.gwu.edu/api/admin/ to check if the server runs properly
   6. Ctrl+C to exit the running server
8. sudo Steps:
   1. nGinx (only if bco_api.conf was modified): sudo cp /var/www/bcoeditor/bco_api/admin_only/bco_api.conf /etc/nginx/conf.d/
   2. Gunicorn (only if bco_api.conf was modified):
      1. Copy the system service files over:
         1. sudo cp /var/www/bcoeditor/bco_api/admin_only/bco_api.service /etc/systemd/system/bco_api.service
         2. sudo cp /var/www/bcoeditor/bco_api/admin_only/bco_api.socket /etc/systemd/system/bco_api.socket
      2. Enable files: sudo systemctl enable bco_api
      3. Start the service: sudo systemctl start bco_api
   3. Make sure the service is running: sudo systemctl status bco_api
9. Access API via web browser:
   1. Restart the server: sudo systemctl restart nginx
   2. Deactivate virtual environment: deactivate
   3. Check the server by going to either site on the web browser: https://biocomputeobject.org/api/admin/ (login using the SuperUser credential just created) or https://biocomputeobject.org/api/docs/

UserDB Production Portal Deployment

1. Connect to 'go.vpn.gwu.edu/SMHS_BIOC' VPN first.
2. Enter test/production server via ssh USERNAME@test.portal.biochemistry.gwu.edu (for test server)/ssh USERNAME@portal.biochemistry.gwu.edu (for production server) (Note: /home and /etc are shared between the two servers)
3. Enter the repository: cd /var/www/bcoeditor/userdb
4. Clone the repository: git clone https://github.com/biocompute-objects/bco_api
5. Change directory: cd /var/www/bcoeditor/userdb/bco_api
6. Go to the desired branch/tag: git switch 22.11(this number should be whatever branch you want to go to)
7. Create a virtual environment: source env/bin/activate
8. Install the required packages: pip3.9 install -r requirements.txt
9. Modify the Configuration file: vim /var/www/bcoeditor/userdb/portalusers/settings.py
10. Make sure the server runs properly: cd /var/www/bcoeditor/userdb
    1. Make migrations: python3.9 manage.py migrate followed by python3.9 manage.py collectstatic
    2. Create a super user for the API: python3.9 manage.py createsuperuser
    3. Run server: python3.9 manage.py runserver 8080
    4. Ctrl+C to exit the running server
11. Deactivate the virtual environment
12. sudo Steps:
    1. Gunicorn (only if userdb.service OR userdb.socket IS MODIFIED): cd admin_onlu
       1. Copy the system service files over:
          1. sudo cp /var/www/bcoeditor/userdb/admin_only/userdb.service /etc/systemd/system/
          2. sudo cp /var/www/bcoeditor/userdb/admin_only/userdb.socket /etc/systemd/system/
       2. Enable files: sudo systemctl enable bco_api
       3. Start the service: sudo systemctl start bco_api
    2. Make sure the service is running: sudo systemctl status bco_api
    3. Restart the server:sudo systemctl restart nginx
    4. Make sure API is accessible via web browser. (EX: https://portal.biochemistry.gwu.edu/users/admin/. Log in using the superuser credential created)

Portal Deployment

1. Pull the repository: cd /var/www/bcoeditor/portal
2. Switch branch:git switch --detach 22.01(any branch name) -f
3. npm install or npm install --legacy-peer-deps
4. Edit /var/www/bcoeditor/portal/src/App.js based on need. For example, when working on the test portal, make sure const sending = hostnames.test, also update the versions under const versions