CouchDB distribution and management of Node.js applications

Steelmesh is a distributed application framework build on top of Node.js and CouchDB (specifically we love using Couchbase community editions).

Steelmesh is designed to assist with managing and scaling Node + Couch applications in a horizontal fashion. At this stage, Steelmesh is not designed to support partitioning large datasets, but rather to:

  1. Provide load distribution for small-medium sized datasets that experience a high traffic load.

  2. Provide a manageable interface to a number of Couch + Node instances.

OK. Just so you know, getting an instance of Steelmesh running is reasonably involved. Not too tricky, but it might involve some mucking around and the process is still nowhere near as refined as it will be in a few months...

Also, Sidelab will be running up a hosted installation of Steelmesh in the near future, so if you are feeling brave, then feel free to message me and we can look at providing you access once it's available.

Essentially, get an installation of CouchDB running somewhere on your network. I would recommend using one of the Couchbase distributions as they are just lovely to work with.

If you don't already have Node and NPM running, then you will need to install them. Use google - it's your friend.

To aid in both creating steelmesh apps, and also administering a steelmesh server we have some command-line tools. The simplest way to install these tools is via npm:

npm install mesh -g

Once installed, this will provide you a mesh command line utility.

By default, steelmesh will attach to a CouchDB called steelmesh. This database is not automatically created, so you will need to use the mesh command line tools to create it. Run the following command to initialize the db:

mesh admin-create

This should generate something similar to the following:

PUT http://localhost:5984/steelmesh/_design/default
Finished push. 1-385253ac3b0c205f93dafee1d839751d
>> mesh:admin-create
- _design/default
Operation succcessful

This command creates the steelmesh database and uploads the required design documents into the database.

OK, you've made it this far. Nice job. Now, in a location that you would like to run steelmesh, clone this repository:

git clone git://

Once you have cloned the repository, change into your newly created directory and pull down the required node_modules:

npm install

Once the required modules are you should be able to run the following command:

node debug-server.js

All being well, you should see output similar to the following:

loading apps using the couch apploader
synchronized application resources
  info - master started
  info - worker 0 spawned
  info - worker 1 spawned
  info - listening for connections
  info - worker 1 connected
  info - worker 0 connected

This is a mix of some steelmesh output and output that has been generated from cluster.

At this stage, steelmesh is operational, but not doing a lot. Time to create an app.

Now, create a directory somewhere on your local machine. By default, the name of the folder will become the name of your Steelmesh appliation but that can be changed using the various Configuration Options. Anyway, let's create an application. I'm going to create a directory called test (because I'm creative like that):

mkdir test
cd test
mesh create

Now in the test directory, you should see a number of new files, including an app.js file. The app.js file is basically the file that contains the information on how the application controls routes, background tasks that it does, etc, etc. Lots of documentation coming on this... promise.

One the application has been created, you can publish the application to a Steelmesh server using the following command:

mesh update

This would generate output similar to the following:

Preparing test for deployment
Pushing to db...
PUT http://localhost:5984/steelmesh/test
Finished push. 1-f0ee9c0a7e63e35207220559cf35390e
Operation succcessful

Now that you have pushed the application to the steelmesh, restart the steelmesh server (see Step 7).

NOTE: This is a temporary step that is required while we are properly implementing listening to CouchDB change notifications and auto reloading updated applications.

You should now see the following when the server is started:

no configuration file, using default config
loading apps using the couch apploader
synchronizing application: test
synchronized application resources
  info - master started
  info - worker 0 spawned
  info - worker 1 spawned
  info - listening for connections

By default, Steelmesh is designed to run behind nginx as this provides an ideal front-door to both CouchDB and Node. So if you don't have nginx installed already, then go get it...

Before we test our application, we will need to start nginx to act a reverse-proxy to both our CouchDB server and Node server. Steelmesh comes with a prebuilt nginx configuration that routes traffic to the appropriate destination.

The simplest way to start nginx is by changing to directory you installed steelmesh in and running the following command:

sudo nginx -p nginx/

This tells nginx to use the steelmesh/nginx directory as the nginx root, so the configuration file is loaded from the conf directory automatically. NOTE: The sudo command is required as the configuration by default listens on port 80 and binding to ports below 1024 (I think) requires superuser privileges.

If everything has gone well, then you should be able to view the following url (if you are running locally, and called your application is called test):


Out of the box, Steelmesh is basically Express on NodeJS with CouchDB connectivity. Express (via Connect), however, offers very powerful middleware capabilities and as such some addins are being developed for Steelmesh:

Steelmesh is distributed under the Apache License (v2).