Providing maps for your web site

There are many different options for providing maps on your own web site. The most basic and easiest for you to use is a JavaScript library called OpenLayers that provides a draggable map that you can embed on your own webpage. This is similar to the earlier section in this book describing the "Export" tab on http://osm.org/. In this chapter we'll go farther by describing how to set up your own server with a customized map style based on OpenStreetMap data. You might want to do this if you are interested in highlighting a particular kind of OpenStreetMap data like bicycle or foot paths or if you are dissatisfied with the elements present in the other available map styles.

System requirements

Serving your own maps is a fairly intensive task. Depending on the size of the area you're interested in serving and the traffic you expect the system requirements will vary. In general, requirements will range from 10-20GB of storage, 4GB of memory, and a modern dual-core processor for a city-sized region to 300GB+ of fast storage, 24GB of memory, and a quad-core processor for the entire planet.

What are tiles?

For our purposes, a web map is made up of several adjacent square images, each 256 pixels square, that cover a particular geographic region of the Earth. The OpenLayers library we are using in this example will place these tiles in a grid to form a draggable view of anywhere on the Earth.

Using OpenLayers

OpenLayers is a JavaScript library for displaying maps on your web site. It is very powerful and can be used to add advanced features to your map like buttons, overlays, popup windows and lines. In this example we'll use it simply to show the map that you render, but to learn more about extending it to include these features, please visit http://openlayers.org/.

The toolchain

We use a series of tools for generating and serving map tiles:

Apache provides the front end server that handles requests from your web browser and passes the request to mod_tile. The Apache web server can also be used to serve static web content like the HTML, JavaScript, or CSS for your map webpage.

Once Apache handles the request from the web user, it passes the request to mod_tile to deal with. Mod_tile checks if the tile has already been created and is ready for use or whether it needs to be updated due to not being in the cache already. If it is already available and doesn't need to be rendered, then it immediately sends the tile back to the client. If it does need to be rendered, then it will add it to a "render request" queue, and when it gets to the top of the queue, a tile renderer will render it and send the tile back to the client.

We use a tool called Mapnik to render tiles. It pulls requests from the work queue as fast as possible, extracts data from various data sources according to the style information, and renders the tile. This tile is passed back to the client and moves on to the next item in the queue.

For rendering, OpenStreetMap data is stored in a PostgreSQL database created by a tool called osm2pgsql. These two pieces work together to allow efficient access to the OpenStreetMap geographic data. It is possible to keep the data in the PostgreSQL database up to date using a stream of diff files produced every 60 seconds on the main OpenStreetMap server.

Setting up your own tile server

Software Configuration

Start with an installation of Ubuntu (10.04) Lucid Lynx Server for your hardware architecture. Add the LAMP server and SSH server during installation. Once installed, this can be run as a headless server with neither monitor nor keyboard. So ssh to the new box, and let's get started. Since there may be several updates for Lucid Lynx, update the packages on your system:

sudo apt-get update
sudo apt-get upgrade

Fetch some essential system tools for this tile server installation process:

sudo apt-get install subversion autoconf screen munin-node munin htop

Organize the file system to make the installation process a bit easier:

cd ~
mkdir src bin planet

Get the latest OpenStreetMap data

Retrieve a piece of OpenStreetMap data from http://planet.openstreetmap.org/. Since the whole planet is at least 18GB when compressed, there are links to smaller country or state sized extracts on that page. Since it is smaller and faster to interact with, the PBF file format is preferable when available. In this case we'll download the entire planet file by issuing the following command:

cd planet
wget http://planet.openstreetmap.org/planet-latest.osm.bz2

Install and configure PostgreSQL database

Next, we need to install the PostgreSQL database system. Start by using apt-get to install the database and required extensions:

It should restart without any errors and report back with this message:

* Restarting PostgreSQL 8.4 database server
...done.

Create a database called gis. Some of our future tools presume that you will use this database name. Substitute your username for username in two places below. This should be the username that will render maps with Mapnik.

Once compiled, we need to set the spatial reference on the newly-created database:

psql -f ~/bin/osm2pgsql/900913.sql -d gis

With the conversion tool compiled and the database prepared, the following command will insert the OpenStreetMap data you downloaded earlier into the database. This step is very disk I/O intensive and will take roughly 30 hours depending on the speed of the computer performing the conversion and the size of the data you retrieved from the server.

Don't be concerned by the NOTICE: entries above. All normal. Next, osm2pgsql will start reading the compressed planet file.

Reading in file: /home/user/planet/planet-latest.osm.bz2

As osm2pgsql reads the planet file it will give progress reports. The line below will refresh every few seconds and update the numbers in brackets. This part of the import takes a long time. Depending on your server, it will take between hours and days.

Processing: Node(10140k) Way(0k) Relation(0k)

As the import proceeds, the Node number will update a couple of times per second until complete, then the Way number will update roughly every second or two. Finally, the Relation number will update at roughly once per minute. As long as you can see these numbers advancing the import process is still operating normally for your server. Do not interrupt the import process unless you have decided to start over again from the beginning.

Install Mapnik library

Next, we need to install the Mapnik library. Mapnik is used to render the OpenStreetMap data into the tiles used for an OpenLayers web map. To start, we'll install the dependencies for the Mapnik library followed by downloading and compiling the source:

View image.png to confirm that you have rendered a map of England. Congratulations!

Install and configure Apache web server and mod_tile

Now that we've created an image using your map data, we need to set up the tile serving software to handle tile requests using Apache. To do this, we'll install the Apache web server and use the mod_tile extension to handle the tile rendering system.

Create the files required for the mod_tile system to run (remember to change username to your user's name):

sudo mkdir /var/run/renderd
sudo chown username /var/run/renderd

Next, we need to tell the Apache web server about our new mod_tile installation by creating the file /etc/apache2/conf.d/mod_tile and adding one line:

LoadModule tile_module /usr/lib/apache2/modules/mod_tile.so

Also, Apache's default website configuration file needs to be modified to include mod_tile settings. Modify the file /etc/apache2/sites-available/default to include the following lines immediately after the admin e-mail address line:

LoadTileConfigFile /etc/renderd.conf
ModTileRenderdSocketName /tmp/osm-renderd
# 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

You'll then need to start the mod_tile rendering application. Note that it will not output anything upon successful start.

cd ~/src/mod_tile
./renderd

Congratulations! You now have a server capable of generating tiles using your own copy of the OpenStreetMap data. Visit http://localhost/osm_tiles2/0/0/0.png to verify that you have a working map tile generated.