nocrash

supervisor to ensure your process does not crash

Usage no npm install needed!

<script type="module">
  import nocrash from 'https://cdn.skypack.dev/nocrash';
</script>

README

nocrash keeps your node.js process running. It is:

  • extremely lightweight
  • easy to configure
  • works well inside a docker container

Purpose

The default restart policies in Docker are lacking. Proper restart policies need to satisfy these requirements:

  • Some smart cooldown period to prevent restart loop
  • Log every restart to desired monitoring provider
  • Ability to handle termination signals

nocrash will keep your service process up and running, restarting it when it crashes, with smart cooldown period applied. It will also log every crash so you can monitor it.

When SIGINT or SIGTERM are received, nocrash will forward the signals to the child processes. When all child processes have exited, nocrash will exit gracefully.

Unlike typical process managers, nocrash does not run as a daemon. It runs as a normal node.js process, obeying typical node.js life cycles and system signals. It works well with docker. nocrash spawns the target app as a child node.js process, and when docker kills nocrash, the child process is killed as well.

Usage

const nocrash = require('nocrash');

nocrash.watch({
  path: 'worker.js',
  minCool: 1,
  maxCool: 10,
  // maxRetries: 5,   // don't set maxRetries, so it will run forever
  log: (msg) => {
    console.error(msg);
  },
});
  • path: the worker process to run
  • minCool: initial cooldown period in seconds. Cooldown period will ramp up if the process keeps crashing
  • maxCool: maximum cooldown period in seconds. Cooldown period will be capped at this maximum
  • If a process stays up for more than 5 minutes, the cooldown period is reset.
  • maxRetries: if not set, nocrash will keep the worker process up forever. If set, it will exit after the number of retries exceeds maxRetries
  • log: nocrash will call this function when error is encountered, such as a process exit. Use this callback to log the errors

Using nocrash in existing app

Assuming the existing app is started with node index.js (index.js is the entrypoint of the app).

Create another file called nocrash.js:

const nocrash = require('nocrash');

nocrash.watch({
  path: 'index.js',   // point to existing entrypoint
  minCool: 1,
  maxCool: 10,
  log: (msg) => {
    console.error(msg);
  },
});

Run the app with node nocrash.js, and nocrash would spawn index.js as a child process, supervising it with nocrash protection.

docker configuration

Even with nocrash protection, docker containers can still crash for various reasons, such as when it runs out of memory. So it is recommended to still configure docker containers with --restart unless-stopped or --restart always restart policy for the extra layer of protection. However, nocrash provides these extra benefits:

  • protection against restart loop with cooldown rules
  • ability to log each service crash to an external logging service