1 files changed, 98 insertions, 0 deletions
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