You are here

TileStream, Openlayers and Drupal 7

If you want to have custom designed maps on your Drupal site one solution is to use TileMill and TileStream combined with OpenLayers. This article explains how to install TileStream on a Debian 6.0 server and how to display them using views and OpenLayers in Drupal 7.

Install TileStream server

TileStream is a Node.js application, so it requires that you have node.js install in version v0.4.9 (which is not the newest version, but this version is required by TileStream). You should check the read me as this version requirement may change over time. You can install node.js and TileStream by execute the commands below. It requires that you have Git installed.

Note The last section of this article shows how to install TileStream on OS X.

~$ git clone --depth 1 git://
~$ cd node
~$ git checkout v0.4.9
~$ ./configure --prefix=/opt/node-v0.4.9
~$ make -j2
~$ make install
~$ ln -s /opt/node-v0.4.9/bin/* /usr/local/bin/
~$ curl | sh
~$ npm install -g tilestream

Now that you have TileStream installed, you can execute the first command below to see options. The other command starts TileStream with its map/data directory in /usr/share/tilestream.

~$ tilestream start --help
~$ tilestream --tiles=/usr/share/tilestream

To test that TileStream is running, you can try connecting to it at http://localhost:8888 in your local browser. You won't have any maps yet, if you want you can download this simple test map of the world. Unpack it (bzip2 -d testmap.mbtiles.bz2) and place it in /usr/share/tilestream.

~$ lynx http://localhost:8888

Run script

To make TileStream start at boot time as a background process with the other services on the server, you will need to install the run-script below.

~$ nano -w /etc/init.d/tilestream
# Provides:          tilestream
# Required-Start:    $local_fs $remote_fs $network $syslog $named
# Required-Stop:     $local_fs $remote_fs $network $syslog $named
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# X-Interactive:     true
# Short-Description: Start TileStream server


case $1 in
        echo "Starting TileStream"
        $TILESTREAM --tiles=$MAPPATH &
        echo "Stopping TileStream"
        PID=ps aux | grep $TILESTREAM | grep -v grep | awk '{print $2}'
        kill -9 $PID
        echo "Restarting TileStream"
       $0 stop
       sleep 1
       $0 start
        echo "Usage: $0 {start|stop|restart}" >&2
        exit 1

Make sure that the script is started at the right run-levels to ensure that the service is running after reboot.

~$ /etc/init.d/tilestream start
~$ chmod 755 /etc/init.d/tilestream
~$ sysv-rc-conf --level 2345 tilestream on

Proxy with Apache

You connect to TileStream through port 8888, which for most clients is closed in firewalls, so in production environment where you want clients to be able to access TileStream you have to proxy the connection. The Apache configuration code below shows how to proxy TileStream to map., which can be access on port 80 (http).

<VirtualHost *:80>
  ServerName map.<domain>
  DocumentRoot /var/www/

  ProxyRequests Off
  ProxyPreserveHost On

  <Proxy *>
    Order deny,allow
    Allow from all

  ProxyPass / http://localhost:8888/
  ProxyPassReverse / http://localhost:8888/

  ErrorLog ${APACHE_LOG_DIR}/map_error.log

  LogLevel warn
  CustomLog ${APACHE_LOG_DIR}/map_access.log combined


Now that you have a TileStream server up-a-running it's time to use open layers in Drupal to display maps. For this article I will use the location module together with the OpenLayers module to show node locations on a map using views. Another module you should consider using is the Geofield module which gives you more possibilities in interacting with our maps, but it's somewhat advanced to configure. I can recommend reading the book Mapping with Drupal from O'Reilly, which gives a good introduction to mapping (around 150 pages).

As of this writing TileStream have switched from using TMS to XYZ format, which have raised some issues when configure Drupal to display the maps. OpenLayers has some issues with display XYZ layers from TileStream. I have written a patch that makes the OpenLayers module work with TileStream. See the patch in the issue queue here You may also want to use a newer version then 7.x-2.0-beta1 of the module.

~$ drush dl openlayers location views_ui
~$ cd sites/all/modules/openlayers
~$ wget
~$ patch -p1 < openlayers-926326-8.patch
~$ drush en openlayers_ui openlayers_views openlayers location_node location views_ui

Before you can use the location module to plot nodes it needs to be configured at admin/config/content/location. If you want to use geo-coding for addresses you have to enable the countries you want to use on the "Geocoding options" tab. Now edit the content types (admin/structure/types) that you want to have support for spatial information. When edit the content type(s) click the "Locative information" tab and enable spatial information for that type. Create some nodes with spatial information to use for the rest of this article.


Now that we have TileStream running and configured our content types to store spatial data we need to setup OpenLayers to use the local TileStream server. Start by going to admin/structure/openlayers and check "Preview Map". After saving the changes, click the Layers tab and create a new layer by clicking the Add link and select XYZ on the next page. Fill in the information listed below.

  • Layer Machine Name: test
  • Layer Title: Test Layer
  • Layer Description: Baselayer show testmap from TileStream server
  • Base URL (template): http://localhost:8888/v2/testmap/${z}/${x}/${y}.png (if you use Apache proxy the port should be 80)
  • Layer Name: testmap (if you download my test map)
  • Zoom Level Range: 2-10 (if you download my test map)
  • Wrap Date Line: Unchecked


Now that we have created a baselayer with the local TileStream's testmap the next step is to create a map that uses this layer, so go to admin/structure/openlayers/maps and click the Add link. Fill out the form with the information below as show below.

  • Basic
    • Map Machine Name: test_map
    • Map Title: Test map
    • Map Description: Show node locations on testmap
  • Center and Bounds
    • Centerpoint: 9.624017328957, 56.316533334288 (if you download my test map)
    • Zoom Level: 3 (if you download my test map)
  • Layers and Styles
    • Select the Test Layer and set it as default.

Spatial data (views)

We will use views to display both the map and the spatial data (node locations) on the map. We start by creating a view with the nodes location as an OpenLayers Data Overlay, go to admin/structure/views/add and fill out the form as shown in the image below, then click "Continue & edit".

Create view to hold OpenLayers data overlay and map

Click the "Add" display button and select OpenLayers Data Overlay as display type.

Add OpenLayers Data Overlay display in views

In the fields section under the display (you just added) the Title field is the only one selected as default. To show spatial information you will need to add the Latitude and Longitude fields.

Added latitude and longitude to the views field list

Select both fields to display decimal degrees and don't check the "Create a lable" check box as shown on the next image and click "Apply (all displays)".

Select latitude and longitude output format

In the main window you should change the number of items to display to "Display all items" by clicking the "Items to display" in the middle of the screen. You should also change the output format for the display by clicking on "Unformatted list" and select "OpenLayers Data Overlay" and click "Apply (all displays)" as show in the image below.

Change views format to OpenLayers Data Overlay

In the next screen you need to fill out the data sources (fields) that you want to use for Title, Latitude and Longitude and click "Apply (all displays)" as show below.

Select datasources for the view output

Now that we have data overlay to display node locations the next step is to add a new "Page" or "Block" display and give it a "Path".

Add page display to handle the map

Its output format should be set to "OpenLayers Map". Remember to override options for this display only as show in the images below. Click "Apply (this display)" and select the "Test map" on the next screen.

Select map formatter - OpenLayers Map

Now save the view, if you go to the URL given to the page display that you just created (/testmap) you will see the map, but without any points plotted. To get the nodes plotted you have to go to admin/structure/openlayers/maps and add the data layer to your map. Edit the test map and click the "Layers & Styles" tab and activate the layer as shown in the image below and click "Save".

Activate the new data layer on the map

You should now have a TileStream map with you nodes plotted at the URL you entered in the "OpenLayers Map" page display in views at /testmap.

Bonus information

If you want to enable "Pop up" windows with the "Title" and "Description" fields selected in the "OpenLayer Data OverLay" view display. Edit you map and click the "Behaviors" tab and enable the "Pop up feature" and select the layer that you want to apply the pop-ups.

Enable pop ups for node pointers

Getting it running on Mac

It can be somewhat troublesome to get TileStream running on a Mac using Homebrew as TileStream requires a specific version of node.js, namely 0.4.9 as of this writing. See the TileStream issue queue at for installation instructions. The steps are summarized below for fast installation.

~$ brew install node  # You'll now have the latest node version
~$ cd /usr/local/Cellar/node
~$ brew versions node
~$ git checkout -b node-0.4.9 10b3ded
~$ brew install node
~$ brew switch node 0.4.9
~$ curl | sh
~$ npm install -g tilestream



The init.d script doesn't work for me on debian with the current tilestream via npm install.

Wow, so easy to set up.

This shit should be at least a dozen steps easier.

Is it possible to view rendered maps from remote if port 8888 is closed. Port closed to restrict a direct access to tilestream UI remotely.

Add new comment

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.