[[PageOutline]]
= Here Comes Trouble =

== Overview ==
`Here Comes Trouble` (htc) is a package for helping the support team with communications during an outage. It facilitates communicating service advisory messages to MF/PL members.

htc consists of the following components:

 * messages git repo - this repo contains all service advisory messages in raw format as well as message and web templates. There is one messages repo for the live installation (not yet functioning) and one for the dev installation. Each repo has three subdirectories: 
  * templates - pre-written and translated templates for common service advisories
  * queue - messages queued for translation or approval
  * published - messages published, a directory for each year with a directory for each message in the corresponding year
 * trouble - a bash script that simplified the creation of new messages. trouble prompts you through the process of selecting a template, creating a new message with next available number, gpg signing the message, commiting and publishing
 * post-commit hooks - the scripts are installed by puppet on jojobe and are called via a post-commit hook in the messages repo on jojobe.
  * rss-publish - generates a new RSS feed based on the most recent 25 messages
  * html-publish - generates browseable html files for the complete set of messages
  * email-publish - based on the RSS feed, emails new messages to service-advisories email list (requires mailman approval before they are released)
  * status-publish - [Not yet implemented] based on the RSS feed, publishes new messages on various configured status-supported systems

Setup of a server (jojobe) is handled via puppet, so we can easily switch to a different host if jojobe goes offline or is otherwise in-accessible.

htc is designed to require only a workstation with the appropriate (and reasonably up-to-date) software installed and Internet access between the workstation and jojobe.mayfirst.org (our server hosted in the UK).

== Getting Started ==

hct can function on either a live or dev installation. As of December 2012 we only have a dev installation running.

 * Checkout a copy of trouble via git:
{{{
git clone git://git.mayfirst.org/mfpl/trouble
cd trouble
git config remote.origin.pushurl gitosis@git.mayfirst.org:mfpl/trouble
}}}
 * Optionally symlink it in your ~/bin directory
 * Checkout a copy of the dev messages repo somewhere else:
{{{
git clone hct-dev@jojobe.mayfirst.org:/srv/hct-dev/messages/repo-hub hct-dev
}}}
 * Try releasing a message:
{{{
cd hct-dev
/path/to/trouble message
}}}

Test html: https://status.dev.mayfirst.org/
Test rss: https://status.dev.mayfirst.org/rss.xml
Test/Approve email: https://lists.mayfirst.org/mailman/admindb/service-advisories-dev

== trouble ==

The primary client component is a command line program called `trouble`.

`trouble` is a helper script that helps you edit a message based on existing templates, gpg sign the message, commit and push the message.

You can checkout a copy of trouble via git: git://git.mayfirst.org/mfpl/trouble

For usage, run trouble with no arguments:


{{{
0 jamie@animal:~$ trouble 
usage 
 trouble <subcmd> <options>
 trouble message [--template <template-name>] [--search <server-search-string>] 
 trouble message [--queue]

Subcommands
 message - create a trouble message
 dns - manipulate DNS records to redirect DNS queries from servers that may be down

Options
 --template - specify the name of a pre-existing dual language template
 --search - if freepupet helper is in your PATH, this string will be passed to freepuppet-helper 
   ls:<server-search-string>, and the Servers Affected line in the service advisory will be 
   pre-populated with the results
 --resume - resume message that has been saved in the queue (for approval or translation) 

Environment Variables
 TROUBLE_MESSAGES_PATH - the page to the service-advisories git repository. If undefined 
 it is set to the current working directory.
Unknown or empty subcmd.
0 jamie@animal:~$
}}}