mirror of
https://github.com/openstreetmap/mod_tile.git
synced 2025-07-25 15:04:30 +00:00
Update README instructions
This commit is contained in:
Felix Delattre
267
README.rst
Normal file
267
README.rst
Normal file
@ -0,0 +1,267 @@
|
|||||||
|
====================
|
||||||
|
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 shoing 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``.
|
||||||
|
|
||||||
|
Requirements
|
||||||
|
------------
|
||||||
|
|
||||||
|
* `Apache 2 HTTP webserver <https://httpd.apache.org/>`__
|
||||||
|
* `Mapnik <https://mapnik.org/>`__
|
||||||
|
* `Cairo 2D graphics library <https://cairographics.org/>`__
|
||||||
|
* `Curl library (SSL variant) <https://curl.haxx.se/>`__
|
||||||
|
* `Iniparser library <https://github.com/ndevilla/iniparser>`__
|
||||||
|
|
||||||
|
Compilation
|
||||||
|
-----------
|
||||||
|
|
||||||
|
On Debian or Ubuntu systems the following packages are needed to start
|
||||||
|
compiling. On other systems the name of the libary might differ
|
||||||
|
slightly.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ apt install build-essential \
|
||||||
|
autoconf \
|
||||||
|
apache2-dev \
|
||||||
|
libcairo2-dev \
|
||||||
|
libcurl4-gnutls-dev \
|
||||||
|
libiniparser-dev \
|
||||||
|
libmapnik-dev
|
||||||
|
|
||||||
|
*(You may install more and optional dependencies in order to add
|
||||||
|
functionality to renderd)*
|
||||||
|
|
||||||
|
Once the dependencies are installed you can compile and install
|
||||||
|
mod_tile and renderd:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ ./autogen.sh
|
||||||
|
$ ./configure
|
||||||
|
$ make
|
||||||
|
$ sudo make install
|
||||||
|
$ sudo make install-mod_tile
|
||||||
|
|
||||||
|
Packages
|
||||||
|
--------
|
||||||
|
|
||||||
|
If you don't want to comile the software yourself. Precompiled
|
||||||
|
software 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>`__.
|
||||||
|
They are in the pipeline and expected to be included in the next releases of
|
||||||
|
those two distributions.
|
||||||
|
|
||||||
|
In the meantime an experimental repository can be used by adding the
|
||||||
|
corresponding line to your ``/etc/apt/sources.list``:
|
||||||
|
|
||||||
|
``deb https://deb.openbuildingmap.org/ bullseye main`` (for Debian Testing, Ubuntu Focal and Ubuntu Groovy)
|
||||||
|
``deb https://deb.openbuildingmap.org/ buster main`` (for Debian Stable)
|
||||||
|
|
||||||
|
Afterwards import the public key for the repository:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ wget -O - https://deb.openbuildingmap.org/archive.key | sudo apt-key add -
|
||||||
|
|
||||||
|
After that you can install the available software as any other package:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ apt update
|
||||||
|
$ apt install libapache2-mod-tile renderd
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
-------------
|
||||||
|
|
||||||
|
After you either copiled the software yourself or installed the software
|
||||||
|
packages, you can continue with the configuration. For your convenience
|
||||||
|
example configuration files are located in the `etc` directory of this
|
||||||
|
repository.
|
||||||
|
|
||||||
|
A very basic example-map and data can be found in the `example-map`
|
||||||
|
directory. For a simple test copy it over to ``/var/www/example-map``.
|
||||||
|
|
||||||
|
Copy the configuration files to their place:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ cp etc/renderd.conf.dist /etc/renderd.conf
|
||||||
|
$ cp etc/apache2/renderd.conf.dist /etc/apache2/conf-available/renderd.conf
|
||||||
|
$ cp etc/apache2/renderd-example-map.conf.dist /etc/apache2/conf-available/renderd-example-map.conf
|
||||||
|
|
||||||
|
Enable the configuration:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ sudo a2enmod tile
|
||||||
|
$ sudo a2enconf renderd
|
||||||
|
$ sudo a2enconf renderd-example-map
|
||||||
|
|
||||||
|
Restart apache2:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ sudo a2enmod tile
|
||||||
|
$ sudo a2enconf renderd
|
||||||
|
|
||||||
|
|
||||||
|
And run the rendering daemon
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ renderd -f
|
||||||
|
|
||||||
|
Make sure the /var/cache/renderd/tiles directory is writable by
|
||||||
|
the user running the renderd process.
|
||||||
|
|
||||||
|
Try loading a tile in your browser, e.g.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
http://localhost/renderd-example/tiles/0/0/0.png
|
||||||
|
|
||||||
|
|
||||||
|
You may edit /etc/renderd.conf to indicate the location of your
|
||||||
|
mapnik style sheet and the uri you wish to use to access it. You may
|
||||||
|
configure up to 10 (by default) mapnik style sheets - simply give each
|
||||||
|
section a unique name and enter the uri and style sheet path.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
The render daemon should have produce a message like:
|
||||||
|
|
||||||
|
Got incoming connection, fd 7, number 1
|
||||||
|
Render fd(7) xml(Default), z(0), x(0), y(0)
|
||||||
|
|
||||||
|
The disk should start thrashing as Mapnik tries to pull
|
||||||
|
in data for the first time. After a few seconds you'll
|
||||||
|
probably see a 404 error. Wait for the disk activity to
|
||||||
|
cease and then reload the tile. With a bit of luck you
|
||||||
|
should see a tile of the world in your browser window.
|
||||||
|
|
||||||
|
If this fails to happen check the http error log. You can
|
||||||
|
increase the level of debugging using the LogLevel apache
|
||||||
|
directive. If no log messages are shown check that you
|
||||||
|
are accessing the correct virtual host - the new version
|
||||||
|
of mod_tile is only installed on a single host by default.
|
||||||
|
To install on multiple hosts either use ServerAlias or
|
||||||
|
use the LoadTileConfigFile in each virtual host.
|
||||||
|
|
||||||
|
For an OSM type setup, OSM map data imported into
|
||||||
|
`PostgreSQL <https://www.postgresql.org/>`__ using
|
||||||
|
`osm2pgsql <https://github.com/openstreetmap/osm2pgsql>`__ is needed.
|
||||||
|
Together with the Mapnik renderer along with the OSM.xml file and map
|
||||||
|
symbols, world_boundaries shapefiles.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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. Mod_tile / renderd 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. For example, many sea tiles are 103 bytes
|
||||||
|
long. In the old scheme a meta tile of blank sea tiles would take
|
||||||
|
64 inodes of 4kB each, a total of 256kB. In this optimized scheme it
|
||||||
|
needs a single file of about 7kB. The metatiles are then stored
|
||||||
|
in the following directory structure:
|
||||||
|
/[base_dir]/[TileSetName]/[Z]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy].png
|
||||||
|
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.
|
||||||
|
|
||||||
|
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 - 2020 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 Affero 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 Affero
|
||||||
|
General Public License for more details.
|
||||||
|
|
||||||
|
You should have received a copy of the GNU Affero General Public License
|
||||||
|
along with this program. If not, see http://www.gnu.org/licenses/.
|
||||||
|
|
||||||
|
See the `COPYING <./COPYING>`__ for the full license text.
|
||||||
150
readme.txt
150
readme.txt
@ -1,150 +0,0 @@
|
|||||||
mod_tile
|
|
||||||
========
|
|
||||||
A program to efficiently render and serve map tiles for
|
|
||||||
www.openstreetmap.org map using Apache and Mapnik.
|
|
||||||
|
|
||||||
Requirements
|
|
||||||
============
|
|
||||||
OSM map data imported into PostgreSQL using osm2pgsql
|
|
||||||
Mapnik renderer along with the OSM.xml file and map
|
|
||||||
symbols, world_boundaries shapefiles. Apache with
|
|
||||||
development headers for APR module development.
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
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. Mod_tile / renderd 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. For example, many sea tiles are 103 bytes
|
|
||||||
long. In the old scheme a meta tile of blank sea tiles would take
|
|
||||||
64 inodes of 4kB each, a total of 256kB. In this optimized scheme it
|
|
||||||
needs a single file of about 7kB. The metatiles are then stored
|
|
||||||
in the following directory structure:
|
|
||||||
/[base_dir]/[TileSetName]/[Z]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy].png
|
|
||||||
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.
|
|
||||||
|
|
||||||
Compiling
|
|
||||||
=========
|
|
||||||
|
|
||||||
mod_tile and renderd utilize a number of third party, some of which it
|
|
||||||
depends on and some provide optional features and are compiled in
|
|
||||||
if the respective libraries are installed. Once the dependencies are installed
|
|
||||||
you can compile and install mod_tile / renderd the usual way:
|
|
||||||
|
|
||||||
./autogen.sh
|
|
||||||
./configure
|
|
||||||
make
|
|
||||||
sudo make install
|
|
||||||
sudo make install-mod_tile
|
|
||||||
|
|
||||||
|
|
||||||
Setup
|
|
||||||
=====
|
|
||||||
Create a new apache config file to load the module,
|
|
||||||
e.g.
|
|
||||||
|
|
||||||
/etc/httpd/conf.d/mod_tile.conf
|
|
||||||
|
|
||||||
See the sample mod_tile.conf for details
|
|
||||||
|
|
||||||
Edit /etc/renderd.conf to indicate the location of your
|
|
||||||
mapnik style sheet and the uri you wish to use to access
|
|
||||||
it. You may configure up to 10 (by default) mapnik
|
|
||||||
style sheets - simply give each section a unique name and
|
|
||||||
enter the uri and style sheet path.
|
|
||||||
|
|
||||||
Make sure the /var/lib/mod_tile directory is writable by
|
|
||||||
the user running the renderd process and create a file an
|
|
||||||
empty file planet-import-complete in this folder.
|
|
||||||
|
|
||||||
Run the rendering daemon 'renderd'
|
|
||||||
|
|
||||||
Restart Aapche
|
|
||||||
|
|
||||||
Note: SELinux will prevent the mod_tile code from opening
|
|
||||||
the unix-socket to the render daemon so must be disabled.
|
|
||||||
|
|
||||||
Try loading a tile in your browser, e.g.
|
|
||||||
http://localhost/osm_tiles/0/0/0.png
|
|
||||||
|
|
||||||
The render daemon should have produce a message like:
|
|
||||||
|
|
||||||
Got incoming connection, fd 7, number 1
|
|
||||||
Render fd(7) xml(Default), z(0), x(0), y(0)
|
|
||||||
|
|
||||||
The disk should start thrashing as Mapnik tries to pull
|
|
||||||
in data for the first time. After a few seconds you'll
|
|
||||||
probably see a 404 error. Wait for the disk activity to
|
|
||||||
cease and then reload the tile. With a bit of luck you
|
|
||||||
should see a tile of the world in your browser window.
|
|
||||||
|
|
||||||
If this fails to happen check the http error log. You can
|
|
||||||
increase the level of debugging using the LogLevel apache
|
|
||||||
directive. If no log messages are shown check that you
|
|
||||||
are accessing the correct virtual host - the new version
|
|
||||||
of mod_tile is only installed on a single host by default.
|
|
||||||
To install on multiple hosts either use ServerAlias or
|
|
||||||
use the LoadTileConfigFile in each virtual host.
|
|
||||||
|
|
||||||
|
|
||||||
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.
|
|
||||||
BIN
screenshot.jpg
Normal file
BIN
screenshot.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 241 KiB |
Reference in New Issue
Block a user