Added some info on configuration in the README

1 files changed, 105 insertions, 18 deletions

diff --git a/README.md b/README.md
index e10eae9..83f3386 100644
--- a/README.md
+++ b/README.md
@@ -16,52 +16,56 @@ signed git commits.
 ...because you would like each specific push event to trigger _something
 different_ on the git repo...
 
-...and you want only authorised users to be able to trigger that
+..and you want only authorised users to be able to trigger that
 _something_...
 
 ...then **scorsh** might be what you have been looking for. 
 
 **scorsh** is a simple system to execute commands on a remote host by
 using GPG-signed commits containing customisable commands
-(scorsh-tags). **scorsh** consists of two components:
+(scorsh-tags). **scorsh** consists of three components:
+
+* the `scorsh-commit` executable (client-side)
 
 * a `post-receive` git hook
 
-* the `scorsh` binary itself
+* the `scorshd` binary itself (server-side)
+
+The `scorsh-commit` executable is used to inject scorsh-commands in a
+regular gpg-signed git commit. 
 
 For each new push event, the `post-receive` hook creates a file in a
 configurable spool directory, containing information about the repo,
 branch, and commits of the push.
 
-The `scorsh` binary processes inotify events from the spool, parses
+The `scorshd` binary processes inotify events from the spool, parses
 each new file there, walks through the new commits looking for signed
 ones, checks if the message of a signed commit contains a recognised
-scorsh-tag, verifies that the user who signed the message is allowed
-to use that scorsh-tag, and executes the commands associated to the
-scorsh-tag. Or, well, this is what `scorsh` should be able to do when
-it's finished ;-)
+scorsh-command, verifies that the user who signed the message is
+allowed to use that scorsh-command, and executes the actions
+associated to the scorsh-command. 
 
-The set of scorsh-tags accepted on a repo/branch is configurable, and
-each scorsh-tag can be associated to a list of commands. Commands are
-just URLs, at the moment restricted to two possible types:
+The set of scorsh-commands accepted on a repo/branch is configurable,
+and each scorsh-command can be associated to a list of
+actions. Actions are just URLs, at the moment restricted to two
+possible types:
 
 * `file://path/to/file` - in this case `scorsh` tries to execute the
   corresponding file (useful to execute scripts)
   
 * `http://myserver.com/where/you/like` - in this case `scorsh` makes an
   HTTP request to the specified URL (useful to trigger other actions,
-  e.g., Jenkins or Travis builds...)
+  e.g., Jenkins or Travis builds -- **currently not working**)
   
 
 
-
 ## Build notes
 
-**scorsh** depends from the availability of a native build of
-`libgit2` version `0.25` or greater on the native system where
-***scorsh** is built. This dependencies is easily satisfied on various
-operating systems by using their respective package manager. For
-instance in Devuan ASCII one can simply do:
+**scorsh** depends on the availability of a native build of `libgit2`
+version `0.25` or greater on the native system where ***scorsh** is
+built. This dependencies is easily satisfied on various operating
+systems by using their respective package manager. For instance in
+Devuan ASCII one can simply do:
 
 ```
 sudo apt install libgit2-dev
@@ -92,6 +96,89 @@ And finally build its binary:
 make
 ```
 
+## Configuration walkthrough (DRAFT)
+
+`scorshd` reads its configuration from a yaml file, normally passed on
+the command line through the option `-c CFG_FILE`. An example is the
+following:
+
+```
+---
+s_spooldir: "./spool"
+s_logfile: "./scorsh.log"
+s_logprefix: "[scorsh]"
+
+s_workers:
+  [
+     {
+       w_name: worker1,
+       w_repos: [".*:.*"], # All branches in all repos
+       w_folder: ./worker1,
+       w_logfile: ./worker1/worker1.log,
+       w_cfgfile: "./worker1/worker1.cfg",
+     },
+     {
+       w_name: worker2,
+       w_repos: [".*:master"], # Branch master in all repos
+       w_folder: ./worker2,
+       w_logfile: ./worker2/worker2.log,
+       w_cfgfile: "./worker2/worker2.cfg",
+     }
+]
+...
+
+```
+
+This files defines two workers. Each worker is associated to a pair of
+`repo:branch` regexps. A worker will be activated only on pushes made
+on a matching `repo:branch`. Each worker has a configuration file
+`w_cfgfile`, where the list of accepted scorsh-commands is
+defined. For instance, for `worker1` we could have:
+
+```
+---
+w_commands:
+    [
+     {
+       c_name: "LOG",
+       c_keyrings: ["allowed_users.asc"],
+       c_actions: [
+                    {
+                     a_url: "file:///home/katolaz/bin/scorsh_script_log.sh"
+                    }
+                   ]
+      },
+     {
+       c_name: "build",
+       c_keyrings: ["allowed_users.asc"],
+       c_actions: [
+                    {
+                     a_url: "file:///home/katolaz/bin/scorsh_script.sh",
+                     a_hash: "c129d4a12998c44dfb9a9fd61ec3159bf29606e0f7280f28bbd98fc6f972fa27"
+                    }
+                   ]
+      },
+     {
+      c_name: "preview",
+      c_keyrings: ["allowed_users.asc"],
+      c_actions: [
+                  {
+                  a_url: "file:///home/katolaz/bin/scorsh_preview.sh"
+                  }
+                 ]
+     }
+      
+    ]
+...
+```
+
+In this example, `worker1` has three configured scorsh-commands,
+namely `LOG`, `build`, and `preview`.  Commands are
+*case-sensitive*. Each command is associated to a list of keyblocks
+(containg the public keys of the users allowed to run that command),
+and to a list of actions. 
+
+**TBC**
 
 ## License