.. _mapcache_install:

*****************************************************************************
Compilation & Installation
*****************************************************************************

:Author: Thomas Bonfort
:Contact: tbonfort at terriscope.fr
:Author: Alan Boudreault
:Contact: aboudreaut at magears.com
:Author: Jeff McKenna
:Contact: jmckenna at gatewaygeomatics.com

.. contents:: Table of Contents
    :depth: 3
    :backlinks: top

Getting the Source
==================

MapCache source is stored in the */mapserver/mapcache/* directory in :ref:`svn`.
You can visually browse the Subversion repository at http://trac.osgeo.org/mapserver/browser/trunk/mapserver/mapcache

Linux Instructions
==================

These instructions target a debian/ubuntu setup, but should apply with few
modifications to any linux installation.

MapCache requires a number of library headers in order to compile correctly:

- **apache / apr / apr-util / apx2**: these are included in the *apache2-prefork-dev* or
  *apache2-threaded-dev* packages, depending on what apache mpm you are running.
  This package will pull in the necessary apr headers, that you would have to
  manually install if you are not buidling an apache module (*libaprutil1-dev*
  and *libapr1-dev*)

- **png**: *libpng12-dev*
- **jpeg**: *libjpeg62-dev*
- **curl**: *libcurl4-gnutls-dev*

The following libraries are not required, but recommended:

- **pcre**: *libpcre3-dev*. This will give you more powerfull regular expression
  syntax when creating validation expressions for dimensions
- **pixman**: *libpixman-1-dev*. The pixel manipulation library is used for
  scaling and alpha-compositing images. MapCache ships with some code to
  perform these tasks, but pixman is generally faster as it includes
  code optimized for modern cpus (sse2, mmx, etc...)

The following libraries are not required, but needed to enable additional
functionalities:

- **fcgi**: *libfcgi-dev*. Needed to build a fastcgi program if you don't want to
  run mapcache as an apache module.
- **gdal / geos**: *libgdal1-dev* *libgeos-dev*. Needed to enable advanced seeding
  options (for only seeding tiles that intersect a given geographical feature)
- **sqlite**: *libsqlite3-dev*. For enabling the sqlite backend storages
- **tiff**: *libtiff4-dev*. For enabling the TIFF backend storages

For unix users where all packages are in the default locations, the compilation
process should resume to:

.. code-block:: bash

  $ ./configure
  $ make
  $ sudo make install

Apache Module Specific Instructions
-----------------------------------

The make install above installs the apache module, but if you need to
specifically need to install only the apache module you can do the following

.. code-block:: bash

  $ sudo make install-module
  $ sudo ldconfig

The installation script takes care of putting the built module in the apache
module directory.  The process for activating a module is usually distro
specific, but can be resumed by the following snippet that should be present in
the apache configuration file ( e.g. /usr/local/httpd/conf/httpd.conf or
/etc/apache2/sites-available/default ):

.. code-block:: apache

  LoadModule mapcache_module    modules/mod_mapcache.so

Next, a mapcache configuration is mapped to the server url with the following
snippet

.. code-block:: apache
   
   <IfModule mapcache_module>
      <Directory /path/to/directory>
         Order Allow,Deny
         Allow from all
      </Directory>
      MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
   </IfModule>

Finally, restart apache to take the modified configuration into account

.. code-block:: bash

   $ sudo apachectl restart

If you have not disabled the demo service, you should now have access to it on
http://myserver/mapcache/demo

Nginx Specific Instructions
----------------------------

.. warning:: Working with nginx is still highly experimental. The following workflow has only been tested on the development version of nginx-1.1.14

For nginx support you need to build mapcache's nginx module against the 
nginx source. Download the nginx source code:

.. code-block:: bash

   $ cd /usr/local/src
   $ mkdir nginx
   $ cd nginx
   $ wget http://nginx.org/download/nginx-1.1.14.tar.gz
   $ tar -xzvf nginx-1.1.14.tar.gz
   $ cd nginx-1.1.14/

Run the configure command with the flag\  ``--add-module`` \. This flag
must point to mapcache's nginx child directory. Assuming that 
mapserver trunk was checked out to\  ``/usr/local/src`` \, an example configure
command for nginx would look like this:

.. code-block:: bash

   $ ./configure --add-module=/usr/local/src/mapserver-trunk/mapcache/nginx

Then build nginx:

.. code-block:: bash

   $ make 
   $ sudo make install

Mapcache supplies a\  ``nginx.conf`` \in its nginx child directory. The conf 
contains an example configuration to load mapcache. The most relevant part of
the configuration is the location directive that points the\  ``mapcache`` \URI 
to the\  ``mapcache.xml`` \path. You will need to change this path to point to 
your own\  ``mapcache.xml`` \ in the mapcache source

.. code-block:: bash

	## BEFORE PATH EDIT
        location ~ ^/mapcache(?<path_info>/.*|$) {
           set $url_prefix "/mapcache";
           mapcache /home/tbonfort/dev/mapserver-trunk/mapcache/mapcache.xml;
        }

	## AFTER PATH EDIT
        location ~ ^/mapcache(?<path_info>/.*|$) {
           set $url_prefix "/mapcache";
           mapcache /usr/local/src/mapserver-trunk/mapcache/mapcache.xml;
        }

Now copy the\  ``nginx.conf`` \ from mapcache's nginx child directory into
nginx's conf directory (the nginx root directory in this case is \  ``/usr/local/nginx`` \) 

.. code-block:: bash

   $ sudo cp /usr/local/src/mapserver-trunk/mapcache/nginx/nginx.conf /usr/local/nginx/conf       

You should now have access to the demo. Notice the port number:  http://myserver:8083/mapcache/demo

CGI/FastCGI Specific Instructions
---------------------------------

A binary cgi/fastcgi is located in the src/ subfolder, and is named "mapcache".
Activating fastcgi for the mapcache program on your web server is not part of
these instructions, more details may be found on the :ref:`FastCGI <fastcgi>`
page or on more general web pages across the web.

The MapCache fastcgi program looks for it's configuration file in the environment
variable called MAPCACHE_CONFIG_FILE, which must be set by the web server before
spawning the mapcache processes.

.. seealso:: :ref:`mapcache_config`

.. $ sudo ln -s /usr/local/bin/mapcache /usr/lib/cgi-bin/mapcache

For apache with mod_cgi:


.. code-block:: apache

   SetEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapserver/mapcache/mapcache.xml"

For apache with mod_fcgid:

.. code-block:: apache

   FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapserver/mapcache/mapcache.xml

If you have not disabled the demo service, you should now have access to it on
http://myserver/fcgi-bin/mapcache/demo supposing your fcgi processes are accessed
under the fcgi-bin alias.

With a working mod_fcgid apache instance, the full httpd.conf snippet to activate
mapcache could be:

.. code-block:: apache

   <IfModule mod_fcgid.c>
      IPCCommTimeout 120
      MaxProcessCount 10
      FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/Users/tbonfort/dev/mapserver/mapcache/mapcache.xml"
      <Location /map.fcgi>
         Order Allow,Deny
         Allow from all
         SetHandler fcgid-script
      </Location>
      ScriptAlias /map.fcgi "/Users/tbonfort/dev/mapserver/mapcache/src/mapcache"
   </IfModule>

The mapcache service would then be accessible at http://myserver/map.fcgi[/demo]


Customizing the build, or if something went wrong
-------------------------------------------------

The configure script will try to locate dependant libraries in default system
locations, that can be overriden or specified with switches
(./configure --help should give you a full list).

Apache apxs
***********

.. code-block:: bash

   --with-apxs=/path/to/apxs

apxs is the apache extension tool that is used for building and installing the
module to a local apache instance. it should be installed along with a standard
apache build, or supplied by distros when installing the apache development
packages.  apxs is sometimes called apxs2 (notably on debian)



Apr
***

.. code-block:: bash

   --with-apr-config=/path/to/apr-config

apr-config is sometimes called apr-1-config on some systems. The path to the
apr libraries is usually determined from the previous apxs utility. you can
use this switch to override which apr will be used. beware that using a
different version of apr than the one that is linked to by apache will likely
cause bugs.



Apr-Util
********

.. code-block:: bash

   --with-apu-config=/path/to/apu-config

apu-config is sometimes called apu-1-config. 


Libcurl
*******

.. code-block:: bash

   --with-curl-config=/path/to/curl-config



Libpng
******

.. code-block:: bash

   --with-png=/path/to/png/prefix

this is the path where the libpng headers and libs can be located.  the
configure script will be looking for [path]/include/png.h and
[path]/lib/libpng.so



Libjpeg
*******

.. code-block:: bash

   --with-jpeg=/path/to/jpeg/prefix

this is the path where the libjpeg headers and libs can be located.  the
configure script will be looking for [path]/include/jpeg.h and
[path]/lib/libjpeg.so



Pixman (recommended)
********************

.. code-block:: bash

   --with-pixman=[yes|no|/path/to/pkgconfig/pixman.pc]

Pixman is a pixel manipulation library used to assemble image tiles when
responding to non-tiled wms requests. Pixman support is recommended as it is
highly optimized and will take advantage of recent processor extensions (mms,
sse, ...) to speed up blending and resampling operations. In case the pixman
library is not found, mod-mapcache will fall back to internal pixel operations
that are slower.



Sqlite (optional)
*****************

.. code-block:: bash

   --with-sqlite[=yes|no|/path/to/sqlite-prefix]

Sqlite is used to enable the sqlite and mbtiles cache backend. version 3.5.0 or
newer is required.
    
.. seealso:: :ref:`mapcache_cache_sqlite`



GDAL/OGR (optional, also requires geos)
***************************************

.. code-block:: bash

   --with-gdal[=yes|no|/path/to/gdal-config]

Gdal (actually ogr) is used by the seeding utility to allow the seeding of
tiles only intersecting a given polygon, e.g.  to preseed all the tiles of a
given country.



GEOS (optional)
***************

.. code-block:: bash

   --with-geos=/path/to/geos-config

Along with gdal/ogr, geos is needed by the seeder to test for the intersection
of tiles with geographical features. A sufficiently recent version of geos (with
support for prepared geometries) is required (but not enforced by the configure
script, so you'll end up with compilation errors if a too old geos version is
used)



PCRE (optional)
***************

.. code-block:: bash

   --with-pcre=/path/to/pcre-prefix

Pcre (perl compatible regular expressions) can be used instead of posix regular
expressions for validating WMS dimensions.  they are more powerfull than posix
REs (and might be slower). You don't need this if you aren't planning on using
WMS dimension support with regex validation, or if your validation needs are
covered by posix REs.

.. seealso:: :ref:`mapcache_dimensions` 



FastCGI Support (optional)
**************************

.. code-block:: bash

   --with-fastcgi=/path/to/fastcgi-prefix

MapCache can run as a fastcgi executable. Note that the overhead of fastcgi
is non-negligeable with respect to the throughput you may obtain with a native
apache module. The fastcgi build is less tested, and may lag behind
compared to the apache module version on some minor details, YMMV.



TIFF Readonly Cache Support (optional)
**************************************

.. code-block:: bash

   --with-tiff=/path/to/libtiff-prefix
    
.. seealso:: :ref:`mapcache_cache_tiff`


Debug Mode
**********

.. code-block:: bash

   --enable-debug

enables some extra tests inside the code, and prints out many more debugging
messages to the server logs. you should probably not enable this unless you
want to track down a problem happening inside MapCache.



Memcached Cache Support (optional)
**********************************

The memcached cache backend is enabled by default, as it does not depend on
other external libraries (support is obtained through apr-util). You can
optionally disable it if you have no need for it.

.. code-block:: bash

   --disable-memcache
    
.. seealso:: :ref:`mapcache_cache_memcache`

Apache Module Options
*********************

You can disable the apache module building if you only plan on using the
fastcgi executable or the seeder.

.. code-block:: bash

   --disable-module

MapCache adds itself to the version string reported by the apache server. This
can be disabled with

.. code-block:: bash

   --disable-version-string

Experimental options, use at your own risk
------------------------------------------

TIFF read/write Cache Support (optional)
****************************************

TIFF write support (for creating new TIFF files and adding tiles to existing
TIFF files) is still experimental and disabled by default. There is a risk in
ending up with corrupt TIFF files if they are placed on a filesystem that does
not honour file locking, as in that case multiple processes might end up writing
to the same file. File locking across concurrent threads is also problematic,
although MapCache tries to detect this situation and apply sufficient locking
workarounds. To stay on the safe side, write support should for now only be
enabled on local filesystems, with a prefork mpm or fastcgi MapCache install.


.. code-block:: bash

   --enable-tiff-write-support
    
.. seealso::
   :ref:`mapcache_cache_tiff`


When writing TIFF files, mapcache can also optionally add georeferencing
information if compiled with libtiff support. GeoTiff writing does not 
produce the full tags needed for defining which preojection the grid is
in, but will only produce those defining the pixel scale and the tiepoints
(i.e. the equivalent information found in the accompanying .tfw files)

.. code-block:: bash

   --enable-geotiff[=yes|no|/path/to/libgeotiffprefix]
    

Native MapServer Mode
*********************

MapCache is by default not linked to MapServer in any way, and communicates 
through the WMS protocol only. For performance reasons, there is a possibility
to directly use the mapserver C library and avoid an http request and an image
compression/decompression. This integration is highly experimental and should
not be enabled for general use.


.. code-block:: bash

   --enable-mapserver

This will use the libmapserver.a from MapCache's parent directory. MapServer
itself should be compiled with thread-safety enabled, unless you plan use the
prefork mpm or fastcgi, **and** you do not plan to use the seeder. For thread
safety on the mapserver side, you might want to have a look at tickets #4041 and
#4044.

Windows Instructions
====================

These instructions target a Windows 7 setup with an Apache httpd compiled from 
source. The Apache MapCache module has been successfully built with with 
Microsoft Visual Studio C++ versions 2003, 2008 and 2010.

Dependencies
------------

Required:

- **Apache / APR / APR-UTIL**: included with apache httpd installation

Those can be installed manually, or using the appropriate Windows SDK
from: http://vbkto.dyndns.org/sdk/

- **PNG** 
- **JPEG** 
- **CURL**

Recommended:

- **PCRE**: ftp://ftp.gnu.org/pub/gnu/regex/regex-0.12.tar.gz

Optional:

- **FCGI**: Needed to build a fastcgi program if you don't want to run
  mapcache as an apache module.
- **GDAL / GEOS**: Needed to enable advanced seeding options (for only
  seeding tiles that intersect a given geographical feature)
- **SQLITE**: For enabling the sqlite backend storages
- **TIFF**: For enabling the TIFF backend storages

Configure Your Makefile
-----------------------

Open nmake.opt and modify the paths to point to the various libraries.

Compilation
-----------

.. code-block:: bash

  $ nmake /f Makefile.vc

If successful, the resulting libraries and executables will be generated in their associated
directories:

apache/
  Apache module (mod_mapcache.dll)

cgi/
  FastCGI MapCache executable (mapcache.exe)
  
util/
  MapCache utilities (mapcache_seed.exe)
  
Move the Module into Apache Directory
-------------------------------------

Copy the *mod_mapcache.dll* file into one of your Apache subdirectories.

.. note::
    Although other modules are installed into */Apache/modules/*, you should place
    mod_mapcache.dll wherever its required dll files (libcurl.dll, zlib.dll, etc.) live,
    to avoid any loading issues later on.

Configure Your Installed Apache
-------------------------------

- Modify your *httpd.conf* file to load the module:

  .. code-block:: apache

    LoadModule mapcache_module "D:/ms4w/Apache/cgi-bin/mod_mapcache.dll"

- Next, configure your mapcache directory with the following
  snippet

  .. code-block:: apache
   
     <IfModule mapcache_module>
        <Directory "D:/ms4w/apps/mapcache/">
           Order Allow,Deny
           Allow from all
        </Directory>
        MapCacheAlias /mapcache "D:/ms4w/apps/mapcache/mapcache.xml"
     </IfModule>
     
- Configure your *mapcache.xml* file (see the :ref:`Configuration <mapcache_config>` section
  for help)
  
.. warning::
    If you receive an error such as "cache disk: host system does not support file symbolic linking"
    you should comment the line "<symlink_blank/>" in your mapcache.xml file, such as:
    
    .. code-block:: bash
    
       <cache name="disk" type="disk">
         <base>D:/ms4w/tmp/ms_tmp/cache</base>
         <!--<symlink_blank/>-->
       </cache>

- Finally, restart your Apache.  You should see a message in Apache's error.log with a message
  similar to:
  
  .. code-block:: bash
  
    [notice] Apache/2.2.21 (Win32) mod-mapcache/0.5-dev configured -- resuming normal operations

Test Your MapCache Module
-------------------------

- In your web browser, goto the local MapCache demo page: http://127.0.0.1/mapcache/demo/ You should see 
  a clickable list of demo links:
  
  ::
   
    tms
    wmts
    gmaps
    kml
    ve
    wms

- Click on one of the demos (such as http://127.0.0.1/mapcache/demo/wmts), a map viewer should load, similar
  to the image below.
  
  .. image:: ../images/mapcache-demo.jpg
     :height: 600px
     :width: 900 px
     
- Zoom in a few times, and your configured cache location should be generating tiles (in this case inside 
  D:/ms4w/tmp/ms_tmp/cache/).
  
  .. image:: ../images/mapcache-disk.jpg