Cacher is the code snippet organizer for pro developers

Hosting Zappa on Heroku

Node.js and Express are awesome.
Coffeescript is awesome.
Zappa is awesome.
Heroku is awesome.
So I wanted to pile all those buds together to host some little sites.

Here’s a description of how I got started:

The tools:

Install node using nvm. (how to install.)
nvm - node version manager. Make it easy to install different versions of node on your machine. It’s worth it.(how to install.)
npm - node package manager. You’ll need this to install zappa and its dependencies. (how to install.)
Heroku. Install the Heroku gem. (how to install.)
Git. You’ll definitely need git. (how to install.)
Foreman. Foreman is a nifty little gem that runs processes in an intuitive way. Heroku requires it.(how to install.)
I pretty much assume you’re running a unix/linux operating system.

You’ll need a Zappa app. Hello world is wicked easy:

port = Number(process.env.PORT || 3000)

require(‘zappa’) port, ->

get ‘/’: ‘hi’ 

Plop that code into a file called test.coffee. The main trick here is making sure that the port is passed to Zappa as a number. Here we cast the variable port as a number since process.env.PORT returns a string.

Zappa recognizes numeric arguments as ports and string arguments as a host. And heroku needs the port to be set to process.env.PORT because they change the port the app is listening on each time you push the project to heroku.

I got totally stumped on this process.env.PORT business when I first tried this out, but luckily the creator of Zappa is a friendly and helpful troubleshooter.

UPDATE: As of August 21, 2011, if you pull the latest changes from the zappa github source there’s a fix from helpful dude Tim Shadel that makes it so you can pass any number-castable string to the port and Zappa will recognize it as an actual port number, without having to cast it as a number yourself. That’s pretty cool.



That means a hello world app can be as simple as this:

port = process.env.PORT || 3000

require(‘zappa’) port, ->

get ‘/’: ‘hi’ 



Next, you’ll need a package.json file:

{

   "name": "zappa-test",
   "version": "0.0.1",
   "private": true,
   "dependencies": {
     "zappa": ">= 0.3.x",
     "coffee-script": ">= 1.1.x"
   }, 
   "engines": {
     "node": "0.6.x",
     "npm":  "1.0.x"
   }
}


Heroku needs to know all the dependencies for your app to be able to run it. Zappa has a bunch of dependencies that will get included recursively, but I’m pretty sure coffee-script has to be listed here. If not, let me know.

Also, note the “engines” section. Heroku now supports multiple versions of node and npm, and this is how you tell Heroku which versions your app runs on.



Foreman requires a Procfile:

web: coffee test.coffee

All you need is that one line in a file named Procfile. Here you’re telling foreman: “Hey foreman, I’ve got a web process that needs to run. The command is coffee, the filename is test.coffee. Can you take care of that for me?” And foreman says: “Oh yeah, you’ve got it buddy.” At this point, it would be worthwhile to have foreman installed on your machine so you can test to make sure the app and the Procfile are working properly.



About WebSockets:

Heroku doesn’t support WebSockets yet. In a previous version of this post a friendly reader named Matt Hickford left a comment with this fix:

Heroku doesn’t support WebSockets. You need these lines in your app or socket.io will die:


@io.set ‘transports’, [‘xhr-polling’]
@io.set ‘polling duration’, 10
`@io` because I’m using zappa 0.3.x



Now, git that shit up:

git init
git add .
git commit -m ‘first!’



And tell Heroku all about it:

heroku create —stack cedar
git push heroku master



It’s really important to include —stack cedar. That’s currently the only Heroku stack node.js runs on.

Unless something wonky happened, that should be it.

Run heroku open to check out your app. I hope these instructions didn’t suck. If I’m missing anything or if you find anything in here totally wrong let me know in the comments.


UPDATED:

Restored the blog post after tumblr crunched the original version of this blog.
Included socket.io info based on an old comment from Matt Hickford and the heroku docs.
Added some new info about passing the port of an app to Zappa.