===== Using Flapjack =====
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. 

==== Components ====
  * //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.
  * [[http://kr.github.com/beanstalkd/|beanstalkd]] is a work queue used to distribute checks and results.
  * [[http://couchdb.apache.org/|couchdb]] is a document-oriented database that checks and events are stored in.


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

<code>
$ flapjack-worker-manager start
</code>

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

<code>
$ flapjack-worker-manager start --workers=10
$ flapjack-worker-manager start --workers=15
</code>

will start 25 workers.

Calling //flapjack-worker-manager// with stop
<code>
$ flapjack-worker-manager stop
</code>
will shutdown all running workers.

If you want to run a //flapjack-worker// interactively, just run:
<code>
$ flapjack-worker
^C
</code>
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:

<code>
$ flapjack-worker --help
</code>

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

<code>
$ flapjack-notifier-manager start
</code>

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

Like //flapjack-worker//, you can run //flapjack-notifier// interactively:
<code>
$ flapjack-notifier
^C
</code>
You can also get a list of options to pass to the notifier:
<code>
$ flapjack-notifier --help
</code>

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

<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
</file>

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

<file>
[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
</file>

**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 [[development_guides|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:
<code>
flapjack-notifier-manager restart --recipients /etc/flapjack/recipients.conf \
                                  --config /etc/flapjack/notifier.conf
</code>

==== flapjack-admin ====

Grab the [[http://github.com/auxesis/flapjack-admin#readme|flapjack-admin]] web interface to start configuring checks, then use the //flapjack-populator// included with //flapjack-admin// to start running the checks:

<code>
$ cd path/to/flapjack-admin
$ bin/flapjack-populator
</code>

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.

==== Distributing ====
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.