source: subversion/applications/utils/mod_mapnik_wms/README

Last change on this file was 22443, checked in by frederik, 9 years ago

mod_mapnik_wms keydb and new readme

File size: 13.6 KB
Line 
1Mod mapnik wms README
2---------------------
3
4(created from http://wiki.openstreetmap.org/wiki/Mod_mapnik_wms - see that
5page for a potentially more current version)
6
7Overview
8
9   mod_mapnik_wms is an Apache module for building a Mapnik based WMS server.
10   It was initially written by Frederik Ramm for internal Geofabrik use, but
11   now is available under the GPL from the OpenStreetMap SVN
12   (applications/utils/mod_mapnik_wms).
13
14   Contents                                         
15                                                     
16     * 1 What is WMS?                               
17     * 2 What is mod_mapnik_wms?                     
18     * 3 Building mod_mapnik_wms                     
19     * 4 Installing and Configuring mod_mapnik_wms   
20     * 5 Layers                                     
21     * 6 Key Database                               
22     * 7 Testing                                     
23
24What is WMS?
25
26   WMS (Web Map Service) is an OGC standard for serving maps. Essentially, it
27   specifies a set of HTTP URL parameters used by a client to retrieve a map
28   image from a server.
29
30   Compared to the usual tile servers we use in OSM, a WMS offers more
31   flexibility but eats more server resources. You can think of it like this:
32   a tile server is like buying off-the-shelf clothing at H&M. Your choices
33   are limited by what has been produced before you ever entered the shop;
34   but it is cheap and efficient. A WMS, on the other hand, is like
35   tailor-made clothing. You can request anything within a broad range of
36   options, and what you get is made to your specifications. This gives a
37   nicer fit but costs much more.
38
39   So if you want to clothe the masses (offer a fast slippy map for a lot of
40   users), you should use a tile server. If you want to server a small number
41   of users with custom maps, use a WMS.
42
43What is mod_mapnik_wms?
44
45   mod_mapnik_wms is a module for the widely-used Apache web server that
46   speaks the WMS protocol. In fact the WMS standard is a bit convoluted and
47   has many extensions and optional extras, but mot_mapnik_wms currently only
48   supports the bare minimum: The GetCapabilities call which tells the client
49   what this server can do, and the GetMap call which produces a map. For
50   rendering the map, mod_mapnik_wms uses the Mapnik library.
51
52Building mod_mapnik_wms
53
54   To build mod_mapnik_wms, you need to have the following installed:
55
56     * Mapnik
57     * Apache2 development package (apache2-prefork-dev)
58     * libgd2 development package
59     * possibly a libdb development package (if you use the key database
60       described later)
61
62   You should be able to build a Debian package by just running "debuild",
63   but you can also choose to run "make". If you run "make" as root, Apache's
64   apxs2 will install the module right away.
65
66   You may have to adjust some Mapnik version numbers (grep -i mapnk
67   debian/*).
68
69Installing and Configuring mod_mapnik_wms
70
71   Before you install mod_mapnik_wms, make sure to have a working Mapnik
72   installation, including the style sheet you want to use, with the database
73   connection and shape files properly set up and configured. Test that with
74   generate_image.py from the OSM Mapnik package, or with nik2img.py. Do not
75   continue with mod_mapnik_wms installation if you are unsure whether your
76   Mapnik installation works at all.
77
78   Your Apache configuration must be modified to load the new module. If you
79   install the module per Debian package, that should be done automatically.
80   Otherwise you will have to place the commands
81
82 LoadFile /usr/lib/libstdc++.so.6
83 LoadFile /usr/lib/libmapnik.so.0.6
84 LoadFile /usr/lib/libgd.so.2
85 LoadFile /usr/lib/libdb-4.6.so
86 LoadModule mapnik_wms_module /usr/lib/apache2/modules/mod_mapnik_wms.so
87
88   somewhere in your Apache config. The library version numbers may have to
89   be changed depending on what's available on your system (which is
90   hopefully the same you had on the build system).
91
92   Then you must configure the WMS module. This is done through Apache
93   configuration directives, usually in the virtual host's config file in
94   your /etc/apache/sites_available directory. An example configuration is
95   provided in server_config.example.
96
97   The mod_mapnik_wms-specific configuration options are:
98
99   +------------------------------------------------------------------------+
100   |       Option        |     Default      |              Use              |
101   |---------------------+------------------+-------------------------------|
102   |                     |                  | A list of allowed SRS names,  |
103   |                     |                  | separated by spaces. They     |
104   |                     |                  | must be supported by the      |
105   |                     |                  | underlying Mapnik             |
106   | WmsSrs              | none             | installation.                 |
107   |                     |                  |                               |
108   |                     |                  | You will usually want to have |
109   |                     |                  | at least EPSG:4326 in that    |
110   |                     |                  | list.                         |
111   |---------------------+------------------+-------------------------------|
112   |                     |                  | Path to Mapnik data source    |
113   | MapnikDatasources   | none (required)  | modules (plugins), usually    |
114   |                     |                  | /usr/lib/mapnik/input. May    |
115   |                     |                  | occur more than once.         |
116   |---------------------+------------------+-------------------------------|
117   |                     |                  | Path to ttf font used in map  |
118   | MapnikFonts         | none (required)  | files. May occur more than    |
119   |                     |                  | once.                         |
120   |---------------------+------------------+-------------------------------|
121   |                     |                  | Path to the map file.         |
122   | MapnikMap           | none (required)  | Currently only one is         |
123   |                     |                  | supported.                    |
124   |---------------------+------------------+-------------------------------|
125   |                     |                  | WMS server title you want to  |
126   | WmsTitle            | empty            | return for GetCapability      |
127   |                     |                  | requests.                     |
128   |---------------------+------------------+-------------------------------|
129   | WmsTopLayerTitle    | OpenStreetMap    | WMS top layer title.          |
130   |                     | WMS              |                               |
131   |---------------------+------------------+-------------------------------|
132   | WmsTopLayerName     | OpenStreetMap    | WMS top layer name.           |
133   |                     | WMS              |                               |
134   |---------------------+------------------+-------------------------------|
135   |                     |                  | Expose individual Mapnik      |
136   |                     |                  | layers to WMS client. This is |
137   |                     |                  | currently commented           |
138   | WmsIncludeSubLayers | false            |                               |
139   |                     |                  | out in the code because       |
140   |                     |                  | Mapnik layers are really not  |
141   |                     |                  | adequate for selecting        |
142   |                     |                  | individually.                 |
143   |---------------------+------------------+-------------------------------|
144   |                     |                  | If true, the map file will be |
145   |                     |                  | loaded for each request       |
146   | WmsDebug            | false            | instead of once at startup    |
147   |                     |                  |                               |
148   |                     |                  | which makes fiddling with the |
149   |                     |                  | style easier.                 |
150   |---------------------+------------------+-------------------------------|
151   | MapnikLog           | none             | File to redirect the "clog"   |
152   |                     |                  | stream to.                    |
153   |---------------------+------------------+-------------------------------|
154   |                     |                  | The URL under which your WMS  |
155   |                     |                  | server can be reached from    |
156   |                     |                  | the outside. It is used in    |
157   |                     |                  |                               |
158   |                     |                  | constructing the              |
159   |                     |                  | GetCapabilities response.     |
160   |                     |                  | Note that clients will use    |
161   |                     |                  | this URL to access the WMS    |
162   |                     |                  | service even if they have     |
163   | WmsUrl              | empty            | retrieved the capabilities    |
164   |                     |                  | document through another      |
165   |                     |                  | channel, e.g. if you have a   |
166   |                     |                  | port forwarding set up and    |
167   |                     |                  | have your client connect to   |
168   |                     |                  | localhost:1234 to retrieve    |
169   |                     |                  | the capabilities document, it |
170   |                     |                  | will only use localhost:1234  |
171   |                     |                  | for the map request if this   |
172   |                     |                  | is actually specified in the  |
173   |                     |                  | WmsUrl.                       |
174   |---------------------+------------------+-------------------------------|
175   |                     |                  | Path the the key database     |
176   |                     |                  | (see below). Only available   |
177   |                     |                  | if compiled with              |
178   | WmsKeyDb            | empty            | USE_KEY_DATABASE.             |
179   |                     |                  |                               |
180   |                     |                  | If empty, no key checking     |
181   |                     |                  | will be done.                 |
182   |---------------------+------------------+-------------------------------|
183   |                     |                  | Maximum image width for       |
184   |                     |                  | "demo" class requests. Only   |
185   |                     |                  | available if compiled with    |
186   | WmsMaxDemoWidth     | unset            | USE_KEY_DATABASE.             |
187   |                     |                  |                               |
188   |                     |                  | Demo requests use standard    |
189   |                     |                  | limits if unset.              |
190   |---------------------+------------------+-------------------------------|
191   |                     |                  | Maximum image height for      |
192   |                     |                  | "demo" class requests. Only   |
193   |                     |                  | available if compiled with    |
194   | WmsMaxDemoHeight    | unset            | USE_KEY_DATABASE.             |
195   |                     |                  |                               |
196   |                     |                  | Demo requests use standard    |
197   |                     |                  | limits if unset.              |
198   |---------------------+------------------+-------------------------------|
199   | WmsExtentMinLon,    |                  |                               |
200   |                     | -179.9999,       | The data bounding box to be   |
201   | WmsExtentMaxLon,    | -89.999,         | published in the capabilities |
202   | WmsExtentMinLat,    | 179.9999, 89.999 | document                      |
203   | WmsExtentMaxLat     |                  |                               |
204   +------------------------------------------------------------------------+
205
206Layers
207
208   WMS supports layers. The server can announce to the client which layers it
209   supports, and the client can make a selection from them. In theory, this
210   module can publish the individual Mapnik layers to the client, and the
211   client can select which ones it wants. In practice this makes little sense
212   as Mapnik layers are not really made for separate use.
213
214Key Database
215
216   This module is used by Geofabrik to serve WMS content to paying customers.
217   Since not all WMS clients support HTTP authentication, we embed a customer
218   specific hash key in the URL (http://servername/maptype/hashkey?...). The
219   module checks whether the given key is in the database and disallows
220   access otherwise.
221
222   You can enable this mechanism if you set USE_KEY_DATABASE when compiling
223   mod_mapnik_wms. There's a small utility that creates the required databas
224   files from a CSV file in the keydb directory.
225
226Testing
227
228   You should be able to test your server with any WMS client, e.g.
229   OpenLayers or Quantum GIS. However, a simple check can be performed
230   directly in the browser:
231
232 http://servername/?LAYERS=&FORMAT=image%2Fjpeg&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&EXCEPTIONS=application%2Fvnd.ogc.se_inimage&SRS=EPSG%3A4326&BBOX=-58.0078125,-13.359375,76.2890625,85.78125&WIDTH=382&HEIGHT=282
233
234   This should bring up a small map image with Europe and Northern Africa in
235   view.
Note: See TracBrowser for help on using the repository browser.