1 files changed, 116 insertions, 0 deletions
diff --git a/install.adoc b/install.adoc
new file mode 100644
index 0000000..fd7d1c5
--- /dev/null
+++ b/install.adoc
@@ -0,0 +1,116 @@
+= 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
+