Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Proxy or redirect requests to different applications based on an API response. Read about how we use it.

NPM version Node.js version support Build status Dependencies GPLv3 licensed

Thundermole Flow Diagram

Table Of Contents


  • Install Node.js
  • Clone this repo locally and cd into it
  • Copy the sample routes with cp config/routes.sample.json config/routes.json
  • Optionally copy the sample StatsD config with cp config/statsd.sample.json config/statsd.json
  • Optionally copy the sample syslog config with cp config/syslog.sample.json config/syslog.json
  • Run make to install dependencies and run the test suite

Running Thundermole

Usage: bin/thundermole [options]


  -h, --help                 output usage information
  -V, --version              output the version number
  -c, --config <path>        the directory to look for config files in
  -C, --cluster              create a cluster of workers for handling requests
  -p, --port <port>          the port to run on
  -w, --workers <num>        the number of workers to add to the cluster
  -r, --rewrite-host-header  whether to rewrite the host header
  -P, --ping-url             A ping URL for the application


bin/thundermole reads configurations from JSON files.


Should contain application routes as outlined in the routes option documentation. See routes.sample.json for an example.


Optional. Should contain statsd configurations as outlined in the statsd option documentation. See statsd.sample.json for an example.


Should contain syslog configurations as outlined in the winston-syslog documentation. See syslog.sample.json for an example.

JavaScript Interface

Thundermole can be loaded as a module and run programatically.

Basic API

var thundermole = require('thundermole');

// Create a thundermole application
var mole = thundermole({
    // ... options ...

// Start the thundermole application on port 3000


routes (object)

Required. A simple routing hash. Each property maps to the first part of a request path, and the value should indicate the API endpoint to use for matching requests. For example:

    "foo": "http://my-api/"

Routes can also be regular expressions which gives you a little more flexibility. The URL path of the request is tested against, and has the preceeding slash stripped. It's worth noting that backslashes need to be escaped as we're working in JSON:

    "/foo\\/bar/i": "http://my-api/"

Also regular expression routes do not match from the start and end of the path – you'll need to manually specify that:

    "/^foo$/i": "http://my-api/"

routes.default (string)

Required. The default route to use if no others match the request.

appendHeader (string)

Optional. The header to send API-appended data in. Defaults to X-Proxy-Appended-Data.

rewriteHostHeader (boolean)

Optional. Whether to rewrite the Host header to match the proxy target. Defaults to true.

statsd (object)

Optional. A node-statsd configuration object, as outlined in their documentation.

logger (object)

Optional. An object with the methods debug, error, info, and warn which will be used to report errors and request information.

pingUrl (string)

Optional. A URL path (including preceding slash) which, when requested, will respond with a 200 status. This can be used for monitoring your Thundermole instance. Defaults to null.

Running Example Applications

Thundermole comes with an example application which runs two APIs and two backends. To run these you'll need to install Foreman, or look into the example Procfile and spin up each process separately.

If you have Foreman, run the example application with:

foreman start -d example

Building Thundermole-Compatible APIs

In order for Thundermole to be able to communicate with your API, you'll need to follow the API Specification.


To contribute to Thundermole, clone this repo locally and commit your code on a separate branch.

Please write unit tests for your code, and check that everything works by running the following before opening a pull-request:

make ci


Copyright © 2015 Springer Nature.
Thundermole is licensed under the GNU General Public License 3.0.


Proxy or redirect requests to different applications based on an API response







No packages published