mirror of
https://github.com/openstreetmap/mod_tile.git
synced 2025-07-20 18:21:52 +00:00
c4e3e6230c
`libcurl` & `libcairo` are also optional and their usage can now be optionally disabled (along with `libmemcached` & `librados`.) * No longer test macOS Autotools building
265 lines
9.0 KiB
ReStructuredText
265 lines
9.0 KiB
ReStructuredText
====================
|
|
mod_tile and renderd
|
|
====================
|
|
|
|
This software contains two main pieces:
|
|
|
|
1) ``mod_tile``: An Apache 2 module to deliver map tiles.
|
|
2) ``renderd``: A daemon that renders map tiles using mapnik.
|
|
|
|
.. figure:: ./screenshot.jpg
|
|
:alt: Image showing example slippy map and OSM layer
|
|
|
|
Together they efficiently render and serve raster map tiles for example
|
|
to use within a slippy map. The two consist of the classic raster tile
|
|
stack from `OpenStreetMap.org <https://openstreetmap.org>`__.
|
|
|
|
As an alternative to ``renderd`` its drop-in replacement
|
|
`Tirex <https://github.com/openstreetmap/tirex>`__ can be used in
|
|
combination with ``mod_tile``.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
* `Supported Operating Systems`
|
|
* `FreeBSD`
|
|
* `GNU/Linux`
|
|
* `macOS`
|
|
* `Supported Build Systems`
|
|
* `CMake <https://cmake.org/>`__
|
|
* `GNU Autotools <https://www.gnu.org/software/software.html>`__
|
|
* `Runtime/Build Dependencies`
|
|
* `Apache 2 HTTP webserver <https://httpd.apache.org/>`__
|
|
* `Cairo 2D graphics library (optional) <https://cairographics.org/>`__
|
|
* `Curl library (optional) <https://curl.haxx.se/>`__
|
|
* `GLib library <https://gitlab.gnome.org/GNOME/glib>`__
|
|
* `Iniparser library <https://github.com/ndevilla/iniparser>`__
|
|
* `Mapnik library <https://mapnik.org/>`__
|
|
* `Memcached library (optional) <https://libmemcached.org/>`__
|
|
* `RADOS library (optional) <https://docs.ceph.com/en/latest/rados/api/librados/>`__
|
|
|
|
Installation
|
|
------------
|
|
|
|
Starting from the following operation systems and their versions:
|
|
|
|
* Debian 11 (Bullseye)
|
|
* Ubuntu 21.04 (Hirsute Hippo)
|
|
|
|
the software and all dependencies can be installed simply with:
|
|
|
|
::
|
|
|
|
$ apt install libapache2-mod-tile renderd
|
|
|
|
These packages for **Debian** and **Ubuntu** are being maintained by
|
|
the `Debian GIS Team <https://wiki.debian.org/DebianGis>`__ in the respective
|
|
`repository <https://salsa.debian.org/debian-gis-team/libapache2-mod-tile>`__.
|
|
|
|
Compilation
|
|
-----------
|
|
|
|
You may want to compile this software yourself. Either for developing on it or
|
|
when using it on an operating system this is not being packaged for.
|
|
|
|
We prepared instructions for you on how to build the software on the following
|
|
distributions:
|
|
|
|
* `Arch Linux </docs/build/building_on_arch_linux.md>`__
|
|
* `CentOS Stream </docs/build/building_on_centos_stream.md>`__
|
|
* `Debian </docs/build/building_on_debian.md>`__
|
|
* `Fedora </docs/build/building_on_fedora.md>`__
|
|
* `FreeBSD </docs/build/building_on_freebsd.md>`__
|
|
* `macOS </docs/build/building_on_macos.md>`__
|
|
* `openSUSE </docs/build/building_on_opensuse.md>`__
|
|
* `Ubuntu </docs/build/building_on_ubuntu.md>`__
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
After you either installed the software packages or compiled the software
|
|
yourself, you can continue with the configuration. For your convenience
|
|
example configuration files are distributed with the software packages and
|
|
located in the ``etc`` directory of this repository.
|
|
|
|
A very basic example-map and data can be found in the ``utils/example-map``
|
|
directory.
|
|
|
|
For a simple test copy it over to ``/usr/share/renderd/example-map``:
|
|
|
|
::
|
|
|
|
$ sudo mkdir -p /usr/share/renderd
|
|
$ sudo cp -av utils/example-map /usr/share/renderd/
|
|
|
|
Copy the apache configuration file to its place, too:
|
|
|
|
::
|
|
|
|
$ sudo cp -av etc/apache2/renderd-example-map.conf /etc/apache2/sites-available/renderd-example-map.conf
|
|
|
|
Add map configurations for example-map to ``/etc/renderd.conf``:
|
|
|
|
::
|
|
|
|
$ printf '
|
|
[example-map]
|
|
URI=/tiles/renderd-example
|
|
XML=/usr/share/renderd/example-map/mapnik.xml
|
|
|
|
[example-map-jpg]
|
|
TYPE=jpg image/jpeg jpeg
|
|
URI=/tiles/renderd-example-jpg
|
|
XML=/usr/share/renderd/example-map/mapnik.xml
|
|
|
|
[example-map-png256]
|
|
TYPE=png image/png png256
|
|
URI=/tiles/renderd-example-png256
|
|
XML=/usr/share/renderd/example-map/mapnik.xml
|
|
|
|
[example-map-png32]
|
|
TYPE=png image/png png32
|
|
URI=/tiles/renderd-example-png32
|
|
XML=/usr/share/renderd/example-map/mapnik.xml
|
|
|
|
[example-map-webp]
|
|
TYPE=webp image/webp webp
|
|
URI=/tiles/renderd-example-webp
|
|
XML=/usr/share/renderd/example-map/mapnik.xml
|
|
' | sudo tee -a /etc/renderd.conf
|
|
|
|
Ensure the ``/run/renderd`` directory exists:
|
|
|
|
::
|
|
|
|
$ sudo mkdir -p /run/renderd
|
|
|
|
Start the rendering daemon:
|
|
|
|
::
|
|
|
|
$ sudo renderd
|
|
|
|
Enable the apache module and site:
|
|
|
|
::
|
|
|
|
$ sudo a2enmod tile
|
|
$ sudo a2ensite renderd-example-map
|
|
|
|
Restart apache:
|
|
|
|
::
|
|
|
|
$ sudo apache2ctl restart
|
|
|
|
Now visit the renderd example map in your browser, e.g.:
|
|
|
|
::
|
|
|
|
http://localhost/renderd-example-map
|
|
|
|
Or try loading a single tile, e.g:
|
|
|
|
::
|
|
|
|
http://localhost:8081/tiles/renderd-example/0/0/0.png
|
|
|
|
*Note: the above commands and paths may differ based on your OS/distribution.*
|
|
|
|
You may edit ``/etc/renderd.conf`` to indicate the location of different
|
|
mapnik style sheets (up to ten) and the endpoints you wish to use to access
|
|
it.
|
|
|
|
It is recommended to checkout `switch2osm
|
|
<https://switch2osm.org/serving-tiles/>`__ for nice tutorials
|
|
on how to set up a full tile server like on `OpenStreetMap.org
|
|
<https://www.openstreetmap.org/>`__, using this software together with a
|
|
`PostgreSQL <https://www.postgresql.org/>`__ database and data from
|
|
OpenStreetMap.
|
|
|
|
|
|
Details about ``renderd``: Tile rendering
|
|
-----------------------------------------
|
|
|
|
The rendering is implemented in a multithreaded process
|
|
called ``renderd`` which opens either a unix or tcp socket
|
|
and listens for requests to render tiles. It uses Mapnik
|
|
to render tiles using the rendering rules defined in
|
|
the configuration file ``/etc/renderd.conf``. Its configuration
|
|
also allows to specify the number of rendering
|
|
threads.
|
|
|
|
The render daemon implements a queuing mechanism with multiple
|
|
priority levels to provide an as up-to-date viewing experience
|
|
given the available rendering resources. The highest priority
|
|
is for on the fly rendering of tiles not yet in the tile cache,
|
|
two priority levels for re-rendering out of date tiles on the fly
|
|
and two background batch rendering queues. The on the fly rendering
|
|
queues are limited to a short 32 metatile size to minimize latency.
|
|
The size of the main background queue is determined
|
|
at compile time, see: ``render_config.h``
|
|
|
|
|
|
Details about ``mod_tile``: Tile serving
|
|
----------------------------------------
|
|
|
|
An Apache module called ``mod_tile`` enhances the regular
|
|
Apache file serving mechanisms to provide:
|
|
|
|
1) When tiles have expired it requests the rendering daemon to render (or re-render) the tile.
|
|
2) Remapping of the file path to the hashed layout.
|
|
3) Prioritizes rendering requests depending on the available resources on the server and how out of date they are.
|
|
4) Use tile storage other than a plain posix file system. e.g it can store tiles in a ceph object store, or proxy them from another tile server.
|
|
5) Tile expiry. It estimates when the tile is next likely to be rendered and adds the appropriate HTTP cache expiry headers. This is a configurable heuristic.
|
|
|
|
To avoid problems with directories becoming too large and to avoid
|
|
too many tiny files. They store the rendered tiles in "meta tiles" in a
|
|
special hashed directory structure. These combine 8x8 actual tiles into a
|
|
single metatile file. This is a more efficient use of disk space and inodes.
|
|
|
|
The metatiles are then stored in the following directory structure:
|
|
``/[base_dir]/[TileSetName]/[Z]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy].meta``
|
|
|
|
Where ``base_dir`` is a configurable base path for all tiles. ``TileSetName``
|
|
is the name of the style sheet rendered. ``Z`` is the zoom level.
|
|
``[xxxxyyyy]`` is an 8 bit number, with the first 4 bits taken from the x
|
|
coordinate and the second 4 bits taken from the y coordinate. This
|
|
attempts to cluster 16x16 square of tiles together into a single sub
|
|
directory for more efficient access patterns.
|
|
|
|
Apache serves the files as if they were present under
|
|
``/[TileSetName]/Z/X/Y.png`` with the path being converted automatically.
|
|
|
|
Notes about performance
|
|
-----------------------
|
|
|
|
``mod_tile`` is designed for high performance tile serving. If the
|
|
underlying disk system allows it, it can easily provide > 10k tiles/s
|
|
on a single serve.
|
|
|
|
Rendering performance is mostly dependent on mapnik and postgis performance,
|
|
however ``renderd`` tries to make sure it uses underlying hardware as
|
|
efficiently as possible and scales well on multi core systems. ``renderd``
|
|
also provides built-in features to scale to multi server rendering set-ups.
|
|
|
|
Copyright and copyleft
|
|
----------------------
|
|
|
|
Copyright (c) 2007 - 2023 by mod_tile contributors (see `AUTHORS <./AUTHORS>`__)
|
|
|
|
This program is free software: you can redistribute it and/or modify it
|
|
under the terms of the GNU General Public License as published by the
|
|
Free Software Foundation, either version 2 of the License, or (at your
|
|
option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
|
|
Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see http://www.gnu.org/licenses/.
|
|
|
|
See the `COPYING <./COPYING>`__ for the full license text.
|