X-Git-Url: http://git.tremily.us/?a=blobdiff_plain;f=install.txt;h=7a76301b397e2c2deb2e28daf0cbc8e8e2a3fdbe;hb=c9f6f03abd219db14cf619200a4ca5ba963efc0e;hp=d4db5851ba56a8ada0cf6a3fc86dbf4371dd9668;hpb=bd42ea1737e11e6b92f3880e0f31c4afc4a7eaf9;p=irker.git

diff --git a/install.txt b/install.txt
index d4db585..7a76301 100644
--- a/install.txt
+++ b/install.txt
@@ -16,24 +16,28 @@ 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.
 
-== Installing 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.
 
-You will need to have Jason Coombs's irc library where Python can see
-it.  See <http://pypi.python.org/pypi/irc/>; use version 3.0, not the
-older code from SourceForge.
-
-For higher performance, also install the eventlet library from
-<http://pypi.python.org/pypi/eventlet/>.  This merges in a cooperative
-threading implementation that is faster and has much lower space
-overhead than system threads, making irkerd more resistant to
-potential DoS attacks.
-
 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.
 
@@ -42,10 +46,53 @@ installed to launch irkerd as a boot-time service on that system.
 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.
+ways to install it. See the irkerhook manual page for details; the
+source is irkerhook.xml in this distribution.
+
+Note that if you were using the CIA service and have ciabot.py in your
+git update script, you can simply replace this
+
+/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
+
+with this:
+
+/path/to/irkerhook.py --refname=${refname} $(git rev-list ${oldhead}..${newhead} | tac)
+
+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 ==
 
-Go to a project repo and call irkerhook.py as indicated above while
-watching the freenode #commits channel.
- 
+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
+