LifeinTECH

I use Heroku a lot to build, deploy and scale web applications. I’m also a big fan of their “pipeline” feature, which enables you to easily manage different instances (e.g. DEV, STAGE, PRD) of your application across the development lifecycle.

One challenge with pipelines is that DEV and STAGE applications are not inherently secured, meaning they are available to the public. In certain scenarios this would be a problem, as content displayed in DEV or STAGE may not yet be finalised or have the required approvals.

As a result, I (and some friends) built a Node Web Accelerator which includes authentication using the Force.com PassportJS strategy. We also included Handlebars and New Relic, which are common dependencies when building web applications.

You can find the Web Accelerator on GitHub (pull requests welcome).

Web Accelerator Architecture

Node + Express:

The Web Accelerator is built on Node / Express.

Node.js is a JavaScript runtime built on Chrome’s V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient. It also includes the Node.js package ecosystem (AKA npm), which is the largest ecosystem of open source libraries in the world.

Express.js is a Node.js web application server framework, designed for building single-page, multi-page, and hybrid web applications.

Handlebars:

Handlebars.js is a semantic web template system, allowing you to build clean logic-less templates based on the Mustache Templating Language.

PassportJS:

Passport.js is an extremely flexible and modular authentication middleware for Node.js. By default, the Web Accelerator uses the Force.com Strategy, which means it uses Force.com as the identity provider. Force.com was chosen as it has a compressive set of identity capabilities and is easy to integrate with. You can also grab yourself a free Force.com Developer Edition org for testing.

Sessions are managed by Heroku Redis, which enables the Web Accelerator to scale beyond a single Heroku dyno. Redis does not require any configuration, simply add it to your application as an add-on.

Heroku Config Variables:

The Web Accelerator follows the best practices of Twelve-Factor App methodology. For example, all environment variables are maintained as config variable in Heroku, making the application very portable, flexible and easy to setup.

New Relic APM:

Although not a requirement, the Web Accelerator also includes New Relic APM for application monitoring. Simple add the add-on and configure the config variable.

Getting Started

Before you start, if you plan to use the Passport.js Force.com Strategy, you will need to first create a “Force.com Connected App”. This will provide you with a unique “Client ID” and “Client Secret”, which will be added to your Heroku app config variables.

Now you can clone the Web Accelerator repository and push it to Heroku.

Add the config variables (highlighted below) from the application settings tab in Heroku.

AUTH_REQUIRED = true / false
CF_CALLBACK_URL = https://.herokuapp.com/auth/forcedotcom/callback
CF_CLIENT_ID = Force.com Connected App ID
CF_CLIENT_SECRET = Force.com Connected App Secret
COOKIE_SECRET = Any Value
LOG_LEVEL = combined
NEW_RELIC_LICENSE_KEY = New Relic License Key
NEW_RELIC_LOG = stdout
REDIS_URL = Redis URL
SF_AUTHORIZE_URL = https://.salesforce.com/services/oauth2/authorize
SF_TOKEN_URL = https://.my.salesforce.com/services/oauth2/token

Finally, add your code / content to the Web Accelerator. This is as simple as adding files to the following folders:

views = Handlebars Pages (HTML)
views/layouts = Handlebars Layouts
views/partials = Handlebars Partials
public = Unauthenticated Static Assets (CSS, Fonts, JS, IMG)
private_static = Authenticated Static Assets (CSS, Fonts, JS, IMG)

Anything added to the public and/or private_static folders will automaticlly be served. Pages added to the views folder would need to have a route defined in the routes/authenticated-routes.js file.

That’s it! The application will now be served when you hit your Heroku app.