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