Installing and Running MapFishSample¶

Download MapFishSample¶

The MapFishSample application is available in the MapFish SVN repository. To install it you first need to check out its source code from SVN.

$ cd ~/mapfish_workshop
$ svn co http://svn.mapfish.org/svn/mapfish/sample/tags/2.2 MapFishSample

You can observe that the structure of MapFishSample is similar to that of the MyApp application that you created previously. MapFishSample is a MapFish application!

Yet, you should notice differences. Among other things, MapFishSample has a directory named buildout, which the MyApp application created earlier doesn’t have. This directory is where Buildout will set up the Python environment for the MapFishSample application.

Build and Deploy MapFishSample¶

Building and deploying MapFishSample is done using Buildout.

“Buildout is a Python-based build system for creating, assembling and deploying applications from multiple parts, some of which may be non-Python-based. It lets you create a buildout configuration and reproduce the same software later.”

To use Buildout a Buildout configuration file must be written. MapFishSample includes multiple Buildout configuration files: buildout.cfg contains the common part of the Buildout configuration, it is extended by other files, such as buildout_demo-mapfish-org.cfg, which include specificities.

[modwsgi]
recipe = collective.recipe.modwsgi
eggs = MapfishSample
config-file = ${buildout:directory}/production.ini

MapFishSample uses Buildout for multiple things:

1. Create an isolated Python environment, and install MapFishSample and its dependencies into it - the [eggs] part.
2. Adapt the application to the execution environment, i.e. the database, the location of Tomcat, etc. For that Buildout creates files from .in files, substituting variables as appropriate - the [template] part.
3. Download the MapFish Print webapp, bundle the application-specific print configuration and resources into it, and deploy it into Tomcat - the [print] and [deploy-print] parts.
4. Create a Python script to run MapFishSample in Apache modwsgi (production mode) - the [modwsgi] parts.
5. Build and compress the JavaScript code - the [jsbuild] part.
6. Build and compress the CSS code - the [cssbuild] part.
7. Build the language files for the internationalization (MapFishSample isn’t internationalized yet, but the i18n environment is in place) - the [po2mo] parts.

The first three items pertain to the deployment of MapFishSample, while the last three items pertain to the building of MapFishSample.

$ cd ~/mapfish_workshop/MapFishSample
$ python bootstrap.py --distribute --version 1.5.2

$ cp buildout_sample.cfg buildout_mine.cfg

$ ./buildout/bin/buildout -c buildout_mine.cfg

*************** PICKED VERSIONS ****************
[versions]

*************** /PICKED VERSIONS ***************

Run MapFishSample¶

For development or a quick test MapFishSample can be run in the Paste HTTP Server, which is installed by Buildout in the Python environment as a MapFish dependency.

$ ./buildout/bin/paster serve development.ini

$ ./buildout/bin/paster serve --reload development.ini

For production MapFishSample is run under Apache modwsgi. Using modwsgi has several advantages over using the Paste server:

• Performance - modwsgi is written in C and has a small overhead.
• Deployment ease - modwsgi can run on Linux and Windows, it is packaged in most Linux distributions, it runs in Apache so there’s no need for custom start/stop scripts.
• Robustness - modwsgi processes can run in isolation from the other Apache processes, and modwsgi processes are automatically restarted in cases of crashes.
• Great documentation and support.

Using modwsgi requires writing a so-called modwsgi script. The Buildout [modwsgi] part takes care of creating that script, it creates it in buildout/parts/modwsgi/wsgi.

Using modwsgi also requires adding modwsgi-specific directives to the Apache configuration. MapFishSample comes with a default Apache configuration. That configuration can be included from the main Apache configuration with a statement like this:

Include /home/user/mapfish_workshop/MapFishSample/apache/*.conf

Include /home/user/mapfish_workshop/MapFishSample/apache/*.conf

$ sudo /etc/init.d/apache2 reload

$ ps aux | grep wsgi
user     16152  0.0  3.5 248312 36288 ?        Sl   16:23   0:00 (wsgi:mapfishsamp -k start

Play with MapFishSample¶

MapFishSample has the following features:

• Query This is activated by pressing the info button in the toolbar. Once activated you can click and draw boxes to get information about POIs. Results are displayed in a popup window.
• Editing This is activated by pressing the editing button in the toolbar. Once activated you can create, modify and delete POIs.
• Search This is activated by pressing the search button in the toolbar. Once activated a search form is displayed, where you can enter criteria for a filtered search.
• Print This is activated by pressing the printing button in the toolbar. Once activated a form, a Print button, and a box on the map are displayed. Through the form and the box the user can control what will be printed. The box can be dragged, resized, and rotated.