Production deployment using a PaaS

Heroku

Heroku has great documentation on creating apps either through their website or using their Heroku Toolbelt CLI app. In this guide we'll use the toolbelt for simplicity. Once you have the toolbelt installed, you'll also need a Heroku account in order to create and deploy apps.

Make sure you are using git

Heroku uses git to deploy applications. If you haven't already started using git for your project's source control, initialize it as a git repository now:

$ git init
$ echo 'node_modules' > .gitignore
$ git add .
$ git commit

Create an app (more information)

In your ac-koa-hipchat project directory, run the following toolbelt command to create an app on Heroku:

$ heroku create <your-really-unique-app-name>

Create or verify your Procfile

Heroku uses a Procfile to start your app. Make sure your project has a file called Procfile in the root directory with at least the following content:

web: node --harmony web.js

The --harmony flag makes sure that your Node.js 0.11.x runtime allows ES6 syntax, particularly generators.

Set environment variables

At a minimum, you'll need to put your app into production mode for it work properly on Heroku. This can be done by setting the following environment variable via the toolbelt's config command.

$ heroku config:set NODE_ENV=production

Configure your production mode base URL

In the production mode settings of your package.json, set your heroku app's name in the localBaseUrl field. We'll configure the remaining fields in that section later on.

  "production": {
    "localBaseUrl": "https://your-really-unique-app-name.herokuapp.com",
    ...
  },

Add a storage add-on

Unless you've written your own ac-node-compatible store, you'll need to add either a Redis or Mongodb add-on to your Heroku app. Which you choose for your app is generally immaterial for simple applications, but if your app needs to do additional data storage and wishes to use the simple, built-in tenant-aware key-value store, then you'll likely be more productive using Mongodb. Of course, your app can also use any additional storage solution you like, though you then need to manage your own tenant-based data partitioning. Doing so is left as an exercise for the reader ;)

Adding a Redis storage engine

Several Redis add-on providers are available through Heroku, but one of our favorites has been RedisCloud. You can add it as follows:

$ heroku addons:add rediscloud

This will add a REDISCLOUD_URL environment variable to your app's config. You then need to make sure that your app's production mode settings are configured to read this value. Your package.json should look something like this:

  "production": {
    "localBaseUrl": "https://your-app-name.herokuapp.com",
    "redisEnv": "REDISCLOUD_URL",
    "port": "$PORT"
  },

Adding a Mongodb storage engine

Several Mongodb add-on providers are available through Heroku, but one of our favorites has been MongoHQ. You can add it as follows:

$ heroku addons:add mongohq

This will add a MONGOHQ_URL environment variable to your app's config. You then need to make sure that your app's production mode settings are configured to read this value. Your package.json should look something like this:

  "production": {
    "localBaseUrl": "https://your-app-name.herokuapp.com",
    "mongoEnv": "MONGOHQ_URL",
    "port": "$PORT"
  },

Unfortunately, MongoHQ no longer offers a free base package. If you want to use a free storage engine to get started, Mongolab is a good alternative. Mongolab's management console is not as nice to use as MongoHQ's, but works fine for starter projects.

Adding other add-ons

It's useful, but not required, to add a few additional Heroku add-ons to your app. We recommend considering the following:

Logentries for easier access to your app's logs
Keen.io to collect analytics -- see ac-koa-hipchat-keenio
New Relic to keep your app awake and monitor app health

Deploy it! (more information)

Your app should now be configured sufficiently to deploy.

First, make sure that you've committed all of your changes to git:

$ git add .
$ git commit

Next, you should be able to deploy the app to Heroku with a git push:

$ git push heroku master

If you have problems with that command, double check that heroku has been configured as a git remote. This should have happened when you created your Heroku app with the toolbelt, but if it hasn't, add it now with the following command:

$ heroku git:remote -a your-really-unique-app-name

Then re-run the push command.

Start a dyno to serve your app (more information)

Finally, you need to scale your app up to run at least one web dyno. Run the following command:

$ heroku ps:scale web=1

When that completes, you should now be able to access your app's descriptor. Verify that the following returns the appropriate JSON:

curl https://your-really-unique-app-name.herokuapp.com/addon/capabilities

FAQ

Help, I'm getting a Node.js build error while deploying!

If you get errors about the latest Node.js not building during your deploy to Heroku, you may need to set a version that is known to build without errors (some of the latest unstable releases of Node.js have not been compatible with Heroku). Make sure that your package.json specifies an exact version that is know to build on Heroku. As of this writing, the latest working build is 0.11.15:

  "engines": {
    "node": "0.11.15"
  },

How can I see my app's log output?

You can access a near-realtime feed of your app's log in a terminal with the following toolbelt command:

$ heroku logs -t

If you've added the Logentries add-on, there's also a web UI you can access via your app's Heroku web console.

My app keeps falling asleep, making it a pain to install and slow to respond!

If your app does not receive any requests for 30 mins and is only running a single 1x dyno, Heroku will put it to sleep. It can often take more than 5s for the app to wake up, which can cause the HipChat add-on installation process to timeout, making it troublesome to install infrequently used add-ons. Waking from sleep also can make your add-on slow to respond if it doesn't have a high volume of traffic.

The simplest solution to this problem is to give it a second dyno, or upgrade its 1x dyno to a 2x dyno. Since this costs money, you may hesitate to do that, though. Fortunately, you can add and configure the New Relic add-on to automatically ping your app every 30s as part of its monitoring solution, which will keep the app awake.

How can I monitor my app's health?

The Logentries add-on actually comes with a quality set of automatically configured alerts based on Heroku's log, even with its free offering. If you want pretty graphs, other add-ons exist for this purpose such as New Relic. If you run 2 dynos of any type (not free), Heroku also offers a basic but useful metrics web console for your app for no additional charge (beyond the price of the second dyno).

Wiki

ac-koa-hipchat / Paas Deployment