node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



clusterman hopes to provide some basic utility around using node 0.6.x's native clustering. It provides a quick script to generate init scripts for your service that will make it super easy to start, stop and restart. It uses forever to keep the cluster master running. Right now it's a naive, generally untested implementation that hopes to allow for term and restarts.

It's meant to be installed globally:

npm install -g

You now have access to two binaries called "clusterman" and "mkclusterman" It expects a config file somewhere, i.e. /etc, and you could run it like:

mkclusterman /etc/my_cluster_app.json > /etc/init.d/my_cluster_app

mkclusterman reads all the bits of your config file and creates an init script that you can easily simply call /etc/init.d/my_cluster_app stop|start|restart and it will do the right thing.

It's can also be installed per app as a node_module, so:

npm install

will install it. Then you create a clusterman.json config file in your apps main directory and run it as such:

node node_modules/clusterman

This has been run just for some test apps while I'm building it out, seems to work. Still a bunch to do.


You can copy the examples/clusterman.json file into /etc, your app's main directory or wherever you like - if you've installed clusterman globally. If you installed it in your app, you must put it in your app's main directory and it must be called clusterman.json. The file contains all the configuration clusterman uses, most of it is passed straight to forever so you can see the forever documentation for that. The particular ones that clusterman cares about are:

  • rootDir - the root directory of your app
  • script - this is just the name of the file you want to run, relative to the rootDir
  • port - what port you want to run it on
  • start - the number of child processes to create
  • pidFile - the file that it will write the process ID to, this will be the id which should get signalled

Your application

The script that you put into configuration is expected to be a server before you start to .listen(). For example, an express app might look like this:

var express = require('express'),
    routes = require('./routes');
var app = module.exports = express.createServer();
  app.use(express.static(__dirname + '/public'));
app.get('/', routes.index);
module.exports = app;

Managing the app

The Easy Way

The key bit is the pidFile you specify in the configuration. clusterman expects one of two signals:

  • graceful restart

    • to do a graceful restart, just kill -s HUP `cat [pidfile]' and it will close off connections for existing servers and as they finish, kill the process and start a new one
  • terminate

    • to just end everything, kill `cat [pidfile]' will kill off immediately all children and the end master process


  • Testing
  • Create generic init scripts
  • Testing