TileStream Install Gotchas

I've been wanting to get my hands a bit more dirty with MapBox. I've played around with TileMill and published some maps with my freebie account. However, I want to take development to the next level by setting up my own TileStream server.

While there are TileStream installation instructions out on github for both Mac and Ubuntu, I got thrown some curve balls when installing on OS X 10.7.4. I took some notes and decided to blog them up for future reference. If I can save someone else some time as well, all the better.

PREPARING FOR THE INSTALL

Review the TileStream Mac OS X 10.6 install instructions on github. They are short and sweet. Seems easy enough, but I swear I should have been a tester. I have this nasty habit of stumbling over any and every issue possible. Maybe it's because I'm running OS X 10.7.4 and the instructions are only good for 10.6. Maybe not...

INSTALLATION STEPS

The goal here is to recap the installation steps and provide solutions to issues I encountered.

1. Install Xcode

Better yet, make sure you have Xcode Command Line Tools installed. Later on you'll be installing node with the Homebrew package installer. Without Command Line Tools in place the node install will barf:

$brew install node
Error: No such file or directory - /usr/bin/cc

No worries, after googling the internets I came across Fix Homebrew - You have no /usr/bin/cc. Homebrew has a dependency on Xcode Command Line Tools being installed, so make sure to get them installed according to the simple directions in the post.

2. Install Homebrew

Installing Homebrew went without a hitch. It's a simple one-liner:

$ruby <(curl -fsSkL raw.github.com/mxcl/homebrew/go)

3. Install node

Not so smooth:

$brew install node
...
Please add /usr/local/lib/node to your NODE_PATH environment variable to have node libraries picked up.
ln: vBstdint.h: Permission denied
Error: The linking step did not complete successfully
The formula built, but it is not symlinked into /usr/local
You can try again using 'brew link node'
/usr/local/Cellar/node/0.4.9: 72 files, 6.8M, built in 2.5 minutes

A couple of things here.  First, go ahead and deal with adding the node directory to your NODE_PATH environment variable.  Second, fix the symbolic link error.  There's a thread in Homebrew issues that points out a solution for recursively changing some file permissions. I had to do this for two directories, then reapply the link:

$sudo chown -R <whateveruser> /usr/local/include/node
$sudo chown -R <whateveruser> /usr/local/lib/node
$cd /usr/local/include
$brew link node
linking /usr/local/Cellar/node/0.4.9... 68 links created

4. Install Node Package Modules (npm)

Note that the TileStream github instructions uses http, but that didn't work for me.  Sub https:

$curl https://npmjs.org/install.sh | sh
$npm install

I ran into some more permission issues when doing the npm install. Had to give the following permissions, then reran the install:

$sudo chown -R <whateveruser> /usr/local/lib/node_modules

5. Install TileStream

The -g option installs TileStream globally.  Omit the switch if you only drink local:

$npm install -g tilestream

6. Fire up TileStream

Simple:

$tilestream

Ugh, I thought I was there but got 'Error: cannot find module 'zlib'. Another dependent module needs to be installed:

$cd /usr/local/lib/node_modules
$npm install zlib
$tilestream

That should get TileStream running at http://localhost:8888. Refer to the TileStream install instructions for running on a specific host or ip. Not much to it.

7. Serve some MBTiles 

If you're not familiar with MBTiles, get up-to-speed because they are fast and more manageable than traditional map caching approaches. TileMill is used to author maps and export MBTile, so get it downloaded and you'll be provided some sample projects to publish.  For more details, check out this crash course.

I used the Control Room project and exported control-room.mbtiles to /Users/shane/Documents/MapBox/tiles.  TileStream will pick up the name of the MBTiles file in the tiles directory, so I can finally see the fruits of my labor at http://localhost:8888/map/control-room:

AFTERTHOUGHTS

Now the real fun begins with doing some custom development with MBTiles. There will be some more interesting posts later on that topic. The only other item to mention is that you can also use TileStache to serve up MBTiles. I chose to start with TileStream because it's part of the MapBox stack.

:!q