Merge pull request #7 from azul/tapicero

Initial Tapicero documentation

3 files changed, 110 insertions, 1 deletions

diff --git a/docs/design/overview.md b/docs/design/overview.md
index 9818aa1..27d8883 100644
--- a/docs/design/overview.md
+++ b/docs/design/overview.md
@@ -125,7 +125,17 @@ These are the databases we currently use:
 * tickets -- help tickets issued in the webapp
 * tokens -- created by the webapp on login, used by soledad to authenticate
 * users -- user records used by the webapp including the authentication data
-* user-...id... -- client-encrypted data for the user with the given id accessed from the client via soledad
+* user-...id... -- client-encrypted user data accessed from the client via soledad
+
+### Database Setup
+
+The main couch databases are initially created, seeded and updated when deploying the platform.
+
+The site_couchdb module contains the database description and security settings in `manifests/create_dbs.pp`. The design docs are seeded from the files in `files/designs/:db_name`. If these files change the next puppet deploy will update the databases accordingly. Both the webapp and soledad have scripts that will dump the required design docs so they can be included here.
+
+The per-user databases are created upon user registration by [Tapicero](https://leap.se/docs/design/tapicero). Tapicero also adds security and design documents. The design documents for per-user databases are stored in the [tapicero repository](https://github.com/leapcode/tapicero) in `designs`. Tapicero can be used to update existing user databases with new security settings and design documents.
+
+### BigCouch
 
 Like many NoSQL databases, BigCouch is inspired by [Amazon's Dynamo paper](http://www.allthingsdistributed.com/files/amazon-dynamo-sosp2007.pdf) and works by sharding each database among many servers using a circular ring hash. The number of shards might be greater than the number of servers, in which case each server would have multiple shards of the same database. Each server in the BigCouch cluster appears to contain the entire database, but actually it will just proxy the request to the actual database that has the content (if it does not have the document itself).
 
diff --git a/docs/design/tapicero.md b/docs/design/tapicero.md
new file mode 100644
index 0000000..cb7be7c
--- /dev/null
+++ b/docs/design/tapicero.md
@@ -0,0 +1,98 @@
+@title = 'Tapicero'
+@summary = 'Creating per-user databases on the couch for soledad.'
+@toc = true
+
+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.
+
+Running
+--------------------
+
+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.
+
+Run in foreground:
+
+    bundle exec /bin/tapicero run
+
+Run as a deamon:
+
+    bundle exec /bin/tapicero start
+    bundle exec /bin/tapicero stop
+
+Run once, process all changes so far and then exit:
+
+    bundle exec tapicero --run-once
+
+Configuration
+---------------------
+
+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``
+
+Files that come later will overwrite settings from the former.
+
+### Sequence File
+
+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`
+
+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.
+
+### Logging
+
+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
+---------------------
+
+--run-once:
+  process the existing users and then exit
+
+--rerun:
+  also work on users that have been processed before
+
+--overwrite-security:
+  write the security settings even if the user database already has some
+
+Combining these flags you can migrate the security settings of all existing per user databases.
+
+
+Installation
+---------------------
+
+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.
+
+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
diff --git a/menu.txt b/menu.txt
index 3e729ef..7a0cfc6 100644
--- a/menu.txt
+++ b/menu.txt
@@ -14,6 +14,7 @@ docs
     overview
     nicknym
     soledad
+    tapicero
   platform
     quick-start
     guide