1 = Forge installation instructions =
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,
8 == Theory of operation ==
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).
16 See the security.txt document for a detailed discussion of security
17 and DoS vulnerabilities related to irker.
19 == Installing irkerd ==
21 irker needs to run constantly, watching for TCP and UDP traffic on
22 port 6659. Install it accordingly.
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.
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.
31 The file org.catb.irkerd.plist is a Mac OS/X plist that can be
32 installed to launch irkerd as a boot-time service on that system.
34 == Installing irkerhook.py ==
36 Under git, a call to irkerhook.py should be installed in the update
37 hook script of your repo. Under Subversion, the call goes in your
38 repo's post-commit script. Under Mercurial there are two different
39 ways to install it. See the irkerhook manual page for details; the
40 source is irkerhook.xml in this distribution.
42 Note that if you were using the CIA service and have ciabot.py in your
43 git update script, you can simply replace this
45 /path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
49 /path/to/irkerhook.py --refname=${refname} $(git rev-list ${oldhead}..${newhead} | tac)
53 To verify that your repo produces well-formed JSON notifications,
54 you can run irkerhook.py in the repo directory using the -n switch,
55 which emits JSON to standard output rather than attempting to ship
56 to an irkerd instance.
58 Then, start irkerd and call irkerhook.py while watching the freenode
61 The 'irk' script is a little test tool that takes two arguments,
62 a channel and a message, and does what you'd expect.
64 If you need help, there's a project chat channel at
66 irc://chat.freenode.net/#irker
68 == Read-only access ==
70 If, for whatever reason, you can't modify the hook scripts in your
71 repository, there is still hope.
73 There's a proxy that takes CIA XML-RPC notifications
74 and passes them to a local irker instance. Find it here:
76 https://github.com/nenolod/irker-cia-proxy
78 There's also a poller daemon that can watch activity in a Subversion
79 repository and ship notifications via an irker instance.
81 https://github.com/shikadilord/irker-svnpoller