Configuration

Installation

Here's the procedure for now:

Prerequisites:

• ruby 1.9 or greater
• gem
• xmpp3r
• cinch
• xml-simple
• prettyprint

Optional

• graphviz (highly recommended)
• a VCS client e.g. git, svn, cvs (NOTE: not working yet)

Install and run

• git clone https://github.com/svdasein/thehat.git
• cd thehat/src
• Run the stand-alone (single user tty) frontend: ./thehat-tty example.yaml

Configuration

In order to run any instance of TheHat, you will need to construct a small YAML configuration file.

Once you've created a configuration file, pass it as the first parameter to the frontend command you're running, e.g. ./thehat-irc myconfig.yaml. Note that all frontend commands to date accept an optional second parameter that is the name of a workflow that the engine should load immediately.

• Basic (tty only) configuration looks like this:

wfengine: {
 datadir: flows,
 webdir: www,
 baseurl: "http://localhost/~someuser",
 svnroot: "file:///home/someuser/svn",
 debuglevel: 1,
 renderers: [
   WorkflowDigraph
 ],
 allowExec: false,
}

• If allowExec == true, then the exec <command> command will be available in the workflow session. Enable with caution. It is just like having a shell prompt in the working directory of the bot. Note also that any command that you might run will block bot execution 'til it completes. So - again - caution. -The list of renderers available currently is:

• WorkflowDigraph: Renders a directed graph image + client side image maps

• WorkflowDigraphPostscript: Renders the same sort of graph as WorkflowDigraph, but as a postscript file

• WorkflowIcal: Renders an ical file. (not working yet - don't use)

• WorkflowRenderer: Good for debugging - dumps inspects of each step

• WorkflowDumpfile: More human-readable than WorkflowRenderer, but similar concept & usages

• If you want to use the WorkflowDigraph renderer with the auto-refresh page (highly recommended) do these things as well:

• Copy flow.cgi in the www directory to the directory you specified as the webdir.

• Ensure that whatever user you intend to run the bot as has permission to write to the webdir.

• Ensure that the program flow.cgi in the web directory is executable by your web server

• Ensure that your perl installation has Time::Local, Time::Zone, and LWP installed.

IRC

• If you want to use thehat-irc to connect to an IRC server, also include:

thehat-irc: { nic: mybot, name: MyBot, channel: mychannel, server: irc.freenode.net, port: 6667 }

XMPP (Jabber)

• If you want to use thehat-xmpp to connect to an XMPP (Jabber) server, you must:
• Set up an account for the bot - the bot does not attempt to register an account for itself
• Create a multi-user-chat room - the bot does not attempt to create a room for itself
• Include this additional section in the configuration file:

thehat-xmpp: { host: myserver.com, account: flow, password: password, resource: TheHat, room: <[email protected]> }

Version Control

• If you want to use a version control system with your workflow definitions, include a vcs item in the wfengine section like this:

vcs: {  
class: 'VCSClassName', [ other parameters specific to the class specified ]
}

• Currently, only the "Subversion" type is supported:

vcs: {  
class: 'Subversion', root: '<file:///home/someuser/svn>'
}

Starting up

• Start all frontends with ./thehat-<frontend type> example.ini
• You can optionally specify a second parameter, which will be interpreted as a workflow to immediately load