116 lines
4.1 KiB
Text
116 lines
4.1 KiB
Text
= 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
|
|
|