= Forge installation instructions = irker and irkerhook.py are intended to be installed on forge sites such as SourceForge, GitHub, GitLab, Gna, and Savannah. This file explains the theory of operation, how to install the code, and how to test it. == Prerequisites == You should have Python 3 installed. While Python 2 support has not yet been removed, it is unmaintained and vulnerable to bitrot. If you just want to use irkerd and/or irkerhook.py, you need not bother with the Makefile. It's for building the derived versions of the documebtation and rubnning validation tools. If you want to run irkerd using a socket proxy, you'll want to do this: ------------------------------------- pip install -r requirements.txt ------------------------------------- Otherwise the code has no dependencies outside the Python standard library. == 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 a 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. The short version: as long as your firewall blocks port 6659 and irkerd is running inside it, you should be fine. == 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. 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 info for sparse messages and -d debug 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 firewall should block port 6659. The design of irker assumes the machine on which it is running is also inside the firewall, so that repository hooks can reach port 6659. 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. irker.service is a systemd unit that can run irkerd as a boot-time service on systems that support systemd. This is configured to run irkerd under a separate user account (irker), so this needs to be set up before starting irker, or the unit needs to be modified to use a different user. == Installing irkerhook.py == 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. SourceForge is a special case: see https://github.com/AI0867/sf-git-irker-pipeline for tools and instructions on how to work around its limitations. == Testing == 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 poller daemon that can watch activity in a Subversion repository and ship notifications via an irker instance. https://github.com/shikadilord/irker-svnpoller