Emphazise usage within leap platform for tapicero

Sorting the sections so the usage scenarios for the platform come first.

1 files changed, 60 insertions, 38 deletions

diff --git a/docs/design/tapicero.md b/docs/design/tapicero.md
index 359ee15..cb7be7c 100644
--- a/docs/design/tapicero.md
+++ b/docs/design/tapicero.md
@@ -1,55 +1,56 @@
-Tapicero - Creating per user databases on the couch for soledad
-------------------------------------------------------------
+@title = 'Tapicero'
+@summary = 'Creating per-user databases on the couch for soledad.'
+@toc = true
 
-``tapicero`` is a daemon that creates per user databases when users are added to the LEAP Platform. It watches the changes made to the users database and creates new databases accordingly. This way soledad does not need admin privileges.
+Tapicero 
+==============
+
+**Create databases for the leap platform users**
+
+
+Tapicero is part of the leap platform. It's deployed to the couch nodes and watches the users database as a daemon. When a user is add it creates a new database for that user. It also removes these databases on user destruction. This way neither the webapp nor soledad need couch admin privileges.
 
 "Tapicero" is spanish for upholsterer - the person who creates your couch.
 
-This program is written in Ruby and is distributed under the following license:
+Running
+--------------------
 
-> GNU Affero General Public License
-> Version 3.0 or higher
-> http://www.gnu.org/licenses/agpl-3.0.html
+Tapicero is usually deployed with the leap platform and run as a daemon from an init script. It also serves as a tool to modify existing user databases. You can find it in `/srv/leap/tapicero` on the couch nodes or play with it on your own machine.
 
-Installation
----------------------
+Run in foreground:
 
-Prerequisites:
+    bundle exec /bin/tapicero run
 
-    sudo apt-get install ruby ruby-dev couchdb
-    # for development, you will also need git, bundle, and rake.
+Run as a deamon:
 
-From source:
+    bundle exec /bin/tapicero start
+    bundle exec /bin/tapicero stop
 
-    git clone git://leap.se/tapicero
-    cd tapicero
-    bundle
-    rake build
-    sudo rake install
+Run once, process all changes so far and then exit:
 
-From gem:
+    bundle exec tapicero --run-once
 
-    sudo gem install tapicero
+Configuration
+---------------------
 
-Running
---------------------
+Tapicero reads the following configurations files, in this order:
+
+* ``$(tapicero_source)/config/default.yaml``
+* ``/etc/leap/tapicero.yaml``
+* Any file passed to ARGV like so ``tapicero start -- /etc/tapicero.yaml``
 
-Run in foreground to see if it works:
+Files that come later will overwrite settings from the former.
 
-    tapicero run -- test/config/config.yaml
-    create a new record in the users database
-    observe /var/log/syslog or the logfile you specified
+### Sequence File
 
-Run as a deamon:
+Tapicero keeps track of the last change processed in a sequence file. The location of the sequence file is configured as `seq_file` and defaults to `/var/log/leap/tapicero.seq`
 
-    tapicero start
-    tapicero stop
+After restarting Tapicero it will only process changes that happened after the change with the sequence id given in the sequence file. This behaviour can be altered by using the --rerun flag or removing the sequence file.
 
-Run once and then exit:
+### Logging
 
-    tapicero --run-once
-    This will create per user databases for all users created since
-    the last run and then exit.
+Tapicero logs it's activity to syslog in a production environment. Logging details can be configured via `log_level`
+Configure `log_file` if you want to log to a file instead of syslog.
 
 Flags
 ---------------------
@@ -66,11 +67,32 @@ Flags
 Combining these flags you can migrate the security settings of all existing per user databases.
 
 
-Configuration
+Installation
 ---------------------
 
-``tapicero`` reads the following configurations files, in this order:
+Tapicero is normally deployed as part of the leap platform. If you want to install it outside of this context these instructions are for you.
 
-* ``$(tapicero_source)/config/default.yaml``
-* ``/etc/leap/tapicero.yaml``
-* Any file passed to ARGV like so ``tapicero start -- /etc/tapicero.yaml
+Prerequisites:
+
+    sudo apt-get install ruby ruby-dev couchdb
+    # for development, you will also need git, bundle, and rake.
+
+From source:
+
+    git clone git://leap.se/tapicero
+    cd tapicero
+    bundle
+    bundle exec bin/tapicero {run, start, status, ...}
+
+From gem:
+
+    sudo gem install tapicero
+
+License
+--------
+
+This program is written in Ruby and is distributed under the following license:
+
+> GNU Affero General Public License
+> Version 3.0 or higher
+> http://www.gnu.org/licenses/agpl-3.0.html