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 == Prerequisites ==
  20
  21 You will need either
  22
  23 1. Python at version 2.6 or later, which has JSON built in
  24
  25 2. Python at version no older than 2.4, and a version of the
  26    simplejson library installed that it can use.  Some newer
  27    versions of simplejson discard 2.4 compatibility; 2.0.9
  28    is known to work.
  29
  30 == Installing irkerd ==
  31
  32 irker needs to run constantly, watching for TCP and UDP traffic on
  33 port 6659.  Install it accordingly. It has no config file; you can
  34 just start it up with no arguments.  If you want to see what it's
  35 doing, give it command-line options -d 1 for sparse messages and -d 2
  36 to show all traffic with IRC servers.
  37
  38 You should *not* make irker visible from outside the site firewall, as
  39 it can be used to spam IRC channels while masking the source address.
  40
  41 You will need to have Jason Coombs's irc library where Python can see
  42 it.  See <http://pypi.python.org/pypi/irc/>; use version 3.4 or later.
  43
  44 Some irclib versions after 5.0 may produce problems if you try to ship
  45 non-ASCII Unicode through them; this is not an irker bug, and should be
  46 kicked upstrean to the irclib maintainer.
  47
  48 The file org.catb.irkerd.plist is a Mac OS/X plist that can be
  49 installed to launch irkerd as a boot-time service on that system.
  50
  51 == Installing irkerhook.py ==
  52
  53 Under git, a call to irkerhook.py should be installed in the update
  54 hook script of your repo.  Under Subversion, the call goes in your
  55 repo's post-commit script. Under Mercurial there are two different
  56 ways to install it. See the irkerhook manual page for details; the
  57 source is irkerhook.xml in this distribution.
  58
  59 Note that if you were using the CIA service and have ciabot.py in your
  60 git update script, you can simply replace this
  61
  62 /path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
  63
  64 with this:
  65
  66 /path/to/irkerhook.py --refname=${refname} $(git rev-list ${oldhead}..${newhead} | tac)
  67
  68 SourceForge is a special case: see
  69
  70 https://github.com/AI0867/sf-git-irker-pipeline
  71
  72 for tools and instructions on how to work around its limitations.
  73
  74 == Testing ==
  75
  76 To verify that your repo produces well-formed JSON notifications,
  77 you can run irkerhook.py in the repo directory using the -n switch,
  78 which emits JSON to standard output rather than attempting to ship
  79 to an irkerd instance.
  80
  81 Then, start irkerd and call irkerhook.py while watching the freenode
  82 #commits channel.
  83
  84 The 'irk' script is a little test tool that takes two arguments,
  85 a channel and a message, and does what you'd expect.
  86
  87 If you need help, there's a project chat channel at
  88
  89    irc://chat.freenode.net/#irker
  90
  91 == Read-only access ==
  92
  93 If, for whatever reason, you can't modify the hook scripts in your
  94 repository, there is still hope.
  95
  96 There's a proxy that takes CIA XML-RPC notifications
  97 and passes them to a local irker instance. Find it here:
  98
  99     https://github.com/nenolod/irker-cia-proxy
 100
 101 There's also a poller daemon that can watch activity in a Subversion
 102 repository and ship notifications via an irker instance.
 103
 104     https://github.com/shikadilord/irker-svnpoller
 105