Web interface plugin for nutcracker-ruby ( Twemproxy )
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Nutcracker Web

Web interface plugin for nutcracker-ruby


  • Ruby 1.9+


gem install nutcracker-web


$ nutcracker-web --help
Usage: nutcracker-web [web-options] -- [nutcracker-options]


  -u, --stats-uri URI              Nutcracker stats uri, default is tcp://localhost:22222
  -c, --config FILE                Nutcracker cluster config file
  -p, --port PORT                  Web interface listening port
  -b, --backend BACKEND            Web server to use ( needs to be Rack compliant )
  -x, --context CONTEXT            Web Interface URL context, default /
  -d, --daemonize                  run in background
  -l, --launch                     launch Nutcracker instance as well
  -s, --max-memory SIZE            manually specify max memory for every redis node ( Use it for elastic cache )
  -v, --version                    Print version and exit
  -i, --pid FILE                   pid file


  -h, --help             : this help
  -V, --version          : show version and exit
  -t, --test-conf        : test configuration for syntax errors and exit
  -d, --daemonize        : run as a daemon
  -D, --describe-stats   : print stats description and exit
  -v, --verbose=N        : set logging level (default: 5, min: 0, max: 11)
  -o, --output=S         : set logging file (default: stderr)
  -c, --conf-file=S      : set configuration file (default: conf/nutcracker.yml)
  -s, --stats-port=N     : set stats monitoring port (default: 22222)
  -a, --stats-addr=S     : set stats monitoring ip (default:
  -i, --stats-interval=N : set stats aggregation interval in msec (default: 30000 msec)
  -p, --pid-file=S       : set pid file (default: off)
  -m, --mbuf-size=N      : set size of mbuf chunk in bytes (default: 16384 bytes)

conneting to a running instance of twemproxy and running the web interface on port 22122

$ nutcracker-web --config /etc/nutcracker/cluster.yml --port 22122
[2014-03-02 17:26:40] INFO  WEBrick 1.3.1
[2014-03-02 17:26:40] INFO  ruby 2.0.0 (2013-05-14) [x86_64-darwin11.4.2]
[2014-03-02 17:26:40] INFO  WEBrick::HTTPServer#start: pid=84800 port=22122

launching twemproxy and nutcracker-web

$ nutcracker-web --config example-cluster.yml --port 22122 --launch
[Sun Mar  2 17:26:37 2014] nc.c:187 nutcracker-0.3.0 built for Darwin 13.0.0 x86_64 started on pid 84801
[Sun Mar  2 17:26:37 2014] nc.c:192 run, rabbit run / dig that hole, forget the sun / and when at last the work is done / don't sit down / it's time to dig another one
[2014-03-02 17:26:40] INFO  WEBrick 1.3.1
[2014-03-02 17:26:40] INFO  ruby 2.0.0 (2013-05-14) [x86_64-darwin11.4.2]
[2014-03-02 17:26:40] INFO  WEBrick::HTTPServer#start: pid=84800 p

if you use ElastiCache you will need to specify maxmemory for each node in your cluster

$ nutcracker-web --config example-cluster.yml --port 22122 --launch --max-memory 674963865666

Usage via code

After starting the twemproxy service via nutcracker-ruby just activate the nutcracker-web plugin:

require 'nutcracker'
require 'nutcracker/web'

# Start nutcracker
nutcracker = Nutcracker.start config_file: 'cluster.conf'

# Start the web service on port 1234 using Webrick
nutcracker.use :web, Port: 1234

# Sleeping....

you can pass default Rack options to Nutcracker#use ( like :Host, :server etc)

Custom Webserver

to use a different webserver like thin

require 'nutcracker'
require 'nutcracker/web'
require 'thin'

nutcracker = Nutcracker.start config_file: 'cluster.conf'
nutcracker.use :web, Port: 1234, server: :thin


  • redis.conf : don't forget to configure the maxmemory attribute for each Redis instance

Developer ?

to run nutcracker-web with stub data

  • bundle install
  • run the rackup command to start the service.
  • edit example.json.
  • client Backbone app is under assets and the Sinatra backend is under the lib directory.

Packaging & Testing

  • rake compile : compile the assets into a single application.{js,css} file under the public directory
  • rake build : compile the assets & builds a new gem
  • rake test : runs the jasmine tests suite

More PNGs


This software is provided “as is” and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.


this project is still in its early stages so things could be a little bit buggy, if you find one feel free to report it @ our issue tracker.
Also nutcracker-web only supports Redis instances for now.