From OpenStreetMap Wiki
Jump to navigation Jump to search

mod_mapnik_wms is an Apache module for building a Mapnik based WMS server. It was initially written by Frederik Ramm for internal Geofabrik use, but now is available under the GPL from Github geofabrik/mod_mapnik_wms.

What is WMS?

WMS (Web Map Service) is an OGC standard for serving maps. Essentially, it specifies a set of HTTP URL parameters used by a client to retrieve a map image from a server.

Compared to the usual tile servers we use in OSM, a WMS offers more flexibility but eats more server resources. You can think of it like this: a tile server is like buying off-the-shelf clothing at H&M. Your choices are limited by what has been produced before you ever entered the shop; but it is cheap and efficient. A WMS, on the other hand, is like tailor-made clothing. You can request anything within a broad range of options, and what you get is made to your specifications. This gives a nicer fit but costs much more.

So if you want to clothe the masses (offer a fast slippy map for a lot of users), you should use a tile server. If you want to server a small number of users with custom maps, use a WMS.

More on the WMS page

What is mod_mapnik_wms?

mod_mapnik_wms is a module for the widely-used Apache web server that speaks the WMS protocol. In fact the WMS standard is a bit convoluted and has many extensions and optional extras, but mod_mapnik_wms currently only supports the bare minimum: The GetCapabilities call which tells the client what this server can do, and the GetMap call which produces a map. For rendering the map, mod_mapnik_wms uses the Mapnik library.

Building mod_mapnik_wms

To build mod_mapnik_wms, you need to have the following installed:

  • Mapnik
  • Apache2 development package (apache2-prefork-dev)
  • libgd2 development package
  • possibly a libdb development package (if you use the key database described later)

You should be able to build a Debian package by just running "debuild", but you can also choose to run "make". If you run "make" as root, Apache's apxs2 will install the module right away.

You may have to adjust some Mapnik version numbers (grep -i mapnik debian/*).

Installing and Configuring mod_mapnik_wms

Before you install mod_mapnik_wms, make sure to have a working Mapnik installation, including the style sheet you want to use, with the database connection and shape files properly set up and configured. Test that with from the OSM Mapnik package, or with Do not continue with mod_mapnik_wms installation if you are unsure whether your Mapnik installation works at all.

Your Apache configuration must be modified to load the new module. If you install the module per Debian package, that should be done automatically. Otherwise you will have to place the commands

LoadFile /usr/lib/
LoadFile /usr/lib/
LoadFile /usr/lib/
LoadFile /usr/lib/
LoadModule mapnik_wms_module /usr/lib/apache2/modules/

somewhere in your Apache config. The library version numbers may have to be changed depending on what's available on your system (which is hopefully the same you had on the build system).

Then you must configure the WMS module. This is done through Apache configuration directives, usually in the virtual host's config file in your /etc/apache/sites_available directory. An example configuration is provided in server_config.example.

The mod_mapnik_wms-specific configuration options are:

Option Default Use
WmsSrs none A list of allowed SRS names, separated by spaces. They must be supported by the underlying Mapnik installation.

You will usually want to have at least EPSG:4326 in that list.

MapnikDatasources none (required) Path to Mapnik data source modules (plugins), usually /usr/lib/mapnik/input. May occur more than once.
MapnikFonts none (required) Path to ttf font used in map files. May occur more than once.
MapnikMap none (required) Path to the map file. Currently only one is supported.
WmsTitle empty WMS server title you want to return for GetCapability requests.
WmsTopLayerTitle OpenStreetMap WMS WMS top layer title.
WmsTopLayerName OpenStreetMap WMS WMS top layer name.
WmsIncludeSubLayers false Expose individual Mapnik layers to WMS client. This is currently commented

out in the code because Mapnik layers are really not adequate for selecting individually.

WmsDebug false If true, the map file will be loaded for each request instead of once at startup

which makes fiddling with the style easier.

MapnikLog none File to redirect the "clog" stream to.
WmsUrl empty The URL under which your WMS server can be reached from the outside. It is used in

constructing the GetCapabilities response. Note that clients will use this URL to access the WMS service even if they have retrieved the capabilities document through another channel, e.g. if you have a port forwarding set up and have your client connect to localhost:1234 to retrieve the capabilities document, it will only use localhost:1234 for the map request if this is actually specified in the WmsUrl.

WmsKeyDb empty Path the the key database (see below). Only available if compiled with USE_KEY_DATABASE.

If empty, no key checking will be done.

WmsMaxDemoWidth unset Maximum image width for "demo" class requests. Only available if compiled with USE_KEY_DATABASE.

Demo requests use standard limits if unset.

WmsMaxDemoHeight unset Maximum image height for "demo" class requests. Only available if compiled with USE_KEY_DATABASE.

Demo requests use standard limits if unset.



-179.9999, -89.999, 179.9999, 89.999 The data bounding box to be published in the capabilities document


WMS supports layers. The server can announce to the client which layers it supports, and the client can make a selection from them. In theory, this module can publish the individual Mapnik layers to the client, and the client can select which ones it wants. In practice this makes little sense as Mapnik layers are not really made for separate use.

Key Database

This module is used by Geofabrik to serve WMS content to paying customers. Since not all WMS clients support HTTP authentication, we embed a customer specific hash key in the URL (http://servername/maptype/hashkey?...). The module checks whether the given key is in the database and disallows access otherwise.

You can enable this mechanism if you set USE_KEY_DATABASE when compiling mod_mapnik_wms. There's a small utility that creates the required databas files from a CSV file in the keydb directory.


You should be able to test your server with any WMS client, e.g. OpenLayers or Quantum GIS. However, a simple check can be performed directly in the browser:


This should bring up a small map image with Europe and Northern Africa in view.