Prepare 1.15 release, with a minor bugfix in the Subversion hook..

[irker.git] / install.txt

diff --git a/install.txt b/install.txt
index d4db5851ba56a8ada0cf6a3fc86dbf4371dd9668..048d51298771bbbb0205c53de02cef614efd15bf 100644 (file)
--- a/install.txt
+++ b/install.txt
@@ -16,23 +16,19 @@ 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 ==
+== 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.
+it.  See <http://pypi.python.org/pypi/irc/>; use version 3.4 or later.
 
 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 +38,47 @@ 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)
 
 == 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
+