mod_tile
| mod_tile | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| License: | GNU GPL v2 (free of charge) | |||||||||||||||||||||
| Platform: | Linux | |||||||||||||||||||||
| Version: | 0.8.1 (2025-05-04) | |||||||||||||||||||||
| Language: | multiple languages
| |||||||||||||||||||||
| Website: | https://github.com/openstreetmap/mod_tile | |||||||||||||||||||||
| Source code: | https://github.com/openstreetmap/mod_tile | |||||||||||||||||||||
| Programming languages: | C and C++ | |||||||||||||||||||||
|
Module for the Apache web server to serve tiles from a tile cache and to render missing tiles on request using the Mapnik library |
||||||||||||||||||||||
| ||||||||||||||||||||||
mod_tile is a system to serve raster tiles for example to use within a slippy map. It provides a dynamic combination of efficient caching and on the fly rendering. Due to its dynamic rendering, only a small fraction of overall tiles need to be kept on disk, reducing the resources required. At the same time, its caching strategy allows for a high performance serving and can support several thousand requests per second.
Mod_tile was originally written for serving the tiles of the main OSM map (Mapnik layer), but since is being used on a variety of different servers providing maps ontop of OpenStreetMap data.
Implementation
The code is split into two parts:
- mod_tile – A custom Apache module which is responsible for serving tiles and requests the rendering of tiles if they aren't already available in cache or if they have changed since.
- A rendering back-end, that takes requests from mod_tile, and renders them to the file system. It is also responsible for queueing requests to ensure the server is not overloaded if many requests come in simultaneously. Currently there are two implementations of such a rendering back-end: The original renderd and tirex.
Features provided by mod_tile
- high performance serving of tiles
- management of dynamic rendering requests
- support for multiple different styles
- expiry and rerendering of individual tiles
- dynamic adjustment of cache_expiry headers
- a number of munin graphs to monitor the status and health of the server
- throttling of individual clients (by ip-address) to a fair share quota.
Installation
See the official readme for instructions how to install mod_tile from packages or compile it from source.
mod_tile uses the Mapnik library for rendering. It is necessary to install Mapnik first and populate the PostGIS database with data first using osm2pgsql. The detailed steps are shown at switch2osm.org
tile expiry
After rendering a tile, it gets cached on disk for fast serving. As OSM data is constantly updated, improved and changed, a mechanism is needed to correctly expire the cache to ensure updated tiles get re-rendered.
There are several possible mechanisms available for expiring and updating tiles (either through mod_tile or by directly re-rendering cached tiles), of which often a combination is used:
mod_tiles expiry works by comparing the time stamp of rendered tiles to the date of the last full data import into the database.
If the planet time stamp is updated, all tiles are automatically marked as in need for re-rendering (dirty) and will be submitted to the rendering backend on next visit.
For the diff-based updates of the database, expiring all tiles would be too costly, and so only those tiles for which the data was updated get expired by altering the time stamp of those tiles to date far in the past. Again there are two different scripts for doing this. One ruby script and one based on output from osm2pgsql.
Alternatively, there are a number of helper utilities that can directly talk to renderd or tirex, submitting tiles for rerendering. This is often used to re-render low-zoom tiles on a periodical basis in the background, as it would be too costly to update them through the normal diff-based expiry.
See also for more details: Tile expire methods.
Configuration
See the official readme.
Source code
The code is in Git at https://github.com/openstreetmap/mod_tile, the readme.txt file contains other important information which you should read before trying to use this code.
Use git clone https://github.com/openstreetmap/mod_tile.git