Commit 6f93441f authored by Felix Delattre's avatar Felix Delattre
Browse files

Adjusted installation instructions

parent 0169d767
......@@ -2,7 +2,7 @@
mod_tile and renderd
====================
This Software contains two main pieces:
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.
......@@ -18,19 +18,6 @@ As an alternative to ``renderd`` its drop-in replacement
`Tirex <https://github.com/openstreetmap/tirex>`__ can be used in
combination with ``mod_tile``.
Dependencies
------------
* `GNU/Linux` Operating System (works best on Debian or Ubuntu)
* `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>`__
* `GLib library <https://gitlab.gnome.org/GNOME/glib>`__
Installation
------------
......@@ -49,12 +36,22 @@ 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>`__.
Dependencies
------------
* `GNU/Linux` Operating System (works best on Debian or Ubuntu)
* `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>`__
* `GLib library <https://gitlab.gnome.org/GNOME/glib>`__
Compilation
-----------
You may want to compile this software for developing on it or when using
on operating systems this is not being packaged for. On Debian or Ubuntu
on operating systems this is not being packaged for. On Debian or Ubuntu
systems the following packages are needed to start compiling. On other systems
the name of the libary might differ slightly.
......@@ -90,19 +87,15 @@ environment before you can run it all.
Configuration
-------------
After you either copiled the software yourself or installed the software
packages, you can continue with the configuration. Here we assume that you have
installed mod_tile using packages from Debian/Ubuntu. If you compiled from
source you need to place debian-style configuration files at the relevant locations
to use the Debian helper scripts a2enmod/a2enconf, or manually create apache configuration.
After you either installed the software packages or copiled 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 ``examples/config`` directory of this repository.
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`
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:
Copy the configuration files to their place, too:
::
......@@ -132,7 +125,7 @@ And run the rendering daemon
$ renderd -f
Make sure the /var/cache/renderd/tiles directory is writable by
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.
......@@ -142,45 +135,26 @@ 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.
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.
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.
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.
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
--------------
Details about ``renderd``: Tile rendering
-----------------------------------------
The rendering is implemented in a multithreaded process
called renderd which opens either a unix or tcp socket
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
the configuration file ``/etc/renderd.conf``. Its configuration
also allows to specify the number of rendering
threads.
......@@ -192,65 +166,50 @@ 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
at compile time, see: ``render_config.h``
Tile serving
------------
Details about ``mod_tile``: Tile serving
----------------------------------------
An Apache module called mod_tile enhances the regular
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
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.
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.
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.
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.
The metatiles are then stored in the following directory structure:
``/[base_dir]/[TileSetName]/[Z]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy].png``
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
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.
Apache serves the files as if they were present under
``/[TileSetName]/Z/X/Y.png`` with the path being converted automatically.
Performance
-----------
Notes about performance
-----------------------
mod_tile is designed for high performance tile serving. If the
``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.
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
----------------------
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment