On Getting Started with Node.js, MongoDB and Heroku on Windows

I recently had the opportunity to see David Padbury present on Node.js at the New England Code Camp. An earlier version of his slides is available here. Recently while prepping for an upcoming presentation on Windows Phone 7 location services, I decided that I’d incorporate Node.js into my demo. This post will briefly introduce the technologies in its title and describe the process of getting them installed and running on a Windows box.

Node.js

Hopefully at this point, you have at least heard of Node.js. If you haven’t, stop what you’re doing right now and Bing it. Node is one of those disruptive technologies that’s going to change the way we build web apps in the years ahead. Well, it might not totally change how we build them. But things will start to look very different because of it.

OK, so what is Node.js? Node is an evented I/O web server. Such web servers use a single thread (yes, you read that correctly) to handle all requests and rely on non-blocking I/O and callbacks to achieve massive levels of concurrency. The operating system provides facilities for performing non-blocking I/O. Windows supports this feature via I/O Completion Ports. Basically, that single thread gets a request, sends it off to do something using non-blocking I/O, waits for a callback upon I/O completion and then sends the response.

MongoDB

It’s somewhat forgivable if you haven’t heard of Node.js. We all miss our exits from time to time. But MongoDB? There’s really no excuse for not knowing about this NoSQL staple! It’s an amazing product. But I’ll mention briefly that MongoDB is a document-oriented, schema-less database. JavaScript is used for queries and commands and documents are stored as BSON (Binary JSON). If you want more introductory material, check out my presentations.

Heroku

Heroku started out as a service for deploying Ruby on Rails apps to EC2, though recently they’ve expanded their offerings. Heroku now supports Node.js, Python and Java, among others. They offer a platform that allows your app to be deployed via a Git push. You get some basic web and database resources for free and pay as your app needs to scale out. It’s all seamless. AppHarbor offers a similar service for ASP.NET apps and is arguably simpler.

Installing Node on Windows

There isn’t an installer for Node. You simply grab the latest executable from http://nodejs.org/#download and drop it somewhere like c:\Program Files\Node\Node.exe. Add the directory to your path. Open up cmd and type node. You should get the interactive node console. I won’t bother reposting the “Hello, World!” exercise. But you should go through the exercise either in the interactive shell or by simply working in a text editor and creating a JS file and then running “node yourfile.js” from the command line.

OK, I’ll re-post so you don’t have to click over.

1
2
3
4
5
6

var http = require('http');
http.createServer(function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('Hello World\n');
}).listen(1337, "127.0.0.1");
console.log('Server running at http://127.0.0.1:1337/');

Save that code snippet to a file hello.js and run “node hello.js”

Browse to http://localhost:1337 and Node should respond with the expected “Hello, World!” response. What’s most exciting about this exercise is that Node is running on Windows, thanks to Microsoft. Be warned that if you scroll to the comments in that post, there are some clear Linux zealots who say some dumb, dumb things about Microsoft. Don’t get me wrong, I have a dual boot of Ubuntu and Win7 on one of my Vaios. But I hate the “MS can’t do anything right crowd.” Leaving the soapbox…

Installing NPM on Windows

OK, so bare bones Node is now running. To do more, you’ll need to grab some of the numerous node modules. As Nuget is to .NET, NPM is to Node. For a young framework, Node has a shockingly rich package library accessible via NPM. Keep in mind, NPM on Windows is considered experimental.

Installation requires Git, so make sure you have that installed. Once you do, run the following commands:

git clone --recursive https://github.com/isaacs/npm.git npm
cd npm
node cli.js install npm -gf

Make sure you didn’t skip that –recursive step. Things break if you do. Also keep in mind that if your Node.exe directory is under Program Files, that’s protected by Windows and you’ll need to run cmd as an admin. The NPM installation creates files in the Node.exe directory. You can test your installation by grabbing the express web framework for Node.js.

npm install express

Creating a Heroku Node.js App

The first thing you need to do is create an empty git repository in the directory in which you’ll create your app.

git init

After you’ve created your Heroku account and the git repo, you need to install the Heroku client. Once you’ve done that, open a command line and enter:

heroku login

You’ll be prompted to enter your email and password. After you successfully authenticate, you should receive a message that you need to either upload an existing SSH public key or create a new one. If you haven’t created an SSH key before, you can also use ssh-keygen to do so.

Next, open your text editor of choice and create a .js file named client.js (or whatever you want to name it). Add the following code (from Heroku’s Node quick start docs).

1
2
3
4
5
6
7
8
9
10

var express = require('express');
var app = express.createServer(express.logger());
app.get('/', function(request, response) {
  response.send('Hello World!');
});
 
var port = process.env.PORT || 3000;
app.listen(port, function() {
  console.log("Listening on " + port);
});

Note that this snippet assumes you’ve used NPM to install express as outlined above. You can test the code by running:

Node.exe client.js

and browsing to http://localhost:3000.

Next, you’re going to need to create a package.json file to tell Heroku which dependencies your app will need. The file should look like below (current version of express is 2.5.0, yours might vary).

1
2
3
4
5
6
7
8

{
  "name": "your-app-name",
  "version": "0.0.1",
  "dependencies": {
    "express": "2.5.0",
    "mongoskin" : "0.1.3"
  }
}

From the directory where your node app lives, run the following command:

npm install

Because this command copies dependencies locally into your directory structure, you’ll want to add the following line to your .gitignore file. Heroku will use NPM to manage your dependencies on the server side.

node_modules

Next, create a file named Procfile (case sensitive) with no extension. Its content should be:

web: node client.js

This file will tell Heroku to start a web process using node to run client.js.

Next, you’ll want to create the app on Heroku, using the cedar runtime stack. The runtime stack is basically just the Heroku environment config (OS, installed libraries, etc.).

heroku create --stack cedar

This will create an app with a unique name, which you can rename to something more meaningful via the following command:

heroku rename mymeaningfulname

Heroku also creates a git remote for you, so you can push your code to Heroku.

git push heroku master

One last step to get your app running on Heroku.

heroku ps:scale web=1

This command will start a web process, which you can verify is running with the following command:

heroku ps

Browse to http://yourmeangingfulname.herokuapp.com to see that your Hello, World! app is indeed running.

MongoDB and NodeJS

There are several options for using MongoDB with Node.js. The native driver is accessible via NPM (npm install mongodb). But don’t start here. While the driver is powerful, it requires maddeningly dense code to use. Your closures will have closures will have closures will have closures…

Mongoose looks promising and simpler. It’s a full ORM style Document Mapper. But for a quick start, I prefer Mongoskin. It’s succinct and easy to use. It doesn’t offer all of the document mapping features of Mongoose, but I’m pretty sure it has the lowest barrier to entry for using MongoDB on Node.js.

npm install mongoskin

On Windows, you will likely see a message from NPM that it is “Not building native library for cygwin” followed by “command not found” and “unary operator expected” errors. I admittedly don’t know what the cause or meaning of these errors is, but they can be ignored for dev.

After installing mongoskin, modify your client.js file so it looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

var express = require('express');
var mongo = require('mongoskin');
 
var app = express.createServer(express.logger());
 
 
app.get('/', function(request, response) {
	var conn = mongo.db('mongodb://localhost:27017/yourdbname');
	conn.collection('users').find().toArray(function(err, items) {
		if (err) throw err;
 
		response.send(JSON.stringify(items));
	});  
});
 
var port = process.env.PORT || 3000;
app.listen(port, function() {
  console.log('Listening on ' + port);
});

This code assumes you have MongoDB running locally and that you have a collection named users with at least one document inserted. Restart your server (Ctrl+C your running Node and rerun node client.js). Browse again to the app and you should see the JSon output.

MongoHQ and Heroku

MongoHQ is a hosted Mongo solution that offers integration with Heroku. You can enable it by navigating to your app in the Heroku admin and clicking on “Add-Ons” in the upper right hand corner. There’s a free version you can get started with (note, this requires a credit card though you’re not billed).

Click through to the MongoHQ admin pages and create a user and get your connection string. Update the line in client.js that creates the connection so it looks something like:

var conn = mongo.db('mongodb://USER:PASSWORD@SUBDOMAIN.mongohq.com:PORT/DBNAME');

That should be it. Now commit and push.

git add .
git commit -m "Commit message"
git push heroku master

Browse to your app and you probably see nothing. Using the MongoHQ admin pages, you can create the “users” collection and add a document. If you do that and refresh, you should see the JSON formatted user document.

Summary

Now that Node.js runs on Windows, devs need to take a serious look. Microsoft is not ignoring this technology and neither should those of us who develop Windows based apps. This walkthrough hopefully gets you familiar with the tools and technologies you need to get started. Heroku isn’t runnign Windows and it certainly isn’t necessary for running node, but for a sandbox it’s generally pretty useful to have.

At some point, I plan to get Node and MongoDB running on Azure. When I do, I’ll post about that too.