install.txt

= Forge installation instructions =

irker and irkerhook.py are intended to be installed on forge sites
such as SourceForge, GitHub, Gitorious, Gna, and Savannah.  This
file explains the theory of operation, how to install the code,
and how to test it.

== Theory of operation ==

irkerhook.py creates JSON notification requests and ships them to
irkerd's listener socket.  irkerd run as a daemon in order to maintain
all the client state required to post multiple notifications while generating
minimum of join/leave messages (which, from the point of view of
humans watching irkerd's output, are mere spam).

See the security.txt document for a detailed discussion of security
and DoS vulnerabilities related to irker.

== Installing irker ==

irker needs to run constantly, watching for TCP and UDP traffic on
port 6659.  Install it accordingly.

You should *not* make irker visible from outside the site firewall, as
it can be used to spam IRC channels while masking the source address.

You will need to have Jason Coombs's irc library where Python can see
it.  See <http://pypi.python.org/pypi/irc/>; use version 3.0, not the
older code from SourceForge.

For higher performance, also install the eventlet library from
<http://pypi.python.org/pypi/eventlet/>.  This merges in a cooperative
threading implementation that is faster and has much lower space
overhead than system threads, making irkerd more resistant to
potential DoS attacks.

The file org.catb.irkerd.plist is a Mac OS/X plist that can be
installed to launch irkerd as a boot-time service on that system.

== Installing irkerhook.py ==

irkerhook.py should be called from the post-commit hook of each 
repository.  See its header comment for detailed installation 
instructions.

You should set the server and (for Subversion) repository variables
from the command line in your post-commit hook.  The server variable
should be set to the inside-the-firewall host running your irker
instance.

A git invocation line should look something like this:

/usr/local/bin/irkerhook.py server=internal.foobar.net

Each project will be able to set its own channel URLs, provided it
has access to its git config file.

A Subversion invocation should look something like this:

REPOSITORY=$1
REV=$2
irkerhook.py repository=$REPOSITORY commit=$REV server=internal.foobar.net

Note that unless you supply additional overrides of project= and
channels= in the hook, the basename of the repository will be used as
the project name and will also be used as the IRC channel name on
freenode.  This is not a limitation of irker.irkerhook, but a
result of the absence of a git-config equivalent that the hook can
mine stuff out of.

== Testing ==

Go to a project repo and call irkerhook.py as indicated above while
watching the freenode #commits channel.