Commit a3f4230d authored by Felix Delattre's avatar Felix Delattre
Browse files

Update README instructions

parent d706d960
mod_tile
========
A program to efficiently render and serve map tiles for
www.openstreetmap.org map using Apache and Mapnik.
====================
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
============
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.
------------
* `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
......@@ -32,7 +192,7 @@ 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:
......@@ -74,72 +234,9 @@ 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.
......@@ -148,3 +245,23 @@ 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.
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