|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| Author: | Thomas Bonfort |
|---|---|
| Contact: | tbonfort at terriscope.fr |
| Author: | Alan Boudreault |
| Contact: | aboudreaut at magears.com |
| Author: | Jeff McKenna |
| Contact: | jmckenna at gatewaygeomatics.com |
Table of Contents
The MapCache project is located at https://github.com/mapserver/mapcache, and can be checked out with either:
# readonly
git clone git://github.com/mapserver/mapcache.git
# ssh authenticated
git clone git@github.com:mapserver/mapcache.git
# tarball
wget https://github.com/mapserver/mapcache/zipball/master
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:
The following libraries are not required, but recommended:
The following libraries are not required, but needed to enable additional functionalities:
For unix users where all packages are in the default locations, the compilation process should resume to:
$ ./configure
$ make
$ sudo make install
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
$ 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 ):
LoadModule mapcache_module modules/mod_mapcache.so
Next, a mapcache configuration is mapped to the server url with the following snippet
For apache < 2.4:
<IfModule mapcache_module>
<Directory /path/to/directory>
Order Allow,Deny
Allow from all
</Directory>
MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
</IfModule>
For apache >= 2.4:
<IfModule mapcache_module>
<Directory /path/to/directory>
Require all granted
</Directory>
MapCacheAlias /mapcache "/path/to/directory/mapcache.xml"
</IfModule>
Finally, restart apache to take the modified configuration into account
$ sudo apachectl restart
If you have not disabled the demo service, you should now have access to it on http://myserver/mapcache/demo
Warning
Working with nginx is still somewhat experimental. The following workflow has only been tested on the development version, i.e. nginx-1.1.x
For nginx support you need to build mapcache’s nginx module against the nginx source. Download the nginx source code:
$ cd /usr/local/src
$ mkdir nginx
$ cd nginx
$ wget http://nginx.org/download/nginx-1.1.19.tar.gz
$ tar -xzvf nginx-1.1.19.tar.gz
$ cd nginx-1.1.19/
Run the configure command with the flag --add-module. This flag must point to mapcache’s nginx child directory. Assuming that mapserver source was cloned or un tarred into to /usr/local/src, an example configure command for nginx would look like this:
$ ./configure --add-module=/usr/local/src/mapcache/nginx
Then build nginx:
$ make
$ sudo make install
Due to nginx’s non-blocking architecture, the mapcache nginx module does not perform any operations that may lead to a worker process being blocked by a long computation (i.e.: requesting a (meta)tile to be rendered if not in the cache, proxying a request to an upstream wms server, or waiting for a tile to be rendered by another worker), it will instead issue a 404 error. This behavior is essential so as not to occupy all nginx worker threads, therefore preventing it from responding to all other incoming requests. While this isn’t an issue for completely seeded tilesets, this implies that these kinds of requests need to be proxied to another mapcache instance that does not suffer from these starvation issues (i.e. either a fastcgi mapcache, or an internal proxied apache server). In this scenario, both the nginx mapcache instance and the apache/fastcgi mapcache instance should be running with the same mapcache.xml configuration file.
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
The basic configuration without any proxying (which will return 404 errors on unseeded tile requests) is:
location ~ ^/mapcache(?<path_info>/.*|$) {
set $url_prefix "/mapcache";
mapcache /usr/local/src/mapcache/mapcache.xml;
}
If proxying unseeded tile requests to a mapcache instance running on an apache server, we will proxy all 404 mapcache errors to a mapcache.apache.tld server listening on port 8080, configured to respond to mapcache requests on the /mapcache location.
location ~ ^/mapcache(?<path_info>/.*|$) {
set $url_prefix "/mapcache";
mapcache /usr/local/src/mapcache/mapcache.xml;
error_page 404 = @apache_mapcache;
}
location @apache_mapcache {
proxy_pass http://mapcache.apache.tld:8080;
}
If using fastcgi instances of mapcache, spawned with e.g. spawn-fcgi or supervisord on port 9001 (make sure to enable fastcgi when building mapcache, and to set the MAPCACHE_CONFIG_FILE environment variable before spawning):
location ~ ^/mapcache(?<path_info>/.*|$) {
set $url_prefix "/mapcache";
mapcache /usr/local/src/mapcache/mapcache.xml;
error_page 404 = @fastcgi_mapcache;
}
location @fastcgi_mapcache {
fastcgi_pass localhost:9001;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param PATH_INFO $path_info;
fastcgi_param SERVER_NAME $server_name;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SCRIPT_NAME "/mapcache";
}
Copy the relevant sections of nginx.conf from mapcache’s nginx directory into nginx’s conf file (in this case /usr/local/nginx/conf/nginx.conf) , you should now have access to the demo at http://myserver/mapcache/demo
Warning
Fastcgi support is not built in by default, you must explicitely enable it at compile time, see FastCGI
A binary cgi/fastcgi is located in the mapcache/ 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 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.
See also
For apache with mod_cgi:
SetEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml"
For apache with mod_fcgid:
FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/path/to/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:
<IfModule mod_fcgid.c>
IPCCommTimeout 120
MaxProcessCount 10
FcgidInitialEnv "MAPCACHE_CONFIG_FILE" "/path/to/mapcache/mapcache.xml"
<Location /map.fcgi>
Order Allow,Deny
Allow from all
SetHandler fcgid-script
</Location>
ScriptAlias /map.fcgi "/path/to/mapcache/src/mapcache"
</IfModule>
The mapcache service would then be accessible at http://myserver/map.fcgi[/demo]
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).
--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)
--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.
--with-curl-config=/path/to/curl-config
--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
--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
--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.
--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.
See also
--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.
--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)
--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.
See also
--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.
--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.
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.
--disable-memcache
See also
You can disable the apache module building if you only plan on using the fastcgi executable or the seeder.
--disable-module
MapCache adds itself to the version string reported by the apache server. This can be disabled with
--disable-version-string
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.
--enable-tiff-write-support
See also
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)
--enable-geotiff[=yes|no|/path/to/libgeotiffprefix]
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 still experimental and should be used cautiously
--enable-mapserver=/path/to/mapserver-srcdir
This will use the libmapserver.so from mapserver’s install 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.
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.
Required:
Those can be installed manually, or using the appropriate Windows SDK from: http://vbkto.dyndns.org/sdk/
Recommended:
Optional:
Open nmake.opt and modify the paths to point to the various libraries.
$ nmake /f Makefile.vc
If successful, the resulting libraries and executables will be generated in their associated directories:
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.
Modify your httpd.conf file to load the module:
LoadModule mapcache_module "D:/ms4w/Apache/cgi-bin/mod_mapcache.dll"
Next, configure your mapcache directory with the following snippet
<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 Configuration 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:
<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:
[notice] Apache/2.2.21 (Win32) mod-mapcache/0.5-dev configured -- resuming normal operations
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.
Zoom in a few times, and your configured cache location should be generating tiles (in this case inside D:/ms4w/tmp/ms_tmp/cache/).
