source: subversion/applications/utils/mod_tile/readme.txt @ 4955

Last change on this file since 4955 was 4955, checked in by jonb, 12 years ago

mod_tile: Apache module and rendering daemon for serving OSM tiles

File size: 4.3 KB
Line 
1mod_tile
2========
3
4A program to efficiently render and serve map tiles for
5www.openstreetmap.org map using Apache and Mapnik.
6
7Note: This program is very much still in development
8it has numerous hard coded paths and options which need
9to be made user configurable options. You will not
10be able to use this program without modifying these to
11fit your local environment.
12
13Requirements
14============
15OSM map data imported into PostgreSQL using osm2pgsql
16Mapnik renderer along with the OSM.xml file and map
17symbols, world_boundaries shapefiles. Apache with
18development headers for APR module development.
19
20
21Tile Rendering
22==============
23The rendering is implemented in a multithreaded process
24called renderd which opens a unix socket and listens for
25requests to render tiles. It uses Mapnik to render tiles
26using the rendering rules defined in osm-jb-merc.xml.
27
28The render daemon implements a queueing mechanism which
29can render foreground requests (for new tiles being viewed)
30and background requests (updating tiles which have expired)
31
32Tile serving
33============
34Tiles are served from the filesystem using Apache from
35/var/www/html/osm_tiles2/[Z]/[X]/[Y].png
36
37where X,Y,Z are the standard OSM tile co-ordinates.
38
39An Apache module called mod_tile enhances the regular
40Apache file serving mechanisms to provide:
41
421) Tile expiry. It estimates when the tile is next
43likely to be rendered and adds the approriate HTTP
44cache expiry headers
45
462) When tiles have expired it requests the rendering
47daemon to render (or re-render) the tile.
48
49There is an attempt to make the mod_tile code aware of
50the load on the server so that it backs off the rendering
51if the machine is under heavy load.
52
53Setup
54=====
55Make sure you've read and implemented the things in the
56requirements section. Edit the paths in the source to
57match your local setup. Compile the code with make, and
58then make install (as root, to copy the mod_tile to the
59apache module directory).
60
61Create a new apache config file to load the module,
62e.g.
63/etc/httpd/conf.d/mod_tile.conf
64
65--------------
66
67LoadModule tile_module modules/mod_tile.so
68
69<Directory /var/www/html/osm_tiles2/>
70  SetHandler tile
71</Directory>
72
73--------------
74
75Create the directory /var/www/html/osm_tiles2/
76
77Run the rendering daemon 'renderd'
78
79Make sure the osm_tiles2 directory is writeable by the
80user running the renderd process.
81
82Restart Aapche
83
84Note: SELinux will prevent the mod_tile code from opening
85the unix-socket to the render daemon so must be disabled.
86
87Try loading a tile in your browser, e.g.
88http://localhost/osm_tiles2/0/0/0.png
89
90The render daemon should have produce a message like:
91
92Got incoming connection, fd 7, number 1
93Render z(0), x(0), y(0), path(/var/www/html/osm_tiles2/0/0/0.png)
94
95After a few seconds you should see a tile of the world
96in your browser window.
97
98To get a complete slippy map you should install a copy
99of the OpenLayers based OSM slippy map and point this to
100fetch tiles from http://localhost/osm_tiles2
101
102mysql2file
103==========
104This was written to export the existing OSM tiles from
105the Mysql database to the filesystem.
106
107Bugs
108====
109Too many hard coded options (need to be come module options or command
110line options to renderd).
111mod_tile uses many non-APR routines. It probably only works in Linux.
112If rendering daemon dies then all queued rendering requests are lost.
113Code has not been thoroughly tested.
114
115Performance
116===========
117The existing tile serving based on Apache + mod_ruby + cat_tile.rb
118+ Mysql manages to serve something in the region of 250 - 500 requests
119per second. Apache + mod_tile manages 2000+ per second. Both these
120figures are for tiles which have already been rendered.
121
122Filesystem Issues
123=================
124The average tile size is currently somewhere in the region of 2.5kB.
125(Based on a 20GB MySQL DB which contains 8M tiles). Typically
126filesystems are not particularly efficient at storing large numbers
127of small files. They often take a minimum of 4kB on the disk.
128
129Unfortunately if you reduce the block size to 1 or 2kB then this also
130has a significant impact on the maximum file system size and number of
131inodes available.
132
133The simple z/x/y.png filesystem layout means that at high zoom levels
134there can be large numbers of files in a single directory
135 
136  Zoom 18 = 2^18 = 256k files in a single directory.
137
138If ext2/3 is being used then you really need to have directory indexing
139enabled.
Note: See TracBrowser for help on using the repository browser.