Cytoscape Wiki|
Size: 10122
Comment:
|
Size: 95
Comment: moved
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
|
= App Store Code Structure = == 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 backend that are served as is without any processing from Django. == Explanation of important files == === Configuration Files === * {{{settings.py}}}: Django settings file for configuring things like the database, location of templates, static files, and so on. * {{{urls.py}}}: the general URL layout of the entire site. Each URL entry in this file delegates URL paths to each Django app. * {{{django.wsgi}}}: 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}}}: programs can obtain details of apps from the backend; used by the Cytoscape App Manager * {{{help}}}: about, contact us, getting started pages * {{{submit_app}}}: Cytoscape 3.0 app submission pages and jar verification === Other Directories === * {{{templates}}}: Templates in this directory are 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. When deploying the site to Apache, Apache should directly serve these files instead of through Django. * {{{util}}}: small utility functions used throughout the site's code = How to set up the App Store on your computer = The App Store requires the following software packages. If you're on a Mac, this can be installed with [[http://mxcl.github.io/homebrew/|Homebrew]]. If you're on Linux, use your distribution's package manager. Note that the versions specified here are not mandatory. They only indicate the version with which I've tested the App Store. * Python 2.7 * xapian 1.2.13 (free-text searching) * xapian-bindings 1.2.13 * This package is not available through Homebrew. The package must be [[http://oligarchy.co.uk/xapian/1.2.13/xapian-bindings-1.2.13.tar.gz|downloaded]] and installed manually. When running the `configure` script, make sure to add the `--with-python` argument: `./configure --with-python` * You can test that Xapian is working correctly by starting Python and typing: `import xapian`. If you don't get any errors, then Xapian is working. * libjpeg 8d (used by PIL) * libpng 1.5.14 (also used by PIL) * GeoIP 1.4.8 (converts IP addresses to geographical locations) The following Python packages are also required. Each can be installed with `pip install`. If you don't have `pip`, type: `easy_install pip`. * Django 1.5.1 * MySQL-Python (aka MySQLdb; can be installed with Debian/Ubuntu's package manager; Django uses this to connect to the MySQL database) * PIL 1.1.7 (can be installed with Debian/Ubuntu's package manage; needed to scale icon and screenshot image files) * PIL ''must'' be built the JPEG support. At the end of PIL's installation, you'll see a printout titled `PIL 1.1.7 SETUP SUMMARY`. This must list JPEG as supported. * django-social-auth (aka social_auth; allows users to log in with their Google accounts) * IPython -- optional (very useful for debugging) == Why not virtualenv? == `virtualenv` is a tool for Python projects that allows encapsulating a project's dependencies. These dependencies are available only for that project and don't pollute the Python library dependencies of another project. `virtualenv` works great if a project's dependencies are only available through `pip`. However, that's not the case with this codebase, since it needs non-Python libraries like `xapian` or `libjpeg`. == Making sure GeoIP is working == 1. Open `settings.py` and make sure the `GEOIP_*` variables are set correctly. * `GEOIP_LIBRARY_PATH` points to the specific location of the GeoIP library file. For example: `GEOIP_LIBRARY_PATH = '/usr/local/Cellar/geoip/1.4.8/lib/libGeoIP.1.dylib'` * `GEOIP_PATH` points to the directory of GeoIP data files. 1. Type `python manage.py shell`. Enter: {{{ import django.contrib.gis.geoip django.contrib.gis.geoip.HAS_GEOIP}}} 1. You should see `True`. If it's `False`, GeoIP is not configured correctly. = How requests are handled = {{{ || | | | | || Request=>|| ==Apache==> | == sites-enabled/appstore ==> | == django.wsgi ==> | == settings.py ==> | == urls.py || || | | | | || }}} 1. An HTTP request is made to the Apache server. 1. 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}}}. 1. {{{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/CyAppStore/django.wsgi}}}. 1. {{{django.wsgi}}} starts the Django library. It also tells Django the location of {{{settings.py}}}, which Django needs to start the site. 1. {{{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. 1. {{{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. 1. The handler function returns with a processed HTML page. = 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/CyAppStore/django.wsgi }}} This tells Apache and mod_wsgi where to locate the site code. Make sure the path to {{{django.wsgi}}} is correct. 1. {{{/var/www/CyAppStore/django.wsgi}}} This file invokes Django's WSGI handler. It needs to correctly reference {{{settings.py}}} to start the site. Make sure these two lines are correct: {{{ SITE_PARENT_DIR = '/var/www' SITE_DIR = filejoin(SITE_PARENT_DIR, 'CyAppStore') }}} 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, 'CyAppStore') }}} Then check if the variables {{{SITE_PARENT_DIR}}} and {{{SITE_DIR}}} are correct. 1. {{{/var/www/CyAppStore/settings.py}}} This file is pretty complicated. But if you've checked everything at this point, here's some ways to pinpoint problems in {{{settings.py}}}. a. If you're getting an HTTP 500 error, you can get the stack trace by turning on debug mode then reloading the page. Note that 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 }}} a. You can poke at the code by running a Python shell. Enter this command at the shell prompt in the same directory as {{{settings.py}}}: {{{ 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() }}} a. The SQL database settings are specified by the {{{DATABASES}}} variable: {{{ DATABASES = { 'default': deploy_database } }}} Make sure that {{{'default'}}} is pointing to te correct dictionary: {{{ deploy_database = { 'ENGINE': 'django.db.backends.mysql', 'NAME': ... 'USER': ..., 'PASSWORD': ... } }}} a. If you're getting database errors, enter this command at the shell prompt in the same directory as {{{settings.py}}}: {{{ python manage.py dbshell }}} If you're able to get a SQL prompt, that means Django can connect to the SQL database. a. 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 svnclean }}} = Tips = * You can reindex the text search engine with this command: {{{ make index }}} * If you want to remove unused tags, authors, and media files, type this command: {{{ python manage.py garbage_dump }}} If any tags or authors were removed, you will have to reindex the text search engine. * When a developer adds a 2.x plugin, it goes into {{{http://cytoscape.org/plugins/plugins.xml}}} but not automatically into the App Store. To add a newly added plugin in {{{plugins.xml}}} to the App Store, do the following: 1. Download {{{plugins.xml}}} and open it. 1. Find the name of the plugin you want to add. It is enclosed in the {{{<name>}}} tag. 1. Run this command: {{{ python manage.py add_plugins_from_plugins_xml name-of-plugin }}} The name of the plugin ''must'' match what's in the {{{<name>}}} tag. If the name has spaces, enclose the name in quotation marks. Do ''not'' run this command on plugins already with app pages, as it will overwrite its details. 1. Reindex the search engine so the app can found through free text search. |
Moved to https://github.com/cytoscape/cytoscape/wiki/Cytoscape-App-Store:-Site-Administration |