install.txt

   1 = Forge installation instructions =
   2
   3 irker and irkerhook.py are intended to be installed on forge sites
   4 such as SourceForge, GitHub, Gitorious, Gna, and Savannah.  This
   5 file explains the theory of operation, how to install the code,
   6 and how to test it.
   7
   8 == Theory of operation ==
   9
  10 irkerhook.py creates JSON notification requests and ships them to
  11 irkerd's listener socket.  irkerd run as a daemon in order to maintain
  12 all the client state required to post multiple notifications while generating
  13 minimum of join/leave messages (which, from the point of view of
  14 humans watching irkerd's output, are mere spam).
  15
  16 See the security.txt document for a detailed discussion of security
  17 and DoS vulnerabilities related to irker.
  18
  19 == Installing irker ==
  20
  21 irker needs to run constantly, watching for TCP and UDP traffic on
  22 port 6659.  Install it accordingly.
  23
  24 You should *not* make irker visible from outside the site firewall, as
  25 it can be used to spam IRC channels while masking the source address.
  26
  27 You will need to have Jason Coombs's irc library where Python can see
  28 it.  See <http://pypi.python.org/pypi/irc/>; use version 3.0, not the
  29 older code from SourceForge.
  30
  31 For higher performance, also install the eventlet library from
  32 <http://pypi.python.org/pypi/eventlet/>.  This merges in a cooperative
  33 threading implementation that is faster and has much lower space
  34 overhead than system threads, making irkerd more resistant to
  35 potential DoS attacks.
  36
  37 The file org.catb.irkerd.plist is a Mac OS/X plist that can be
  38 installed to launch irkerd as a boot-time service on that system.
  39
  40 == Installing irkerhook.py ==
  41
  42 Under git, a call to irkerhook.py should be installed in the update
  43 hook script of your repo.  Under Subversion, the call goes in your
  44 repo's post-commit script. Under Mercurial there are two different
  45 ways to install it. See the irkerhook manual page for details.
  46
  47 == Testing ==
  48
  49 Go to a project repo and call irkerhook.py as indicated above while
  50 watching the freenode #commits channel.
  51