===== Packaging Guide =====

This document aims to comprehensively detail dependencies, build & checkout processes, and recommendations for packaging Flapjack. 
==== Dependencies ====

Flapjack attempts to follow the Puppet route of keeping the number of dependencies very low. This reduces headaches for downstream packagers.

Essential dependencies (some of which may already be packaged for your operating system):

  * [[http://www.ruby-lang.org/en/|Ruby]]
  * [[http://kr.github.com/beanstalkd/|beanstalkd]]
  * [[http://couchdb.apache.org/|CouchDB]]
  * [[http://raa.ruby-lang.org/project/daemons/|daemons]]
  * [[http://beanstalk.rubyforge.org/|beanstalk-client]]
  * [[http://log4r.sourceforge.net/|log4r]]
  * [[http://home.gna.org/xmpp4r/|xmpp4r]]
  * [[http://tmail.rubyforge.org/|tmail]]
  * [[http://github.com/brianmario/yajl-ruby|yajl-ruby]]

Additionally, if you wish to package the DataMapper persistence backend, you will need to package: 

  * [[http://github.com/datamapper/dm-core|dm-core]]
  * [[http://github.com/datamapper/dm-more/tree/master/dm-validations/|dm-validations]]
  * [[http://github.com/datamapper/dm-more/tree/master/dm-timestamps/|dm-timestamps]]
  * [[http://github.com/datamapper/dm-more/tree/master/dm-types/|dm-types]]
  * [[http://rubyforge.org/projects/dorb|data_objects]]
    * do_sqlite3
    * do_mysql
    * do_postgres


==== Debian Ruby packaging guidelines ====
Flapjack adheres to the [[http://pkg-ruby-extras.alioth.debian.org/upstream-devs.html|Debian Ruby packaging guidelines]]. The guidelines set out some sane standards for upstream developers to follow, to make packaging by downstream maintainers as easy as possible. 

The guidelines have been translated into a [[http://github.com/auxesis/flapjack/blob/master/features/packaging-lintian.feature|test suite]] which is used to verify the packagability of Flapjack. If any of these tests fail, it's considered a high priority bug. 

If you are developmentally inclined, please help improve the test suite to make life easier for packagers.
==== Release tarball ====

For a tarball of just Flapjack suitable for packaging, you can find a list of published releases [[http://github.com/auxesis/flapjack/downloads|on GitHub]]. 

These tarballs are automatically created by GitHub when a commit is tagged. To keep bug tracking sane, please only build packages from tagged releases. 

For more info on tags, check out the [[http://book.git-scm.com/3_git_tag.html|Git book's introduction to tagging]], and the [[http://www.kernel.org/pub//software/scm/git/docs/git-tag.html|man page]].

Alternatively, if you want a tarball of Flapjack and all its dependencies to compile each component yourself, run:
<code>
$ rake tarball
</code>

==== Splitting up Flapjack packages ====

So users can granularly opt-in to Flapjack components (e.g. in distributed deployments you don't want the admin interface on your workers), it's recommended that Flapjack is split into several packages: 

  * //flapjack//, containing:
    * flapjack-worker, flapjack-worker-manager
    * flapjack-notifier, flapjack-notifier-manager
    * flapjack-stats, flapjack-benchmark

  * //flapjack-notifiers//, a meta package for:
    * flapjack-notifiers-mailer, containing the [[http://github.com/auxesis/flapjack/tree/master/lib/flapjack/notifiers/mailer/|mailer notifier]]
    * flapjack-notifiers-xmpp, containing the [[http://github.com/auxesis/flapjack/tree/master/lib/flapjack/notifiers/xmpp/|xmpp notifier]]

The //flapjack// package should recommend //flapjack-notifiers//. 

Currently //flapjack-admin// is maintained as a separate project and distributed as a Merb application. This makes packaging difficult, so if you manage to package everything else and get up to packaging //flapjack-admin//, please ping the [[http://groups.google.com/group/flapjack-project|mailing list]] so Lindsay can get off his arse and make it packagable.

==== Packagers ====

  * Debian: Serafeim Zanikolas
  * OpenBSD: [[http://twitter.com/berndahlers|Bernd Ahlers]]
  * CentOS / RHEL: [[http://agilesysadmin.net|Stephen Nelson-Smith]]