The aim of this guide is to setup a tileserver that serves tiles for Great Britain. The OpenStreetMap data will be fetched from Geofabrik.

This guide was tested on a fresh install of Debian Jessie.

Machine Information:

With the configuration given in this document, a maximum of 1GB of memory was used by osm2pgsql during the initial import.

Setup Database

Install Postgres with Postgis

Required Packages

Login as root, and run

apt install postgresql-9.4-postgis-2.1 postgresql-contrib-9.4

Create Database

Next a postgres user, and database must be created. To use peer authentication, you should have a system user by the same name. The username used will be osm. The database name will be greatbritain.

Still as root, switch user to postgres.

su postgres

Also then run:

cd ~

to avoid any problems that can arise from being in the root home directory.

The following commands will then setup the database.

createuser osm
createdb -E UTF8 -O osm greatbritain
psql -c "CREATE EXTENSION hstore;" -d greatbritain # Should result in CREATE EXTENSION
psql -c "CREATE EXTENSION postgis;" -d greatbritain # Should result in CREATE EXTENSION

Then exit from the postgres user.


Create a user

To avoid running the service as root, throughout the rest of this guide, the osm user is used. As said above, using the same name as the user for the database, allows peer authentication to work.

Create this user using the adduser command.

adduser osm

Import Data

Get The Stylesheet

The stylesheet that this guide will use is the standard. You can either download the release here: or clone it, and checkout the v2.29.1 tag. Do this as the osm user, in the users home directory.

su osm
cd ~
tar -xzf v2.29.1.tar.gz

You should now have a directory called "openstreetmap-carto-2.29.1".

This needs to be done at this point as it includes the osm2pgsql style that describes what data goes in to the database.

Install osm2pgsql

Required Packages

Switch back to the root user, and install osm2pgsql

apt install osm2pgsql

Get the initial data

Geofabrik is an organisation that provides convenient extracts of OSM data.

su osm
cd ~

Import the data

Run the following as the osm user. This can take some time, so you might want to consider running it such that you can leave it (e.g. in screen, tmux, ...).

osm2pgsql --slim -d greatbritain -C 1600 --hstore -S openstreetmap-carto-2.29.1/ great-britain-latest.osm.pbf

Possible problems:

At this point, you have a database containing OSM data, to test this, try running the following command.

psql -d greatbritain -c "select name from planet_osm_point where place='city';"

Serving Tiles

Install mod_tile

mod_tile is not yet available in Debian, so it must be built from source. Run the following as the osm user in their home directory to download the source code.

wget -O mod_tile.tar.gz
tar -xzf mod_tile.tar.gz

Required Packages:

apt install autoconf libtool libmapnik-dev apache2-dev

Run as the osm user in the source directory

cd mod_tile-6c2cb243e4c8b047950ab8062cd66245f20a5d2f/

Run as root in the source directory

make install
make install-mod_tile
cd ..

Generate Mapnik Style

Packages Required

apt install curl unzip gdal-bin mapnik-utils node-carto

Return to the OSM style and fetch the required shapefiles from the internet.

cd ~/openstreetmap-carto-2.29.1/

To change the database name, we can use sed

sed -i 's/"dbname": "gis"/"dbname": "greatbritain"/' project.mml

Then build the carto.css in to a mapnik xml stylesheet.

carto project.mml > style.xml

Setup renderd

Open /usr/local/etc/renderd.conf

Change the default section to be as follows

The changes are:

Either run the following commands, or edit the default section of the file to match as below.

All of the commands in this section must be run as root, so


sed -i 's/XML=\/home\/jburgess\/osm\/svn\.openstreetmap\.org\/applications\/rendering\/mapnik\/osm\-local\.xml/XML=\/home\/osm\/openstreetmap-carto-2.29.1\/style.xml/' /usr/local/etc/renderd.conf
sed -i 's/HOST=tile\.openstreetmap\.org/HOST=localhost/' /usr/local/etc/renderd.conf

At this point, the default section in the /usr/local/etc/renderd.conf configuration file will look as follows.

;** config options used by mod_tile, but not renderd **
;TYPE=png image/png
;DESCRIPTION=This is a description of the tile layer used in the tile json request
;ATTRIBUTION=&copy;<a href=\"\">OpenStreetMap</a> and <a href=\"http://wiki.openstreetma$

Next, change the mapnik section.

The changes are:

Again, either run the following command, or change the file manually.

sed -i 's/plugins_dir=\/usr\/lib\/mapnik\/input/plugins_dir=\/usr\/lib\/mapnik\/2.2\/input\//' /usr/local/etc/renderd.conf


Install the init script:

cd /home/osm
cp mod_tile-6c2cb243e4c8b047950ab8062cd66245f20a5d2f/debian/renderd.init /etc/init.d/renderd
chmod a+x /etc/init.d/renderd

Correct the paths in the init script:

sed -i 's/DAEMON=\/usr\/bin\/$NAME/DAEMON=\/usr\/local\/bin\/$NAME/' /etc/init.d/renderd
sed -i 's/DAEMON_ARGS=""/DAEMON_ARGS=" -c \/usr\/local\/etc\/renderd.conf"/' /etc/init.d/renderd
sed -i 's/RUNASUSER=www-data/RUNASUSER=osm/' /etc/init.d/renderd

mkdir -p /var/lib/mod_tile
chown osm:osm /var/lib/mod_tile

Start renderd

systemctl daemon-reload
service renderd start

Install and Configure Apache and mod_tile

Install Apache

Required Packages

apt install apache2

Configure apache to load mod_tile

echo "LoadModule tile_module /usr/lib/apache2/modules/" > /etc/apache2/mods-available/tile.load
ln -s /etc/apache2/mods-available/tile.load /etc/apache2/mods-enabled/

Add the following just before <?/VirtualHost> in /etc/apache2/sites-enabled/000-default.conf To do this, you can use the nano text editor

LoadTileConfigFile /usr/local/etc/renderd.conf
ModTileRenderdSocketName /var/run/renderd/renderd.sock
# Timeout before giving up for a tile to be rendered
ModTileRequestTimeout 0
# Timeout before giving up for a tile to be rendered that is otherwise missing
ModTileMissingRequestTimeout 30

Restart apache

service apache2 restart

Load the world in a browser to test

If you are on the machine locally and have a graphical web browser, you can go to: http://localhost/osm_tiles/0/0/0.png If you are accessing the machine via ssh, you can, from your remote machine forward port 80 through ssh, by using the -L option ( -L 8080:localhost:80 )

Any problems with renderd, stop the daemon, and run as following to get the standard output.

service renderd stop
su osm -c "renderd -f -c /usr/local/etc/renderd.conf"

This should reveal the problem

Slippy Map