Hacking Heroku with Custom Build Packs

A little known fact about Heroku's cedar platform is that it's capable of even more than advertised (and that's already a long list: Ruby, Node.js 0.4.7, Scala, Java, Clojure, Python/Django, etc). Here's how to customize a cedar "buildpack" to compile the latest version of Node.

First, you need to start by forking their buildpack repo on Github. Luckily, they've provided a readme to help get you going, but they failed to point out that you'll need to install the vulcan gem to run the build scripts. So, start off by running

$ gem install vulcan

Vulcan is a remote build management tool that generates the binary files heroku uses to quickly bootstrap its platforms. This saves a huge amount of time when booting up your application the first time, since you're skipping a potentially lengthy compile.

You'll also need to have an Amazon AWS account with S3, so make sure you have your [API keys handy aws-api and have created an S3 bucket for your build files.

The buildpack readme instructs you to set your AWS credentials as shell variable and run their packing scripts with the Node and NPM versions you want to compile, too bad the readme skips a crucial dependency.

First you need to create a build platform to compile your binaries on:

$ vulcan create wookie-test

This will create a cedar platform, so the output will look familiar to heroku users.

Now you're ready to do what the readme sez:

$ export AWS_id=xxx AWS_SECRET=yyy S3_BUCKET=zzz
$ s3 create $S3_BUCKET
$ support/package_node 0.6.2
$ support/package_npm 1.0.106

*make sure that the bucket you choose has public read permissions!

BOOM! Check your S3 bucket and you should see 3 files in there:


In case you were wondering, scons is a python scripting tool for handle cross platform dev ops and systems engineering tasks, which is a dependency of heroku platforms. This file gets generated as part of the Node build script, and unless you work at heroku you probably won't have reason to bump this version number any time soon.

Now its time to modify and commit the version number's you compiled into the bin/compile script in your build pack. Push those changes up to github and you're almost ready to go. My fork of a Node 0.6.2 + NPM 1.0.106 buildpack is viewable on github.

And now for the big finish!

In any Node 0.6.x compatable project, run

heroku create --stack cedar --buildpack

If all the stars have aligned and the heroku gods are smiling on you, you should see custom version of Node boot up in cedar platform and start your app.

-----> Vendoring node 0.6.2

The best part about this is that now your buildpack is open source and everyone can use it! Please test out my custom Node build pack for yourself and happy hacking on Heroku!

================ Update:

[12/1/11] – @ddollar (the author of the buildpack repo) pointed out that there's a a Version detection branch that will autodetect the right Node version based on your package.json file. IMO that's what you should be using!