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 == Installing irker ==
   9
  10 irker needs to run constantly, watching for TCP and UDP traffic on
  11 port 6659.  Install it accordingly.
  12
  13 You should *not* make irker visible from outside the site firewall, as
  14 it can be used to spam IRC channels while masking the source address.
  15
  16 You will need to have Jason Coombs's irc library where Python can see
  17 it.  See <http://pypi.python.org/pypi/irc/>; use version 3.0, not the
  18 older code from SourceForge.
  19
  20 == Installing irkerhook.py ==
  21
  22 irkerhook.py should be called from the post-commit hook of each
  23 repository.  See its header comment for detailed installation
  24 instructions.
  25
  26 You should set the server and (for Subversion) repository variables
  27 from the command line in your post-commit hook.  The server variable
  28 should be set to the inside-the-firewall host running your irker
  29 instance.
  30
  31 A git invocation line should look something like this:
  32
  33 /usr/local/bin/irkerhook.py server=internal.foobar.net
  34
  35 Each project will be able to set its own channel URLs, provided it
  36 has access to its git config file.
  37
  38 A Subversion invocation should look something like this:
  39
  40 REPOSITORY=$1
  41 REV=$2
  42 irkerhook.py repository=$REPOSITORY commit=$REV server=internal.foobar.net
  43
  44 Note that unless you supply additional overrides of project= and
  45 channels= in the hook, the basename of the repository will be used as
  46 the project name and will also be used as the IRC channel name on
  47 freenode.  This is not a limitation of irker.irkerhook, but a
  48 result of the absence of a git-config equivalent that the hook can
  49 mine stuff out of.
  50
  51 == Testing ==
  52
  53 Go to a project repo and call irkerhook.py as indicated above while
  54 watching the freenode #commits channel.
  55
  56 == Security considerations ==
  57
  58 See the security.txt document for a detailed discussion of security
  59 and DoS vulnerabilities related to irker.