Documentation

Installing Dracones (Python Version)

Please note that Dracones is now offered in Python and PHP flavors (both equivalent, in terms of services, and from the perspective of the JavaScript client, because they share a same interface). This document covers the installation and setup of the Python version.

Basic Components

The server part of Dracones relies on a number of open source software components:

MapServer: a geospatial/GIS platform that can be run as a CGI program on a web server
Apache: a web server through which MapServer is run
Python: the MapServer programming interface is called MapScript, and it has Python bindings

As is the case with the software bricks it relies on, Dracones is meant to be OS agnostic: it is being developed primarily on Windows, whereas the demo version accessible on the web runs on Linux. I assume it should work on OS X as well, with a reasonable amount of effort maybe, but I never tried it. From now on I will make the assumption that you are either using Windows (at least XP), or some Debian-like flavor of Linux (Ubuntu in most cases I guess). For Linux, I will also assume that you are performing the installation steps as root, or using sudo.

Since Dracones has no installer yet, you will have to follow these steps carefully, in a rather linear fashion. No step is in itself very difficult, and I tried to be very explicit for the ones that may require more attention.

Python

On both Windows and Linux, Python must be available. I've developped and tested with versions 2.5 and 2.6. For versions < 2.5, I don't know how it would behave, and for Python 3, the code would certainly require some changes.

Dracones is a WSGI application, and works through Pesto, an excellent and very well documented WSGI framework, that is most easily installed (Once Python and setuptools are installed) by doing:

$ easy_install pesto

Please note that it's important that Pesto version ≥ 13 is used, because it adds an important Session management option, that Dracones relies upon.

MapServer

One very good option for Windows is MS4W, a complete bundle, preconfigured with Apache and MapServer, as well as its MapScript multi-programming language bindings.

Once MS4W is installed, you have to manually install the Python-MapScript package, that can be found in the

<MS4W>\Apache\cgi-bin\mapscript\python

directory. Navigate in the zipped folders until you reach the .egg and Python files, and put them in your

<Python2X>\Lib\site-packages

folder, so that the mapscript module becomes accessible to Python.

On Linux it's even easier:

$ apt-get install php5-mapscript python-mapscript

Both packages are actually "leaves" in the MapServer dependency tree, that will cause many important packages to be installed: Apache, MapServer, etc. Although Dracones doesn't actually make any use of PHP5-MapScript, Python-MapScript by itself doesn't require Apache, so it's an easy way to have it installed and properly configured.

At this point, it would be a good thing to test that the Python-MapScript installation works. One way to do it is to simply do:

$ python
>>> import _mapscript

If you see a DLL-related problem (quite likely with the MS4W package), it's probably due to an incomplete PATH environment variable (not to be confused with the PYTHONPATH variable however), that must also include

<MS4W>\Apache\cgi-bin

as a source of mandatory DLL files.

mod_wsgi

Apache does not natively understand WSGI, so the mod_wsgi module is required. On Windows you can manually install the package available at http://code.google.com/p/modwsgi/. Once the module file is in place, you have to edit the main Apache config file to enable it. If you are using MS4W, this is:

<MS4W>/Apache/conf/httpd.conf

to which you must add this directive, with the proper module filename:

LoadModule rewrite_module modules/<wsgi_module_filename>.so

On Linux, again it's easier (no need to modify the Apache config, as it is done automatically):

$ apt-get install libapache2-mod-wsgi

Dracones Core

A Dracones application has two components: the core part, that is mainly the codebase you have downloaded, and the application part, that is yours to create, and of which you can have as many as you need. Each part is intended to run, from the web server's perpective, as a separate application/site, independently served. The core part has the job of serving the JavaScript content (the map widget that must be embedded in a web page), and also handling the Python AJAX requests that will send instructions on how to change the state of the application, as it's being used.

The core component must be installed first. Place first the Dracones codebase wherever you want.

Next, instruct Apache that you want to serve this codebase by copying the

<dracones_core_location>/apache/httpd_dracones_core_python.conf

file into the proper folder. On Windows using MS4W, that would be:

<MS4W>\httpd.d

On Linux, probably something like:

/etc/apache2/sites-available

Once this file is copied, edit it and change all the

<dracones_core_location>

for the right absolute path. On Linux, also uncomment the Alias directive in the same file:

Alias /ms_tmp /var/www/tmp/ms_tmp

and create the corresponding temporary location where MapServer will put the map image and session files:

$ mkdir /var/www/tmp
$ mkdir /var/www/tmp/ms_tmp
$ mkdir /var/www/tmp/pesto_tmp
$ chown -R www-data:www-data /var/www/tmp

On Windows, MS4W takes care of only half of that, as you still have to create the:

<MS4W>\tmp\pesto_tmp

location. And again on Linux, this must be followed by:

$ a2ensite httpd_dracones_core_python.conf

The core part of Dracones is now installed, but don't restart the web server yet, as we have more things to do.

Does it work? Hello World? Installing the test app

To verify that it works, we will use a test application, which is packaged with the Dracones codebase (in the test_app folder). As we did with the core component, we must instruct Apache to serve an additional codebase, this time for our test application. On Windows (with MS4W), this is done by copying the

<dracones_core_location>/apache/httpd_dracones_test_app.conf

file in the

<MS4W>\httpd.d

folder. On Linux, copy the same file in

/etc/apache2/sites-available

Once copied, edit it and change all the

<dracones_core_location>

for the right absolute path. Again on Linux, this must be followed by:

$ a2ensite httpd_dracones_test_app.conf

Two final steps are required before we are set: first the core component JSON configuration file

<dracones_core_location>/conf.json

must be edited. On Windows, it will look something like (note that the forward slashes and the missing drive prefix (if using C:) are ok with Python, even though we're in a Windows context):

{
  "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"]
}

Whereas on Linux it will be:

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

The first and third variables specify the place where the temporary map image files will be stored (by the server) and retrieved (by the client), whereas the second variable is the special folder in which Pesto stores its session files. The app_conf_filepaths list attribute is an important one to understand and remember: it must contain a pointer to the config file of all the Dracones applications that need to be taken into account. If a pointer to an application is not supplied, it will simply be ignored by Dracones. In our case, there's only one, the test app, and its conf.json file location must be specified duly, by changing the

<dracones_core_location>

for the right path value.

Thankfully, we have reached the final step.. We must edit the config file of the application itself:

<dracones_core_location>/test_app/conf.json

In both the Windows and Linux cases, this is an easy one:

{
  "app_name": "dracones_test_app",
  "mapfile_path": "<dracones_core_location>/test_app"
}

The mapfile_path attribute should of course point to the location where the application's mapfiles are stored.

Once all that is done, you can restart your web server, and use your browser to verify that the application is available at the address:

http://<your_server>/dracones_test_app

With the way Dracones performs error logging, it should be pretty clear what went wrong, if that's the case. One other very helpful source is the Apache error.log file. Also, one important potential pitfall to note are PYTHONPATH issues: the proper paths for the Python scripts are in the Dracones Core module Apache conf file (specified with the WSGIPythonPath directive), but if for some reason it does not work properly (in fact I know it does not for older versions of mod_wsgi), you may have to modify the PYTHONPATH environment variable manually, or specify the path explicitly in the scripts, by appending to the sys.path list.

How was your installation process?

I'd like to get some feedback about the Dracones 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.