Persevere on Heroku

It is becoming increasingly popular to deploy Node.js-based applications to Node-friendly hosting services to take advantage of the pre-built, reliable, robust architecture and infrastructure these services provide. Persevere, a JavaScript server framework for developing RESTful applications on Node.js, is an excellent fit for these types of hosting services. In this post I will show you how easily a Persevere application can be built and deployed on one such service, Heroku, but the process can be easily replicated on other providers that offer similar functionality.

Creating an application

To begin with, you will need to create a free Heroku account, and then download and install the Heroku toolbelt tool suite. Next, create a git repository for your application and use the heroku command to initialize the application itself. You will need to give your application a unique name; we’ll use “appname” for this example:

git init
heroku apps:create appname

We can bootstrap our Persevere application with the Persevere template or the Persevere example application. To use the template, we could simply pull it into our application’s git repository:

git pull https://github.com/persvr/persevere-template master

The template is complete enough that we could push it to Heroku and have a running server, but since it doesn’t have any data models or pages, it is not very interesting. You can read the Persevere documentation for more information on setting up data models and other aspects of building an application. The Persevere example application is more complete, so we’ll use it instead:

git pull https://github.com/persvr/persevere-example-wiki master

Create a Procfile in your application repository that contains the single directive:

web: node index.js

Commit this with git and then push it to Heroku:

git push heroku master

After a successful push, Heroku will automatically install all the dependencies specified in the package.json file that was included in the example application. We can ensure that at least one web process is running with:

heroku ps:scale web=1

Your application should now start up. Persevere is setup to serve on the port specified by the PORT environment variable, which Heroku provides, so Persevere automatically starts on the correct port to interface with Heroku. You can verify this by looking at the Heroku logs:

heroku logs

You can test the application by visiting http://{appname}.heroku.com with your browser (replace {appname} with the unique name selected for your application). If the example wiki starts up properly, you should have an option to create/edit a new page (and to register and login as a new user) at the redirected URL.

Switching data stores

One of the benefits of Persevere is that we can actually start creating and prototyping an application with the default, fully functional JSON file-based store (which stores all data in memory and records changes to disk), and then later upgrade to a more robust, scalable database if needed. This can be as simple as swapping in a different data store. With Heroku, we can easily add MongoDB as an addon (I used MongoHQ) through the web interface or with the command:

heroku addons:add mongohq

Note that although the use of MongoDB is free for small applications, Heroku requires you to add a credit card to your account to verify it.

To use Persevere’s MongoDB object store connector, we add the mongodb-store package to the dependencies of our package.json:

  "mongodb-store": ">=0.1.1"

In the example wiki application we can swap out our data store for MongoDB by opening up the model/page.js module and assigning the value of the pageStore export of the page-mongo module to the pageStore variable (this is actually already available in the comments):

var pageStore = require('./page-mongo').pageStore;

To use MongoDB on Heroku, we also need to modify mode/page-mongo.js. Edit this file and set the url variable to process.env.MONGOHQ_URL. Look at the rest of model/page-mongo.js to see how the MongoDB store is setup. Basically, a new store instance is constructed with the name of the collection you wish to use. When deployed on Heroku, Persevere will automatically detect the MongoDB URL, and the collection you specify will be created:

var MongoDB = require("mongodb-store").MongoDB,
    myStore = MongoDB({collection: "collection-name"});

Finally, we commit and push again with git, and our application should start up with a connection to MongoDB. Any new pages created in the wiki will now be stored in the MongoDB database. We don’t have to make any further changes to the application; Persevere will map data manipulation operations as well as RQL queries to MongoDB so they can be used in the same way as with the default store.

Hopefully this example gives you an idea of how easily Persevere applications can be deployed to NodeJS hosting services, taking advantage of Persevere default settings, NPM installation capabilities, and switching to hosted add-on database services when appropriate. Let us know if you have any questions.