Deploying TileStream to the Heroku Cloud

TileStream is an open source tile server devel­oped by Map­Box, which bor­rows exten­sively from their com­mer­cial Map­Box tile server prod­uct. TileStream loads map layer pack­ages cre­ated in the TileMill appli­ca­tion, which are stored on the server as SQLite data­bases in the mbtiles specification/schema. On the other hand, Heroku is a cloud appli­ca­tion plat­form that sup­ports Python, Ruby, Java and Node.js apps, the lat­ter of which TileStream is depen­dent upon. This post will show how to deploy a TileStream server on the Heroku cloud appli­ca­tion plat­form, thereby allow­ing you to serve your map tiles using scal­able infra­struc­ture that can respond to fluc­tu­a­tions in the demand of your web maps. See the result here.

Download and Install

• Git
• Heroku Tool­belt

If you already have git or heroku tool­belt installed you may skip this step. You can check to see if git and heroku are avail­able on your sys­tem by check­ing the ver­sion of each tool. On win­dows, you will want to work inside of the “git bash shell” which is an unix ter­mi­nal appli­ca­tion installed for your git usage that also con­nects to the sys­tem PATH envi­ron­ment mak­ing heroku available.

$ git --version
git version 1.8.1.msysgit.1

$ heroku --version
heroku/toolbelt/3.2.2 (i386-mingw32) ruby/1.9.3

Setup Heroku

If this is your first time using Heroku, cre­ate an account on their web­site. After doing so you will be able to login to Heroku using the com­mand line. Doing so will “pair” your com­puter up with your Heroku account via an exchange of your RSA authen­ti­ca­tion key. If you don’t already have a pub­lic RSA key on your com­puter you will be asked to gen­er­ate one when you login.

$ heroku login
Enter your Heroku credentials.
Email: 
Password (typing will be hidden):
Could not find an existing public key.
Would you like to generate one? [Yn] yes
Generating new SSH public key.
Uploading SSH public key ~/.ssh/id_rsa.pub... done
Authentication successful.

Create a Heroku App

Cre­ate an app, which is Heroku’s fun­da­men­tal unit of orga­ni­za­tion to which you can deploy, man­age and pro­vi­sion your TileStream server. I am going to call my app tilestream. This for­mal­izes an app on your Heroku account that is acces­si­ble via url and git at tilestream.heroku.com and [email protected]:tilestream.git

$ heroku create tilestream
Creating tilestream... done, stack is cedar
http://tilestream.herokuapp.com/ | [email protected]:tilestream.git

You can check to see if this worked by vis­it­ing the url of your new heroku app. A place­holder wel­come page will be shown.

The Application

On your com­puter, cre­ate a new direc­tory for your app. I keep all of my Heroku apps in their own folder. You will also need to cre­ate 2 files within them: Proc­file and package.json. The Proc­file allows us to issue com­mands to the web dyno for your Heroku app (just like issu­ing com­mands on your ter­mi­nal). The package.json file declares our Heroku app as a Node.js appli­ca­tion, and lists what we would like installed. Also, cre­ate a sub­folder for your map tiles. You can move your exist­ing mbtiles pack­ages to the tiles folder, or place an exam­ple mbtiles pack­age made avail­able by Map­Box: control_room (3MB).

$ mkdir ~/heroku/tilestream.herokuapp.com
$ cd ~/heroku/tilestream.herokuapp.com
$ touch Procfile package.json
$ mkdir tiles

Procfile

web: tilestream --host tilestream.herokuapp.com --uiPort=$PORT --tilePort=$PORT --tiles=./tiles

--host maptiles.herokuapp.com url of your Heroku app
--uiPort=$PORT TileStream UI made avail­able through the pub­lic port of your app
--tilePort=$PORT TileStream maps made avail­able through the pub­lic port of your app
--tiles=./tiles tiles folder that con­tains the mbtiles packages

package.json

{
    "name": "tilestream",
    "author": "Michael Markieta",
    "version": "0.0.1",
    "description": "My TileStream Server",
    "engines": {
      "node": "0.10.24",
      "npm":  "1.3.11"
    },
    "dependencies": {
      "tilestream": "1.1.0"
    }
}

name author version description straight-forward Heroku app descrip­tion para­me­ters
engines we want node.js 0.10.24 and npm 1.3.11
dependencies we want tilestream 1.1.0 from npm

Push it to the Cloud

You will need to start off by ini­tial­iz­ing a github repos­i­tory in the root of your Heroku app folder. This will allow you to com­mit changes to the repo and push them to your Heroku app in the cloud. Heroku relies on git as a trans­port mech­a­nism to pub­lish your appli­ca­tion. When changes are made locally and pushed to the cloud, your code (com­mit his­tory) is com­pared to that on Heroku’s servers and only what needs to be changed is trans­ferred (unlike a blan­ket upload-all typ­i­cal of ftp).

$ git init
Initialized empty Git repository in ~/heroku/tilestream.herokuapp.com/.git/
$ git add .
$ git commit -m "initial commit"
 3 files changed, 14 insertions(+)
 create mode 100644 Procfile
 create mode 100644 package.json
 create mode 100644 tiles/control_room.mbtiles
$ git remote add heroku [email protected]:tilestream.git
$ git push heroku master

When this com­pletes you will have TileStream up and run­ning at your app url. Here is the final prod­uct of this tuto­r­ial using the exam­ple mbtiles pack­ages from Map­box: http://tilestream.herokuapp.com