home | articles | site map | contacts
about us
consulting
client login
support
contacts
Creating Your First Node.js App in Windows with Heroku Hosting
8/6/2012
Follow PrimaryObjects on Twitter Subscribe to Primary Objects via RSS More Software Articles
by Primary Objects
enter email address
 

Introduction

Many Windows developers are currently developing web applications with the most popular Microsoft technology stack of C# ASP .NET. As technologies evolve, and especially with the advent of mobile platforms and alternative operating systems, new programming technology stacks emerge to fit new needs. One of the latest new tech stacks that is receiving a good degree of popularity is Node.js, a server-side javascript framework.
 
Just as C# ASP .NET is used for developing Windows-based web applications (hosted on a Windows server with IIS), Node.js can be used for developing javascript web applications, hosted on a variety of platforms. Node.js provides its own server, separate from IIS, for hosting web applications. While you can run Node.js locally to both debug and host Node.js javascript web applications, you can take full advantage of the Node.js stack by shifting to cloud-based hosting with Heroku. In fact, you can even take it one step further and move the entire IDE and development cycle into the cloud with the Cloud9 IDE.
 
In this tutorial, we'll walk through the steps of creating your first Node.js javascript web application. We'll run the web application locally, for debugging purposes. We'll then push the code to a remote Git repository on Heroku to deploy our web app live for the public. As a final bonus, we'll walk through the steps of editing code using the Cloud9 IDE and pushing directly to Heroku to update our app.
 

First, a Few Definitions for the .NET Developer

For ASP .NET developers, there are a few terms and technologies that need defining. As with any new technology stack, there is a learning curve involved. We'll be using the following technologies in this Node.js Heroku tutorial:
 
Node.js: A server-side javascript programming framework that allows you to create web applications purely in javascript.
 
Express.js: A node.js web application framework that wraps a lot of the nuts and bolts in creating a typical javascript web application (initialization, MVC routing, integration, etc).
 
Jade: A template engine for writing the views for our node.js MVC web application. Jade is similar to Razor in MVC ASP .NET, but with different formatting. Jade provides simplified HTML coding and allows omitting closing tags through the use of tabs for indentation (to mark begin/end blocks in HTML code).
 
Heroku: A cloud-based application platform for hosting web applications that were developed in a variety of languages. Heroku provides hosting for web apps written in Ruby, Java, Python, Scala, and of course, Node.js. One of the most appealing features of Heroku is its open-source friendliness with its free-plan pricing structure.
 
Cloud9 IDE: A web-based IDE (integrated development environment) for writing javascript applications. Cloud9 provides an online editor with code formatting, color coding, debugging, breakpoints, a sample web server for running the apps, and integration with Git for commits and publishing code.
 
Git: A versioning system for keeping track of file changes. Similar to SVN (and TFS, with respect that they're both version control systems), Git allows pushing and pulling code from and to local or remote repositories. A local repository can be created in a simple folder in Windows. Any folder can have its own repository. Git also supports remote repositories. Heroku provides a Git repository that you can commit to. GitHub and BitBucket also provide Git repositories for online storage of code.
 

Installing the Tools in Windows

Before we get started, we'll need to install the required software for creating a node.js web application, committing to a Git repository, and working with Heroku. We'll start with Git.
 
1. Install Git, the server software
 
2. Install a Git client (for creating repositories, committing files, and working with Git). I recommend using Tortoise Git for Windows
 
3. Install Node.js
 
4. Create an account on Heroku, for hosting your node.js app
 
5. Install the Heroku tools, for creating projects, hosting, and configuring
 
6. Open a command prompt in Windows with administrator access (type cmd, right-click the result and select Run As Administrator).
 
7. At the command prompt, type: npm login
   Enter your Heroku account email address and password.
   This will log you into the Heroku toolkit so that you can publish your files to the server.

Setting up Heroku

With the tools installed, we'll now need to configure Heroku with an SSH key for publishing our files. First, we'll generate a key and then we'll add it to our Heroku account.
 
1. Run Puttygen in Windows (installed with Git). You can do this by clicking Start and typing: puttygen
 
2. In Puttygen, click the Generate button to create an SSH key.
 
3. Click Save Private Key and choose Yes when prompted if you wish to save the key without a password (you can choose to enter a password, if you wish, but for the sake of simplicity with this tutorial, we'll choose not to create one).
 
4. Save the file as heroku_key.ppk to any folder of your choice.
 
5. Copy the key text from the textbox, paste it into Notepad, and save it to C:\Users\[username]\.ssh\id_rsa.pub (if a file already exists, overwrite it).
 
6. Run Pageant in Windows (installed with Git). You can do this by clicking Start and typing: pageant
 
7. Right-click the pageant icon in the system tray next to your clock and click Add Key.
 
8. Select heroku_key.ppk that you saved in step 4 above and click Open.
 
9. At the Windows command prompt, type: heroku keys:add (this will let you add the key to your Heroku account)
 
10. At the Windows command prompt, type: heroku create (this will make a new app url). Copy the git: url in the output and save it for later. You'll need this in order to save your files into your repository for publishing. If you forget the url, you can find it in your Heroku account, online.
 
11. In Windows, create a folder for your code files.
 
12. At the Windows command prompt, navigate to the folder you created in step 11.
 
13. Type: npm install express jade stylus (this will install the Express, Jade, and Stylus libraries for node.js)

Creating our First Node.js Application: Hello World

With our tools installed and our working environment created, we can begin writing our first node.js code file. In Windows, open the folder you created in step 11 above and create a new file named "helloworld.js". Type the following code into the file:
 
var express = require('express');
var app = express.createServer();

app.get('/', function(req, res) {
res.send('Hello World!');
});

// Get port from heroku, otherwise use 3000.
var port = process.env.PORT || 3000;
app.listen(port, function() {
console.log("Listening on " + port);
});
The above code uses the Express framework to simplify our node.js web application code. We first reference the required api (Express). We then establish a route to the root url /. When a user accesses the root url, we'll print the text "Hello World!" to the web browser. The final block of code tells the Node.js web server to listen on a configured port for incoming connections to our web application.

Running our First Node.js Web Application

The above code was quite simple. Now it's time to run our web application in the web browser. We can do this by executing node.js on our javascript file, as follows:
 
1. In Windows, open a command prompt, navigate to your project folder, and type: node helloworld
   This should begin running your helloworld.js web application.
 
2. Open a web browser and navigate to http://localhost:3000
   You should see your web applicaiton running, displaying the text "Hello World!".

All The World's a Stage

We've successfully ran our node.js web application locally and loaded the page in our web browser. Now it's time to publish the code to our Heroku server for the world to see. We'll first need to create two configuration files for Heroku, as follows:
 
1. Create a file in your project folder, named package.json with the following contents:
{
  "name": "helloworld",
  "version": "0.0.1",
  "dependencies": {
    "express": "2.5.x"
  },
  "engines": {
    "node": "0.8.x",
    "npm": "1.1.x"
  }
}
2. Create a file named Procfile. It must contain a capital 'P'. In Windows, you can first save a file from Notepad as "procfile.txt" then rename it to "Procfile" in the Windows Explorer. It should have the following contents:
 
web: node helloworld.js
 
3. Test Heroku locally, by opening a command prompt with Administrator access, navigate to your app's folder, and type: foreman start
 
4. Open a web browser and navigate to http://localhost:5000
   You should be able to see your web application running, displaying the text "Hello World!"

Committing to Git and Publishing to Heroku

With Heroku setup locally and our code ready to deploy, it's time to commit our code to a Git repository and publish it live. We can do this as follows:
 
1. Create a new Git repository in your app folder by right-clicking the folder in Windows and selecting Git Clone.
 
2. In the Git clone dialog, for the field "URL:", paste the Git url that you copied from Step 10 above under "Setting up Heroku". Click OK to clone the repository.
 
3. Move the files that you created for the project into the new Git folder.
 
4. Navigate into the new folder.
 
5. Create a new text file named .gitignore with the following contents:
node_modules
 
6. Right-click in the folder and click Git Commit -> master.
 
7. Enter a description for the message, checkmark all files (.gitignore, Procfile, helloworld.js, package.json), and click OK.
 
8. To publish to Heroku, right-click the folder again and select TortoiseGit->Push. Under "Destination", select "Remote" and verify the drop-down is set to "origin" (which points to Heroku). Alternatively, you could edit the field "Arbitrary URL" and paste the Git url that you created earlier in this article). Click OK to commit.
 
9. Open a Windows command prompt and navigate to your project's Git folder. Then type: heroku ps:scale web=1
 
10. Your node.js web application should now be running live! Navigate to your app's url (you can find it in your heroku account on the web site)

Moving From Notepad to the Cloud

In the above example, we created our first node.js web application file helloworld.js using Notepad in Windows. We can take our development environment to the next level with a complete IDE, including debugging for javascript, with a variety of tools. For this tutorial, we'll integrate with Cloud9, a cloud-based javascript IDE for node.js.
 
1. Create a Cloud9 account
 
2. On your dashboard, click the "Show your SSH key" link, along the right-side.
 
3. Copy the SSH key text and paste it into Notepad. Save the file as C:\Users\[username]\.ssh\cloud9.pub
 
4. Open a command prompt in Windows and type: heroku keys:add
   Select the file cloud9.pub that you saved from step 3 above.
 
5. In Cloud9, click Create New Workspace and choose Clone From Url.
 
6. Paste the Git url for your Heroku project (you can find it in your Heroku account, under My Apps).
 
7. Click Start Editing.
 
8. At the Cloud9 command prompt, type: npm install express
 
9. Double-click helloworld.js and modify the text for "Hello World!", such as changing it to "Hello World, modified by Cloud9 IDE".
 
10. Click the Run icon and double-click the .js file to run. You can then browse to the Cloud9 debug url to see it in action.
 
11. Click Stop to end debugging.
 
12. To commit the changes, at the Cloud9 command prompt type: git commit -m -a
    Then type: git push
 
You can now load your Heroku-hosted node.js javascript web application URL to view the changes live.
 
 

About the Author

This article was written by , Microsoft certified software developer and architect, providing C# ASP .NET web application development, database design, and mobile software development across a variety of domains for clients in both the business and consumer sectors.

   
comments powered by Disqus
Profile
Learn more about Primary Objects and our goals ..  More
12/28/2012
Primary Objects publishes node.js app, RedAnt, a REST web service .. More
09/21/2012
Primary Objects publishes node.js app, CD Early Withdrawal Calculator .. More
Home | About Us | Services | Client Login | Job Opportunities | Contact Us
Copyright © Primary Objects 2013
Privacy Policy
Follow us on Twitter