Generating static sites with Cabin and Cloudant

By Max Thayer

Cabin is a static site generator (that is, blogs, homepages, info sites, etc) that uses grunt to compile assets into static web pages. This breaks your deployment process into this:

grunt deploy

... and your site is live! Since it's all static files, you can host your cabin on Cloudant. Here's how:

4-line deployment

Use this fork to create and deploy cabins in four commands, which are...

npm install -g git://
cabin new couch-cabin
cd $_
grunt deploy

This installs the fork using node.js' package manager, npm; creates our cabin; enters it; and deploys it to a CouchDB instance running at http://localhost:5984. To deploy to Cloudant, go into the root folder of your cabin, and edit couchapp.json to something like this:

  "app": "app.js",
  "db": "",
  "options": {
    "okay_if_exists": true

Where USERNAME and PASSWORD are your Cloudant credentials.

Note: Root URLs

Cabin assumes that it deploys to a top-level URL, so something like rather than, which will cause Cabin's styles to go all funky. So, if you deploy to Cloudant, make sure you set up a virtual host that points to your cabin. Check out Pretty URLs with Cloudant for details on how to set up virtual hosts with Cloudant.

Custom Cabin

If you'd rather edit your cabin by hand to deploy as a CouchApp, here's how you'd do that:

1. Gruntfile.js

Add this bit to grunt.initConfig:

mkcouchdb: {
  app: require('./couchapp.json')
couchapp: {
  app: require('./couchapp.json')

And add this task after:

grunt.registerTask('deploy', [

2. couchapp.json

Create a file named couchapp.json and add this to it:

  "app": "app.js",
  "db": "http://localhost:5984/cabin",
  "options": {
    "okay_if_exists": true

3. app.js

Create a file named app.js and add this to it:

var couchapp = require('couchapp'),
    path = require('path');

ddoc = {
  _id: '_design/app',
  rewrites: [{
    from: '',
    to: '/index.html'
    from: '*',
    to: '/*'
  views: {},
  lists: {},
  shows: {}

couchapp.loadAttachments(ddoc, path.join(__dirname, 'dist'));

module.exports = ddoc;

4. Dependencies

Now, run this to install dependencies:

npm install grunt-couchapp couchapp --save-dev

Then, do grunt deploy and your cabin is live!

5. Virtual Hosts

Cabin depends on living on a top-level URL, so you'll need to set up a virtual host so that your CouchApp can live at a url like, or else Cabin's styles will look all funky. Check out Pretty URLs with Cloudant for instructions on how.

As always, if you have any trouble, check our docs, post your question to StackOverflow, ping us on IRC, or if you'd like to discuss the matter in private, email us at

Happy coding!

Create an account and try it yourself

Sign Up for Updates!

Recent Posts