DOCSEARCHbyAlgolia
Submit Docs

cluster

repository·master·Indexed 25 days ago

https://github.com/learnboost/cluster

An extensible multi-core server manager for Node.js (version 0.7.7) designed to handle worker lifecycle, zero-downtime restarts, and graceful shutdowns. It provides a plugin system for logging, statistics, PID file management, and a command-line interface, and can be used for both HTTP/TCP servers and abstract process management like job queues.

Tokens
6.7K
Snippets
26
Records
45
Agent score
80%

What's inside cluster

  1. How to use Cluster to manage a Node.js application

    master

    Cluster manages workers (spawning one per CPU by default) and provides features like zero-downtime restarts, graceful shutdowns, and worker resuscitation.

    To use Cluster, you typically pass your application logic (as a module or a path) to the cluster() function, chain plugins using .use(), and then call .listen(port).

    Best Practice: Instead of requiring your app in the master process, pass the path to your application file to the cluster() function. This prevents the master process from unnecessarily creating database connections, as the file will only be require()ed within the workers.

    var cluster = require('cluster');

// Passing the path to the app file is recommended to avoid
// unnecessary database connections in the master process.
cluster('./app')
  .use(cluster.logger('logs'))
  .use(cluster.stats())
  .use(cluster.pidfiles('pids'))
  .use(cluster.cli())
  .use(cluster.repl(8888))
  .listen(3000);

  2. Use Cluster for abstract process management

    master

    Cluster is not limited to servers; it can manage processes for tasks like job queues. By invoking cluster() without any arguments, it spawns a worker for every CPU core. You can then use .start() to begin the process and check isWorker to determine the execution context.

    var cluster = require('cluster');

var proc = cluster().start();

if (proc.isWorker) {
  // do things within the worker processes
} else {
  // do something within the master
}

  3. Use the stats plugin to monitor cluster performance

    master

    The stats() plugin collects statistics from the master process's event emitter and exposes them via a REPL function. To use it, you must also use the repl() plugin. This allows you to monitor system load, uptime, worker counts, and more by telnetting into the REPL port.

    cluster(server)
  .use(cluster.stats())
  .use(cluster.repl(8888))
  .listen(3000);

  4. Enable verbose debugging for Cluster

    master

    To output verbose debugging information to _stderr_, use the cluster.debug() middleware. This provides visibility into the lifecycle of the master and worker processes, such as spawning, connecting, and shutting down.

    cluster(server)
  .use(cluster.debug())
  .listen(3000);

  5. Use the reload plugin to restart workers on file changes

    master

    The reload(paths[, options]) plugin monitors specific files or directories for mtime (modification time) changes. When a change is detected, it restarts the cluster workers.

    By default, the plugin sends a __SIGTERM__ signal to kill workers immediately. You can provide a different signal for graceful termination or specify an interval for the watcher.

    cluster(server)
  .use(cluster.reload('lib'))
  .listen(3000);

  6. Manage workers with spawn(), kill(), and restart()

    master

    You can dynamically manage the cluster lifecycle from the REPL:

    Spawn workers

    Use spawn() to add one worker, or spawn(n) to add n workers.

    Kill a worker

    Use kill(id[, signal]) to terminate a specific worker by its ID.

    • Defaults to SIGTERM.
    • Use SIGQUIT for graceful termination.

    Restart workers

    Use restart() to gracefully restart all current workers.

  7. Set up the Cluster REPL

    master

    The Cluster REPL provides live administration tools for inspecting state, spawning/killing workers, and more. It is implemented as a plugin.

    Security Note: It is highly recommended to use a local Unix domain socket instead of a TCP port to avoid creating a security hole.

    cluster(server)
  .use(cluster.repl('/var/run/cluster.sock'))
  .listen(3000);

  9. Set up the Cluster CLI plugin

    master

    To add a command-line interface to your cluster, use the cluster.cli() plugin.

    Important: You must use cluster.pidfiles() before cluster.cli() in your plugin chain to ensure the pidfile directory is exposed, which is required for the CLI to function.

    cluster(server)
  .use(cluster.pidfiles())
  .use(cluster.cli())
  .listen(3000);

  10. Use CLI commands to manage your cluster

    master

    Once the cluster.cli() plugin is configured, your server script acts as both the master process and the CLI entrypoint. You can run commands directly against your server file using node <server.js> <command>.

    Available Commands:

    • status: Displays the status of the master and worker processes (e.g., alive or dead).
    • restart: Restarts the cluster.
    • shutdown: Shuts down the cluster.
    • --help: Shows available command information.

  12. Use the pidfiles plugin to save process IDs

    master

    The pidfiles([path]) plugin automatically saves PID (process-ID) files for the master and all worker processes. By default, these files are saved to a ./pids directory relative to the project root. You can specify a custom directory by passing a path to the plugin function.

    // Save to default directory: ./pids
cluster(server)
  .use(cluster.pidfiles())
  .listen(3000);

// Save to a custom directory
cluster(server)
  .use(cluster.pidfiles('/var/run/node'))
  .listen(3000);