Development

Development environment

Click here to setup an AppStore development environment

Click here to setup a Virtual Machine running the AppStore

NOTE: The instructions below assume: /opt/miniconda/bin/python is the Python being used

Terminology

• Django app: Django organizes websites into separate modules called apps. Each app has its own directory at the top level typically containing files like __init__.py, model.py, and views.py.
• templates: HTML files with placeholders, which Django processes by filling in Python code.
• static files: general website files (images, Java Script, CSS) that are served as is without any processing from Django.
• media files: general website files referenced by the database; they are served as is without any processing from Django.
• mod_wsgi: Apache module that interfaces with Python.

Explanation of important files

Configuration Files

• settings/production.py: Django settings file for configuring things like the database, location of templates, static files, and so on.
  • For local development the file is settings/local.py on Vagrant its settings/vagrant.py To set an alternate just modify wsgi.py and manage.py files replacing settings.local with desired configuration file.
• urls.py: the general URL layout of the entire site. Each URL entry in this file delegates URL paths to each Django app.
• wsgi.py: the configuration file used when the App Store is deployed to an Apache server using mod_wsgi.

Django Apps

• apps: navigation of Cytoscape apps and app pages
• users: user login/logout
• search: free text searching
• backend: JSON representation of 3.0 apps; used by the App Manager in Cytoscape 3.0+
• help: about, contact us, getting started pages
• submit_app: Cytoscape 3.0 app submission pages and jar verification
• download: for downloading releases and tracks download stats for apps

Other Directories

• templates: Templates used throughout the App Store.
• static: Each subdirectory has static files for a Django app. The common subdirectory has static files that belong to the entire site.
  • Run /opt/miniconda3/bin/python manage.py collectstatic to deploy these files to /var/www/html/static and configure Apache to serve this directory.
• util: small utility functions used throughout the site's code
• dbmigration: scripts that directly update SQL tables after changes had been made to database models; only needed when needing to migrate old versions of SQL database backups

How requests are handled

         ||             |                               |                    |                    |            ||
Request=>|| ==Apache==> | == sites-enabled/appstore ==> | == wsgi.py ==> | == settings/production.py ==> | == urls.py ||
         ||             |                               |                    |                    |            ||

1. An HTTP request is made to the Apache server.
2. Apache looks in /etc/apache2/sites-enabled to see how to handle the request. The appstore configuration file is set to handle requests made to http://apps.cytoscape.org.
3. appstore tells Apache to use mod_wsgi. mod_wsgi runs a Python interpreter within Apache. appstore tells mod_wsgi to start Python with /var/www/appstore/wsgi.py.
4. wsgi.py starts the Django library. It also tells Django the location of settings/production.py, which Django needs to start the site.
5. settings.py contains the location of urls.py (defined in the ROOT_URLCONF variable), which is a list of URLs (in the form of regular expressions) and the Python functions that handle them.
6. urls.py in the top directory of the App Store merely imports additional URLs from each Django app. It dispatches the request to the appropriate function that is designated to handle requests for a given URL. Functions are defined in the views.py file in each Django app.
7. The handler function returns with a processed HTML page.

Adding fields to the Resource Well

The Resource Well is located in the lower right of each app page and contains a set of icon-link entries. Here is how you would add a new one:

1. Create new field corresponding to the new feature, in the app model and update the database through django-migrations.
2. In the app_page.html template, create a new section for badge, with source added for the png file in static/app folder and tooltip indicating purpose of the badge. Also link the badge with necessary links.
3. Add the link to the new resource in the Resources Section and add proper icon (we used awesome font icon) for the same.
4. In order to enable the new field to be edited and saved in the database, create new edit fields in the javascript file corresponding to the app_page_edit( static/apps/js/) .
5. Also create corresponding make field save action in SaveActionsToAjax variable.
6. Add the new field in app_page_edit.html in the resources section along with its new icon.

Debugging

1. /etc/apache2/sites-enabled/appstore

   This file tells Apache and mod_wsgi where to find the site. The most important line is this:

   WSGIScriptAlias / /var/www/appstore/wsgi.py

   This tells Apache and mod_wsgi where to locate the site code. Make sure the path to wsgi.py is correct.

2. /var/www/appstore/wsgi.py

   This file invokes Django's WSGI handler. It needs to correctly reference settings/production.py to start the site. Make sure these two lines are correct:

   SITE_PARENT_DIR = '/var/www'
   SITE_DIR = filejoin(SITE_PARENT_DIR, 'appstore')

   To check if these variables are being defined correctly, you can launch a separate Python interpreter and enter these lines:

   from os.path import join as filejoin
   SITE_PARENT_DIR = '/var/www'
   SITE_DIR = filejoin(SITE_PARENT_DIR, 'appstore')

   Then check if the variables SITE_PARENT_DIR and SITE_DIR are correct.

3. /var/www/appstore/settings/production.py

   This file is pretty complicated. But if you've checked everything at this point, here's some ways to pinpoint problems in settings/production.py.

   • If you're getting an HTTP 500 error, you can get the stack trace by turning on debug mode then reloading the page. Note: Debug mode exposes sensitive information about the site to the public. Make sure to keep debug mode off as much as possible. Change to following line to True:

     DEBUG = False

   • You can poke at the code by running a Python shell. Enter this command at the shell prompt in the same directory as production.py:

     /opt/miniconda3/bin/python manage.py shell

     You can check to see if the site's code is working correctly without having debug mode on. For example, to see if the list of all apps is working, enter this into the Python interpreter:

     from apps.models import App
     App.objects.all()

   • The SQL database settings are specified by the DATABASES variable:

     DATABASES = {
                  'default': deploy_database
     }

     Make sure that 'default' is pointing to to correct dictionary:

     deploy_database = {
                     'ENGINE':   'django.db.backends.mysql',
                     'NAME':     ...
                     'USER':     ...,
                     'PASSWORD': ...
     }

   • If you're getting database errors, enter this command at the shell prompt in the same directory as production.py:

     /opt/miniconda3/bin/python manage.py dbshell

     If you're able to get a SQL prompt, that means Django can connect to the SQL database.

   • If you make changes to a Python file but you're not seeing the changes taking effect, you may have to delete all the .pyc files. To do so, type this:

     make clean-pyc

Tips

• You can reindex the text search engine with this command:

  /opt/miniconda3/bin/python manage.py rebuild_index

• If you edit any Python files and need it to be refreshed by Apache, you will need to remove all pyc files:

  make clean-pyc

Debug

• Once the website is deployed in production, turn off the debug option in settings/production.py by setting DEBUG = false