Day 8: Harp.JS--The Modern Static Web Server

So far in the 30 technologies in 30 days blog series, we have looked at Bower, AngularJS, and GruntJS JavaScript technologies. These latest technologies are designed and developed to make a developer's life easier and more productive. Today, we will learn another new JavaScript technology called Harp. In this blog post, we will start with the basics of Harp, and then we will create a simple Harp application, and finally deploy the application to OpenShift.

What is Harp?

Harp is an open source static web server for modern web applications. It can serve Jade, Markdown, EJS, CoffeeScript, LESS, Stylus as HTML, CSS, and JavaScript without any configuration.

As more and more development moves towards the client side, developers have started to use alternatives which gets compiled to native technologies. For example, instead of writing HTML we can use template libraries like Jade or EJS. Similarly, CoffeeScript can be used as an alternative to JavaScript, and for styling, Stylus and LESS can be used as an alternative to CSS.

It is a zero-configuration web server that is used to serve static assets. It has a built in asset pipeline for serving .jade, .markdown, .ejs, .coffee, .less, .styl as .html, .css, and .js.

Harp Prerequisites

Harp requires NodeJS and the NPM package manager which comes by default with node.js installations. You can download the latest version of NodeJS from official website. Once you have node.js and NPM installed, we will use the NPM system to install Harp.

Install Harp

To install Harp, just type the following command.

$ npm install -g harp

The command shown above will install the harp package globally, allowing the harp command to be available from any directory.

Create Harp project

The harp command line gives us the capability to create sample harp apps. To create an application, just type the harp init command.

$ harp init blog

This will create a directory named blog on the machine file system. The blog directory will have the following structure.

Harp application structure

The sample project created by harp uses Jade template engine for HTML and uses less for CSS.

Start the Harp server

We can run the application using the harp server command as shown below:

$ cd blog
$  harp server
 
          _____                    _____                    _____                    _____          
         /l    l                  /l    l                  /l    l                  /l    l         
        /::l____l                /::l    l                /::l    l                /::l    l        
       /:::/    /               /::::l    l              /::::l    l              /::::l    l       
      /:::/    /               /::::::l    l            /::::::l    l            /::::::l    l      
     /:::/    /               /:::/l:::l    l          /:::/l:::l    l          /:::/l:::l    l     
    /:::/____/               /:::/__l:::l    l        /:::/__l:::l    l        /:::/__l:::l    l    
   /::::l    l              /::::l   l:::l    l      /::::l   l:::l    l      /::::l   l:::l    l   
  /::::::l    l   _____    /::::::l   l:::l    l    /::::::l   l:::l    l    /::::::l   l:::l    l  
 /:::/l:::l    l /l    l  /:::/l:::l   l:::l    l  /:::/l:::l   l:::l____l  /:::/l:::l   l:::l____l 
/:::/  l:::l    /::l____l/:::/  l:::l   l:::l____l/:::/  l:::l   l:::|    |/:::/  l:::l   l:::|    |
l::/    l:::l  /:::/    /l::/    l:::l  /:::/    /l::/   |::::l  /:::|____|l::/    l:::l  /:::|____|
 l/____/ l:::l/:::/    /  l/____/ l:::l/:::/    /  l/____|:::::l/:::/    /  l/_____/l:::l/:::/    / 
          l::::::/    /            l::::::/    /         |:::::::::/    /            l::::::/    /  
           l::::/    /              l::::/    /          |::|l::::/    /              l::::/    /   
           /:::/    /               /:::/    /           |::| l::/____/                l::/____/    
          /:::/    /               /:::/    /            |::|  ~|                       ~~          
         /:::/    /               /:::/    /             |::|   |                                   
        /:::/    /               /:::/    /              l::|   |       Harp v0.9.4               
        l::/    /                l::/    /                l:|   |       Static Web Server           
         l/____/                  l/____/                  l|___|       By Chloi Inc. 2012-2013     
 
Your server is listening at http://localhost:9000/

Now, go to http://localhost:9000/ to see the running application.

harp sample app

Now open the index.jade file, and make the following change:

h1 Welcome to Harp.
h3 This is my blog. Enjoy.

Refresh the browser and we will see the change.

harp app with change

Deploy to the cloud

There are few alternatives to deploy harp applications as mentioned in the documentation. I will cover how we can deploy the sample application to OpenShift.

OpenShift is a public Platform as a Service, and you can use it to deploy Java, NodeJS, Ruby, Python, and PHP applications for free.

Before we deploy the application to OpenShift, we'll have to do few setup tasks :

  1. Sign up for an OpenShift Account. It is completely free, and Red Hat gives every user three free Gears on which to run your applications. At the time of this writing, the combined resources allocated for each user is 1.5 GB of memory and 3 GB of disk space.

  2. Install the rhc client tool on the machine. The rhc is a ruby gem so you need to have ruby 1.8.7 or above on your machine. To install rhc, just typesudo gem install rhc If you already have one, make sure it is the latest one. To update the rhc, execute the command shown below.sudo gem update rhc For additional assistance setting up the rhc command-line tool, see the following page: https://openshift.redhat.com/community/developers/rhc-client-tools-install

  3. Setup the OpenShift account using rhc setup command. This command will help us create a namespace and upload your ssh keys to OpenShift server.

After setup, we can create a new OpenShift application by running the following command.

$ rhc create-app blogonopenshift nodejs-0.10

This will create an application container for us, called a gear, and setup all of the required SELinux policies and cgroup configuration. OpenShift will also setup a private git repository for us and clone the repository to the local system. Finally, OpenShift will propagate the DNS to the outside world. The application will be accessible at http://blogonopenshift-{domain-name}.rhcloud.com/. Replace {domain-name} with your own unique OpenShift domain name (also sometimes called a namespace).

Next, change directory to the blogonopenshift folder, and initialize a new harp project.

$ cd blogonopenshift
$ harp init _harp

This will create the sample harp application in the blogonopenshift directory under _harp folder.

Update the package.json file in the blogonopenshift directory with harp dependency.

{
  "dependencies": {
    "harp" : ">=0.8"
  }
}

Then, use the Node Package Manager to install the dependencies:

$ npm install

Next, update the server.js with the following.

require('harp').server("_harp", { ip : process.env.OPENSHIFT_NODEJS_IP, port: process.env.OPENSHIFT_NODEJS_PORT})

In the code shown above, we create an instance of the harp server. We pass it the ip address and the port number which the server should bind to in OpenShift environment. In a cloud environment, the recommended practice is to use environment variables instead of hard coding values.

If we push the code to OpenShift, it will not work the first time. The reason is that harp API does not provide any option to configure the IP address. I have logged an issue in the harp github repository. For the time being, open the index.js file in node_modules/harp/lib directory and update the server function with the one shown below:

/**
 * Server
 *
 * Host a single Harp Application.
 *
 */
 
exports.server = function(dirPath, options, callback){
  connect.createServer(
    middleware.regProjectFinder(dirPath),
    middleware.setup,
    middleware.underscore,
    middleware.mwl,
    middleware.static,
    middleware.poly,
    middleware.process,
    middleware.fallback
  ).listen(options.port,options.ip ,  callback)
}

Now commit the code to the local git repository and then push the changes to cloud.

$ git add .
$ git commit -am "blogonopenshift app deployed to cloud"
$ git push

After the code is pushed, and the application is deployed on OpenShift, we can view the running application at http://blogonopenshift-{domain-name}.rhcloud.com. My sample application is running at http://blog-shekhargulati.rhcloud.com.

That is it for today. I hope it was useful. Keep the feedback coming.

What's Next

Image Source

http://www.flickr.com/photos/57139637@N04/5532885987/

$ npm install -g harp

I guess we need sudo before this command.

hi,

Im trying to deploy a static web server with harp on openshift but i'm dealing with a confusing error at boot time:

Harp You need root access to run this command. try sudo

my simple server.js:

require('harp').server( "www", {ip:process.env.OPENSHIFT_NODEJS_IP, port:process.env.OPENSHIFT_NODEJS_PORT || 8080});

Even if a log into openshift shell and open a node console to boot the server the error is the same:

[web-worizon.rhcloud.com repo]> node

require('harp').server( "www", {ip:process.env.OPENSHIFT_NODEJS_IP,port:process.env.OPENSHIFT_NODEJS_PORT || 8080}); undefined

Harp You need root access to run this command. try sudo

Any ideas why this is happening? E.