Setting up PyIRE

Installation

It is generally recommended that PyIRE is installed into its own virtualenv (see `https://pypi.python.org/pypi/virtualenv`_).

Installing the Core Software

It is recommended that you install the latest stable release, but if you wish to contribute back to the project, please consider installing the latest development version from source.

Stable releases

To install the latest stable release run:

pip install pyire

To install an older release, download the release from https://bitbucket.org/mhall/pyire/downloads and then install using:

pip install pyire-x.y.z.tar.gz

Source code

To install the latest development version from source, clone the Mercurial repository:

hg clone hg clone https://bitbucket.org/mhall/pyire

Additional Required Packages

PyIRE additionally requires further packages to be fully operational:

  • a cryptography library to support secure session cookies;
  • a database access library.

Secure session handling

You need to install either pycryptopp or PyCrypto packages to enable the use of secure session cookies:

pip install pycryptopp

or

Download PyCrypto from https://www.dlitz.net/software/pycrypto/ and install using pip install pycrypto-X.Y.tar.gz.

Database access

PyQuestionnaire uses SQLAlchemy as its database access library and thus in theory supports any database supported by SQLAlchemy. The following databases have been tested with PyQuestionnaire:

PostgreSQL

Recommended, fully supported and tested with the psycopg2 database adapter:

pip install psycopg2

MySQL

Fully supported and tested with the mysql-python database adapter:

pip install mysql-python

SQLite
Only supported for testing purposes. SQLite does not support all DDL statements required to upgrade the database for future releases, thus it is not recommended to use it in a production environment.
All other databases
Should in theory be supported, but have not been tested. If you have deployed PyIRE using another database backend, please let us know and the documentation will be updated.

Configuration

The next step is to set up PyQuestionnaire so that it is ready to run. For this you need to:

  1. Generate a configuration file
  2. Initialise the database

Both tasks are done using the configuration application included in PyIRE. To see all options provided by the configuration application run:

PyIRE -h

Generate the Configuration

To generate a configuration file run:

PyIRE generate-config

You will be asked to provide the `SQLAlchemy connection string`_ for your database. If you don’t know it yet, you can accept the default test database and change the configuration setting later.

You can also set the following parameters on the command-line:

  • –sqla-connection-string <SQL Alchemy connection string>
  • –filename <Configuration Filename defaults to production.ini>

Initialise the Database

The next step is to initialise the database:

PyIRE initialise-database <Configuration File>

and the required database tables will be created. During testing you might want to re-create the initial database. In that case run:

PyIRE initialise-database <Configuration File> --drop-existing

and the old tables will be removed and the database re-created in its initial state.

If you change the `SQLAlchemy connection string`_, then you need to re-run the database initialisation.

Deployment

In-production deployment has been tested using Apache2 and mod_wsgi. However, you can also use the internal server provided by `Pyramid`_, either directly or behind a reverse proxy.

Deploying with Apache2 & mod_wsgi

To deploy PyIRE via Apache2 and mod_wsgi add the following settings to the VirtualHost configuration:

WSGIDaemonProcess pyire user=www-data group=www-data processes=1 threads=10 python-path=/path/to/virtualenv/lib/python2.7/site-packages
WSGIScriptAlias /pyire /path/to/the/application.wsgi
<Location /pyire>
    WSGIProcessGroup pyire
</Location>

Note: Leave the processes value at 1. Use the threads option to specify how many parallel requests to support.

Then create the following script to to run the application via WSGI. Adapt it by replacing the paths with the paths to where PyIRE is installed:

import os
os.chdir(os.path.dirname(__file__))
import site
import sys

# Remember original sys.path.
prev_sys_path = list(sys.path)

site.addsitedir('/path/to/virtualenv/lib/python2.7/site-packages')

# Reorder sys.path so new directories at the front.
new_sys_path = []
for item in list(sys.path):
    if item not in prev_sys_path:
        new_sys_path.append(item)
        sys.path.remove(item)
sys.path[:0] = new_sys_path

from pyramid.paster import get_app
from paste.script.util.logging_config import fileConfig
fileConfig('/path/to/the/application/pyire.ini')
application = get_app('/path/to/the/application/pyire.ini', 'main')