IMPORTANT: This file is out-of-date.
Please refer to doc/install.en.html for MapIt! installation


Installation
============

A more user friendly installation is being prepared. Until then the
installation has to be done manually, but that shouldn't be too
difficult.


Overview
--------

A MapIt! installation consists of three parts: the CGI-code, the data
(raster maps, HTML-templates and markers) and the icons that are needed
by the generated HTML code.

Where the CGI-code and the icons have to be installed on your system
depends on your web-server configuration. The data files can be
installed anywhere (preferably outside of the public directory tree of
your web-server), you only have to modify the configuration file
accordingly.


Generic Installation Steps
--------------------------

Even though there are a variety of ways to hook MapIt! into your
web-server such as CGI, Fast-CGI or mod_python, all front-ends share
some installation and configuration steps which are described in this
section. The front-end specific instructions are in the relevant
sections below.

 1. Install the Sources

    Copy the sources to a suitable place. The sources are split into the
    base code (src/base) and the front-end code (src/frontends). The
    base code is needed by all front-ends, but you only need some of the
    files in src/frontend depending on the front end you want to use:

	Frontend	Files in src/frontends
	--------------------------------------
	CGI		showmap
			genmap

	FastCGI		showmap.cgi
			showmap.fcgi
			showmap.py
			genmap.cgi
			genmap.fcgi
			genmap.py
			fcgi.py

	mod_python	showmap.py
			genmap.py
			modmapit.py
    
    Where to put these files is described in the front-end specific
    sections.

    You can put the base files and the frontend files into the same
    directory (the easiest solution) or you can leave them in different
    directories. In the latter case you have to make sure that the
    front-end files can find the base files.


 2. Install the Data Files

 2.1 Install the Tile Data

    Copy the files from examples/simple except this icons/
    subdirectory into a suitable directory while preserving the
    directory structure of the sub-directories. On our system that's
    .../www-adm/tools/mapit/simple

 2.2 Install the Icons

    Copy the files in examples/simple/icons/ into a suitable
    directory for your web-server. For example, on our system it's
    .../www-adm/www/public/mapit/simple/Icons

    The HTML generated by MapIt! refers to the icons with URLs of the
    form "/simple/Icons/image.png" by default. Please make sure that the
    icons can be reached by these URLs or modify the template files
    accordingly.


 3 Configure MapIt!

 3.1 Adapt mapconfig.py

    Modify the configuration file mapconfig.py for your system. The most
    important entry that will have to be changed is the variable
    _base_dir, which points to the directory where you installed the data
    files.

    If you use Windows, please note, that if you use backslashes (\) as
    directory delimiter, you have to double them, so that e.g.
    "C:\Programme\Mapit" becomes "C:\\Programme\\Mapit". However, it's
    easier to just use forward slashes (/) as delimiters.

    Another Windows specific problem may be that some files use the
    Unix line ending conventions which Notepad does not understand.
    You can use Wordpad instead, but be sure to save the files as
    text files.

 3.2 Adapt the HTML-Template

    If necessary, adapt the HTML-template (examples/simple/simple.template
    (in the mapit archive)) to your needs. The most typical change
    are the links to the icons. A short explanation of the <mapit:> tags
    can be found in src/base/pagetemplate.py.



Installing MapIt! as CGI Script
-------------------------------

The MapIt! front-end scripts for CGI, showmap and genmap, have to be put
into a directory that is configured for CGI in your web-server. For
example, on our system it's .../www-adm/cgi-bin/mapit/simple

Under Unix and under Windows if you use Apache you may have to modify
the first line of the scripts to point to your python interpreter. For
instance, on our NT-installation the looks like:

#!c:\programme\python\python -u -O

The -u flag under windows is important for the genmap script because it
writes binary data to stdout.


Installing MapIt! as Fast CGI Script
------------------------------------

At the moment this solution only works on Unix. A simple way to get FCGI
to work with most servers is through the fcgi-cgi program from the
devkit available at http://www.fastcgi.com. The .cgi versions of showmap
and genmap are normal CGI scripts that use fcgi-cgi as interpreter and
contain commands that invoke and connect to the workhorses showmap.fcgi
and genmap.fcgi. To make this work on your system you will probably have
to modify the paths in the .cgi files to your needs.



Installing MapIt! with mod_python
---------------------------------

mod_python is a module for the Apache web-server available from
http://www.modpython.org/. This is obviously an Apache only solution.
The examples here come from a Windows NT installation, but it works just
the same under Unix.

Copy the source files into a suitable directory, e.g. on our NT system
that's C:/Programme/Apache Group/Apache/cgi-bin/mapit/, and configure
this directory as follows in Apache's http.conf:

<Directory "C:/Programme/Apache Group/Apache/cgi-bin/mapit/">
	SetHandler python-program
	PythonHandler modmapit
	PythonDebug on
</Directory>

This tells Apache to call the handler function in modmapit for *all*
URIs in that directory. modmapit knows how to recognize "showmap" and
"genmap" in the URL and call the appropriate functions.

If you want, you can specify an alias for this directory with something
like:

ScriptAlias /mapit-scripts/ "C:/Programme/Apache Group/Apache/cgi-bin/mapit/"

Now the URL http://localhost/mapit-scripts/showmap should display the
HTML-page with the map.
