These are the installation instructions for the Web Interface. For instructions for the Base Code see the google code site.
There are some dependencies to install the web interface
Additionally, mysql-python currently require
In Ubuntu (or another debian based system) these can be installed using:
$sudo apt-get install python-dev python-pip python-virtualenv libmysqlclient-dev bzr git
To aid development, this code has been configured to use setuptools for distribution. This allows changes to the code to be tested using the develop function. Allowing changes to the code to be immediately reflected in the python environment, rather than requiring a fresh #setup.py install call.
Additionally, I recommend developing in a virtual environment this is the equivalent of a clean python install, allowing any problems that may occur with missing packages / different package versions to be seen. This is a great advantage when packaging, as installing from scratch allows testing of installation steps.
Note
Using a virtualenv is not mandatory. For example if you are installing on a production server and are unlikely to make any changes to the code. However, for development its a extremely useful tool.
To setup the virtual environment.
Note
These steps use pip to install packages. However, feel free to use your favourite package manager (easy-install etc)
Install virtualenv:
$pip install virtualenv
Setup Virtual Environment. Using the –no-site-packages flag means that we get the equivalent of a clean python install:
$virtualenv --no-site-packages testenv
To use the virtual environment activate it. Missing this stage can be a common source of problems, as the program tries to use packages that are not in the system wide library:
$cd testenv
$source bin/activate
(testenv)$
And to shut everything down afterwards, deactivate it:
(testenv)$ deactivate
$
Grab the latest version of the source from launchpad
For Stable:
$bzr branch lp:cogent-house
To install in development mode:
(testenv)$ setup.py develop
Note
There appears to be a bug in easy_install when installing numpy. This means that the setup.py develop step may not work. A simple work around is to install numpy with pip (which for some reason works) then rerun the setup script:
$pip install numpy
$python setup.py develop
The database setup script can be called by running:
$initialize_cogentviewer_db <config>.ini
Currently, the web interface uses a local version of the javascript libaries, this avoids any problems when there is no internet connection available.
Unpack the jsLibs.tar.gz file in the same base directory as the webinterface:
dan@einstein:~$tar -xvzf jsLibs.tar.qz
dan@einstein:~$ ls -l
total 38956
drwxr-xr-x 4 dan dan 4096 2012-06-15 14:53 cogent-house
drwxr-xr-x 5 dan dan 4096 2012-06-13 12:00 jslibs
-rw-r--r-- 1 dan dan 7456451 2012-06-15 14:57 jsLibs.tar.gz
Once the application is installed in development mode. It is possible to test the server
Activate the virtual env:
$cd testenv
$source bin/activate
Navigate to the cogent-viewer base directory:
(testenv)$cd cogentviewer
Start the Paste server:
(testenv)$pserve --reload development.ini
The web interface should now be available at 127.0.0.1:6543
The application also has a suite of unit tests.
Testing is performed using the nose test runner.
Rather than use a live database, the Unit tests use a separate testing DB.
To set this up create a new schema testStore and user test_user with password test_user
We also need to populate the database with its initial testing data the simplest way to do this is to run an instance of the paste server using the test.ini script:
$initialize_cogentviewer_db test.ini
Note
If you want to use an alternative database, it is possible to modify the database string found in the test.ini setup file.
Warning
Unfortunately it is impossible to run the unit tests using a separate sqlite database There have been locking issues as parts of the code try to access the DB, meaning that several tests fail.
As the REST interface communicates with the server, we need to have an instance of the web server running for the tests to complete.
Start an Instance of the paste server running the test.ini script:
(testenv)$pserve serve --reload test.ini
Run the Unit tests:
(testenv)$nosetests
An alternative method to serve the web interface under apache, setup a reverse proxy to forward requests to the paste serve
We first need to enable the mod-proxy module on the apache server:
$sudo a2enmod proxy
Note
If you get an error loading the site, you may need to enable proxy_http
Then Modify the default site /etc/apache2/sites-available/default:
ProxyRequests Off
ProxyPreserveHost On
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /webInterface/ http://localhost:6543/
ProxyPassReverse /webInterface/ http://localhost:6543/
Finally we need to make a modification to the paster .ini script used to serve the application, add the following directing to the config file, just before the [server:main] directive:
filter-with = urlprefix
[filter:urlprefix]
use = egg:PasteDeploy#prefix
prefix = /webInterface
Note
This modification has been made in the proxy.ini config file
The Documents are built with Sphinx <http://sphinx.pocoo.org/index.html>`_
Most of the information comes from docstrings in the code itself. Please keep these up to date.
To build the Docs it is as simple as:
$cd docs
$make html
Exporters are available for HTML and Latex (amongst others)
Warning
Some Ubuntu versions of sphinx are old, and will generate an error when building the graphs. To avoid this install the latest version of sphinx from PyPy:
#sudo pip install --upgrade Sphinx
The webinterface requires an upto date version of the database. If the web interface is installed on top of an pre-exisiting base server. You will need to update the database using the following steps.
Get the and latest version of the base software, from here
Backup the Database:
$mysqldump -u chuser -l -v ch > chDump.sql
Install Alembic:
$pip install alembic
Backup the Database (Included here incase you don’t feel it is important)
Run the Alembic Upgrade Script:
$alembic upgrade head