file explains the theory of operation, how to install the code,
and how to test it.
-== Installing irker installation ==
+== 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.
+
+== Prerequisites ==
+
+You will need either
+
+1. Python at version 2.6 or later, which has JSON built in
+
+2. Python at version no older than 2.4, and a version of the
+ simplejson library installed that it can use. Some newer
+ versions of simplejson discard 2.4 compatibility; 2.0.9
+ is known to work.
+
+== Installing irkerd ==
irker needs to run constantly, watching for TCP and UDP traffic on
-port 6659. Install it accordingly.
+port 6659. Install it accordingly. It has no config file; you can
+just start it up with no arguments. If you want to see what it's
+doing, give it command-line options -d 1 for sparse messages and -d 2
+to show all traffic with IRC servers.
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.
+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.
+Under git, a call to irkerhook.py should be installed in the update
+hook script of your repo. Under Subversion, the call goes in your
+repo's post-commit script. Under Mercurial there are two different
+ways to install it. See the irkerhook manual page for details; the
+source is irkerhook.xml in this distribution.
-You should set the server and either repository or project 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.
+Note that if you were using the CIA service and have ciabot.py in your
+git update script, you can simply replace this
-A git invocation line should look something like this:
+/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
-/usr/local/bin/irkerhook.py project=foobar server=internal.foobar.net
+with this:
-A Subversion invocation should look something like this:
+/path/to/irkerhook.py --refname=${refname} $(git rev-list ${oldhead}..${newhead} | tac)
-REPOSITORY=$1
-REV=$2
-irkerhook.py repository=$REPOSITORY commit=$REV server=internal.foobar.net
+SourceForge is a special case: see
-Note that the basename of the repository will be used as the project
-name.
+https://github.com/AI0867/sf-git-irker-pipeline
+
+for tools and instructions on how to work around its limitations.
== Testing ==
-Go to a project repo and call
+To verify that your repo produces well-formed JSON notifications,
+you can run irkerhook.py in the repo directory using the -n switch,
+which emits JSON to standard output rather than attempting to ship
+to an irkerd instance.
+
+Then, start irkerd and call irkerhook.py while watching the freenode
+#commits channel.
+
+The 'irk' script is a little test tool that takes two arguments,
+a channel and a message, and does what you'd expect.
+
+If you need help, there's a project chat channel at
+
+ irc://chat.freenode.net/#irker
+
+== Read-only access ==
+
+If, for whatever reason, you can't modify the hook scripts in your
+repository, there is still hope.
+
+There's a proxy that takes CIA XML-RPC notifications
+and passes them to a local irker instance. Find it here:
+
+ https://github.com/nenolod/irker-cia-proxy
+
+There's also a poller daemon that can watch activity in a Subversion
+repository and ship notifications via an irker instance.
+
+ https://github.com/shikadilord/irker-svnpoller
+
projects / irker.git / blobdiff