Documentation

Installing Dracones (PHP Version)

This document covers the installation of the new set of PHP alternative components, introduced in version 1.1. It is easier than the Python installation, as it relies on much less external components and is less painful to debug.

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

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.

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. Please note that whereas Dracones-Python is more flexible, Dracones-PHP requires MapServer ≥ 5.6.

If you are using MS4W, PHP-MapScript is already installed. If you use Linux, it's very easy to install however:

$ apt-get install php5-mapscript

This package is actually a "leaf" in the MapServer dependency tree, that will cause many important packages to be installed: Apache, MapServer, etc.

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 PHP 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_php.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:

$ mkdir /var/www/tmp
$ mkdir /var/www/tmp/ms_tmp
$ chown -R www-data:www-data /var/www/tmp
$ a2ensite httpd_dracones_core_php.conf

Please note that this Apache config file makes use of a RewriteRule to provide a unified interface with the Python version of Dracones. You therefore have to make sure that the mod_rewrite module is properly loaded. If you are using MS4W, edit the main Apache config file:

<MS4W>/Apache/conf/httpd.conf

and make sure that this directive is not commented out:

LoadModule rewrite_module modules/mod_rewrite.so

On Linux, use instead:

$ a2enmod rewrite

You must also give PHP an include path for the source files. Since PHP-MapScript runs as a CGI (and not as a module: trying to do this in a Directory directive will not work) this must be done in the php.ini file. If you are using MS4W, this file can be found there:

<MS4W>/Apache/cgi-bin/

Update the path, for instance:

include_path = ".;\ms4w\Apache\php;<dracones_core_location>"

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 PHP, even though we're in a Windows context):

{
  "ms_tmp_path": "/ms4w/tmp/ms_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/",
  "ms_tmp_url": "/ms_tmp",
  "app_conf_filepaths": ["<dracones_core_location>/test_app/conf.json"]
}

The first and second variables specify the place where the temporary map image files will be stored (by the server) and retrieved (by the client). Note that you can ignore the session_path variable found in the config file, as it is not used with the PHP version of Dracones. 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.

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.