Replace README with one that describes LC config

1 files changed, 74 insertions, 4 deletions

diff --git a/README b/README
index b6b2662..3e80296 100644
--- a/README
+++ b/README
@@ -1,8 +1,78 @@
 README for lorry-controller
 ===========================
 
-Notes
------
+Lorry Controller mirrors Troves and mirrors or converts upstream
+projects into git repositories on the local Trove. Lorry Controller
+reads a configuration file (see below) and runs the Lorry program
+against the intended targets at suitable intervals.
 
-The lorry-controller.conf here is an example starting config for any customer
-configuration.  It is a single trove instance pointing at git.baserock.org.
+Lorry Controller configuration
+------------------------------
+
+Lorry Controller reads a configuration file of the following format.
+
+* The file uses JSON syntax.
+* The file is a list.
+* Each item in the list is a mapping specifying a Trove or a set of
+  `.lorry` files.
+* A Trove spec specifies another Trove to mirror completely.
+* A Lorry spec specifies a set of Lorry specification (`.lorry` files)
+  for individual project repositories to convert or mirror to git on
+  the local Trove.
+
+Each spec (mapping) has a number of key/value pairs. The following are
+shared between Trove and Lorry specs:
+
+* `type` is the type of the spec; value MUST be either `trove` or
+  `lorries`.
+* `interval` specifies how often Lorry Controller should mirror the
+  repositories in the spec. See below for INTERVAL.
+* Additionally, the following seem to be supported by an old version
+  of Lorry Controller, but Lars doesn't know what they mean or if
+  they're useful anymore (FIXME: find out or scrap them): `uuid`,
+  `serial`, `create`, `destroy`, `stagger`, `tarball`.
+
+Trove specs have the following keys:
+
+* `trovehost` is the other Trove to mirror; a domain name or IP address.
+* `ls-interval` determines how often should Lorry Controller query the
+  other Trove for a list of repositories it may mirror. See below for
+  INTERVAL.
+* `prefixmap` probably has some meaning (FIXME: find out what).
+* `ignore` is a list of git repositories from the other Trove that
+  should NOT be mirrored. Each list element is a path to the git
+  repository (not including leading slash).
+
+An INTERVAL value (for `interval` or `ls-interval`) is number and a
+unit to indicate a time interval. Allowed units are minutes (`m`),
+hours (`h`), and days (`d`), expressed as single-letter codes in upper
+or lower case.
+
+Lorry specs have the following keys:
+
+* `prefix` is a path prefix to be prepended to all repositories
+  created from the `.lorry` files from this spec.
+* `globs` is a list of globs (as strings) for `.lorry` files to use.
+  The glob is matched in the directory containing the configuration
+  file in which this spec is. It is OK for the globs to not match
+  anything.
+
+A fairly minimal example for mirroring `git.baserock.org` and using
+local `.lorry` files.
+
+    [
+        {
+            "type": "trove",
+            "trovehost": "git.baserock.org",
+            "ls-interval": "4d",
+            "interval": "2h"
+        },
+        {
+            "type": "lorries",
+            "interval": "1h",
+            "prefix": "delta",
+            "globs": [
+                "open-source-lorries/*.lorry"
+            ]
+        }
+    ]