Flapjack consists of several components that do one thing and do it well. This guide covers how each of the components work and interact with one another.

• flapjack-admin lets you configure checks through a web interface.
• flapjack-notifier notifies people if the check results are bad.
• flapjack-worker executes the checks and reports back results.
• beanstalkd is a work queue used to distribute checks and results.
• couchdb is a document-oriented database that checks and events are stored in.

You can use flapjack-worker-manager to start a cluster of workers (5 by default):

$ flapjack-worker-manager start

flapjack-worker-manager can be called multiple times to start more workers, for instance:

$ flapjack-worker-manager start --workers=10
$ flapjack-worker-manager start --workers=15

will start 25 workers.

Calling flapjack-worker-manager with stop

$ flapjack-worker-manager stop

will shutdown all running workers.

If you want to run a flapjack-worker interactively, just run:

$ flapjack-worker
^C

You can use this to see what's going on behind the scenes. The worker manager is just spawning multiple copies of flapjack-worker.

To find out what options can be passed to the worker, run:

$ flapjack-worker --help

Use flapjack-notifier-manager to start and stop flapjack-notifier as a daemon.

$ flapjack-notifier-manager start

Right now you can only run one flapjack-notifier as a daemon at a time.

Like flapjack-worker, you can run flapjack-notifier interactively:

$ flapjack-notifier
^C

You can also get a list of options to pass to the notifier:

$ flapjack-notifier --help

You can configure who receives notifications from flapjack-notifier in a recipients configuration file:

[Jane Doe]
  email = jane@example.org
  phone = +61 444 222 111
  pager = 61444222111
  jid = jane@doe.com

[John Smith]
  email = john@example.org
  phone = +31 123 456 789 
  pager = 31123654987
  jid = jane@doe.com

Then you can configure what persistence backends, transports, and notifiers are used:

[notifier]
  notifier-directories = /usr/lib/flapjack/notifiers/ /path/to/my/notifiers
  notifiers = mailer, xmpp

[persistence]
  backend = couchdb
  host = localhost
  port = 5984 
  database = flapjack_production

[transport]
  backend = beanstalkd
  basedir = /usr/lib/flapjack/persistence/
  host = localhost
  port = 11300

[mailer-notifier]
  from_address = foo@bar.com

[xmpp-notifier]
  jid = foo@bar.com
  password = barfoo

Transports are the message queues by which checks and results are sent between workers and the notifier. Currently there is only a beanstalkd transport, however it's very easy to write an AMQP/RabbitMQ backend.

Persistence backends interact with a representation of the checks in a database. The representation of the checks is managed by flapjack-admin, and injected onto the beanstalkd queue using flapjack-populator. Currently there are CouchDB and DataMapper backends, with the CouchDB one being the default.

Notifiers do the grunt work of notifying people if a check fails. They are initialised from the config file by any section that ends with -notifier. Currently there are email and XMPP notifiers.

Now you need to restart the notifier:

flapjack-notifier-manager restart --recipients /etc/flapjack/recipients.conf \
                                  --config /etc/flapjack/notifier.conf

Grab the flapjack-admin web interface to start configuring checks, then use the flapjack-populator included with flapjack-admin to start running the checks:

$ cd path/to/flapjack-admin
$ bin/flapjack-populator

This will take the checks you set up in flapjack-admin and turn them into jobs on the beanstalkd work queue.

Provided the workers are running, they will start running the new checks.

If you have existing checks in the beanstalkd work queue, you need to restart it before running the populator again. As beanstalkd is an in-memory work queue, the restart will wipe all existing jobs, leaving a clean slate to run the flapjack-populator again.

Deploying a new “batch” of checks from the admin interface will trigger a restart of beanstalkd, so unless you are automating the deployment of new checks you won't need to worry about restarting beanstalkd.

When you ran install-flapjack-systemwide during the install, init scripts were placed in /etc/init.d. Additionally, if you run Ubuntu or Debian, they were set to start on boot.

Each init script has a corresponding control file in /etc/default/ that can be used to set default options when starting & stopping daemons.

You can use these to start up the different parts of Flapjack depending on what role the system should play.

For instance, you might want to run a worker cluster on one machine and the notifier on another. This can be a great way of distributing the load when you have lots of checks.

You can run worker clusters across many machines too, providing failover if one of your clusters goes down. This also works for the notifier.