DraconesPH


Installing DraconesPH (Python Version)

This document covers the installation of the Python version of DraconesPH (which works with the Python version of Dracones). There is also a corresponding PHP version, which unfortunately lacks the SaTScan component for the moment.

Basic Components

To be quite honest.. DraconesPH is not the easiest software in the world to install (right now at least). However I will try my best to be as clear as possible in this document. First be aware that DraconesPH relies on the following (mostly open source or free) technologies:

The first step is to install or upgrade to the latest version of Dracones (version ≥ 1.0.0 must be used). When done, you can copy the DraconesPH codebase wherever you want. We will refer to this location from now on as:

<draconesph_location>

Next, add a DraconesPH reference in the Dracones Core configuration file (JSON formatted). If you already have the Dracones Test App installed for instance, this would give:

{
  "ms_tmp_path": "/ms4w/tmp/ms_tmp/",
  "session_path": "/ms4w/tmp/pesto_tmp/",
  "ms_tmp_url": "/ms_tmp",
  "app_conf_filepaths": ["<dracones_core_location>/test_app/conf.json",
                         "<draconesph_location>/conf.json"]
}

Data Model (PostgreSQL + PostGIS)

Next, install the latest version of PostgreSQL, along with the PostGIS spatial extension. On both Windows and Linux, this should be fairly easy. Also make sure you create a PG superuser, with which we'll create the DraconesPH data model. We will access this data model using the Psycopg2 Python library, which can be installed in one step:

$ easy_install psycopg2

You can then create a PostGIS-enabled database:

$ createdb -T template_postgis draconesph

Note that for all the PG commands, you may have to specify the PG user (using the -U switch, preferably with a PG superuser) and a password. Also, if your PG install has not created the template_postgis (typically on Linux I think), you can create one using a script provided in the DraconesPH bundle (make sure that you edit it first so that it contains proper paths to your particular PG install):

$ psql -d template1 -f <draconesph_location>/model/sql/create_template_postgis.sql

You are then ready to create and populate the tables of the DraconesPH data model:

$ cd <draconesph_location>/model/sql
$ psql -d draconesph -f create_draconesph.sql
$ psql -d draconesph -f populate_draconesph.sql

This data model should now contains: 500 randomly located cases with one of three conditions (influenza, hepatitis or fever), 300 randomly located schools, food stores and resto/bars, and 250 randomly picked links between cases and places. It also contains 540 Montreal-Island "Census Tracts" polygonal geometries, as well as 29 greater Montreal-Island "CLSC" polygonal geometries (we'll call those two the "place" layers).

Ext JS

That part is easy: download the latest version of Ext JS (3.2.1 at the time of writing this) and extract it there:

<draconesph_location>/htdocs/javascript/lib/

Make sure it is named "ext", and not "ext-3.x.x", so that it's easy to upgrade in the future.

Apache

From the perspective of Apache, DraconesPH, as is the case for any other Dracones application, is a separate site, with its own settings and codebase. To add a new site corresponding to the DraconesPH application, you can use this configuration file:

<draconesph_location>/apache/httpd_draconesph_python.conf

in which you have to replace the <draconesph_location>s with the proper absolute path (note that Apache being kind, you can use a /whatever/dir notation on Windows as well).

Here is an important additional step, that I have not been able to simplify in a satisfying way unfortunately: Since we don't want different WSGIPythonPath directives in the many Dracones conf files to mess with each other, we have to define one, in one only place: the main, Dracones Core Apache conf file, in which you will replace the existing one, currently probably pointing to only one location:

WSGIPythonPath <dracones_core_location>/python

with this new one, pointing now to two locations:

WSGIPythonPath <dracones_core_location>/python;<draconesph_location>/python

using a ":" separator on Linux, and ";" on Windows.

SaTScan

For the next step you have to download SaTScan, that you can either install graphically (default option) or by using the "Non-Graphical" package found in the "Alternative Download Options" of the Download page, for a command-line only experience.

On Linux, you have to set the permission of the working directory, because SaTScan is run on behalf of Apache:

$ chown -R www-data:www-data <draconesph_location>/satscan

Wrapping It All Up

We finish this installation by editing the DraconesPH JSON configuration file:

<draconesph_location>/conf.json

{
  "app_name": "draconesph",
  "mapfile_path": "<draconesph_location>/maps",

  "satscan_working_dir_path": "<draconesph_location>/satscan",
  "satscan_exe_path": "<satscan_batch_executable_path>",
  "satscan_process_timeout": 15,

  "map": {
      "srid": 32188,
      "postgis_connection": "dbname=draconesph host=localhost user=<pg_user>"
  }
  
}

where <satscan_batch_executable_path> should point to the batch version of the SaTScan executable (something like "/program files/satscan 8.1/satscanbatch.exe" on Windows). And finally, the map structure is a new Dracones feature allowing to specify a default connection string for the entire map (i.e. every MapServer layers composing it, for which there is no MapFile CONNECTION attribute defined). With this connection string you can specify your Postgres user (again, preferably a PG superuser, or at least the owner of the draconesph database). Also, please note that this string's host and password parameters are not necessarily mandatory, depending on your PG access setup.

After having restarted Apache (very important!) you should be able to test your installation by visiting:

http://<your_server>/draconesph

How was your installation process?

I'd like to get some feedback about the DraconesPH installation process: is it understandable, are some parts less clear? Was it a success, or a failure? If you feel like it, please drop me a line about it.