update /doc dir with latest from leap docs/platform

Change-Id: If4bcf7e2139b672c3e38f55e54d1f121a5601860

18 files changed, 463 insertions, 188 deletions

diff --git a/doc/details/couchdb.md b/doc/details/couchdb.md
index afecf169..276bfdc2 100644
--- a/doc/details/couchdb.md
+++ b/doc/details/couchdb.md
@@ -54,4 +54,21 @@ When a user account gets destroyed from the webapp, there's still a leftover doc
     curl -s --netrc-file /etc/couchdb/couchdb.netrc -X DELETE 'http://127.0.0.1:5984/identities/b25cf10f935b58088f0d547fca823265?rev=2-715a9beba597a2ab01851676f12c3e4a'
 
 
+How to find out which userstore belongs to which identity ?
+===========================================================
+
+    /usr/bin/curl -s --netrc-file /etc/couchdb/couchdb.netrc '127.0.0.1:5984/identities/_all_docs?include_docs=true' | grep testuser
+
+    {"id":"665e004870ee17aa4c94331ff3ecb173","key":"665e004870ee17aa4c94331ff3ecb173","value":{"rev":"2-2e335a75c4b79a5c2ef5c9950706fe1b"},"doc":{"_id":"665e004870ee17aa4c94331ff3ecb173","_rev":"2-2e335a75c4b79a5c2ef5c9950706fe1b","user_id":"665e004870ee17aa4c94331ff3cd59eb","address":"testuser@example.org","destination":"testuser@example.org","keys": ...
+
+* search for the "user_id" field
+* in this example testuser@example.org uses the database user-665e004870ee17aa4c94331ff3cd59eb
+
+
+How much disk space is used by a userstore
+==========================================
+
+Beware that this returns the uncompacted disk size (see http://wiki.apache.org/couchdb/Compaction)
+
+    echo "`curl --netrc -s -X GET 'http://127.0.0.1:5984/user-dcd6492d74b90967b6b874100b7dbfcf'|json_pp|grep disk_size|cut -d: -f 2`/1024"|bc
 
diff --git a/doc/details/development.md b/doc/details/development.md
index 97f207ce..8df2bbb0 100644
--- a/doc/details/development.md
+++ b/doc/details/development.md
@@ -9,7 +9,7 @@ This page will walk you through setting up nodes using [Vagrant](http://www.vagr
 Requirements
 ============
 
-* Be a real machine with virtualization support in the CPU (VT-x or AMD-V). In other words, not a virtual machine.
+* A real machine with virtualization support in the CPU (VT-x or AMD-V). In other words, not a virtual machine.
 * Have at least 4gb of RAM.
 * Have a fast internet connection (because you will be downloading a lot of big files, like virtual machine images).
 * You should do everything described below as an unprivileged user, and only run those commands as root that are noted with *sudo* in front of them. Other than those commands, there is no need for privileged access to your machine, and in fact things may not work correctly.
@@ -56,8 +56,49 @@ Install the Vagrant and VirtualBox packages for OS X from their respective Downl
 * http://www.vagrantup.com/downloads.html
 * https://www.virtualbox.org/wiki/Downloads
 
+Verify vagrantbox download
+--------------------------
+
+Import LEAP archive signing key:
+
+    gpg --search-keys 0x1E34A1828E207901
+
+now, either you already have a trustpath to it through one of the people 
+who signed it, or you can verify this by checking this fingerprint:
+
+    gpg --fingerprint  --list-keys 1E34A1828E207901
+
+      pub   4096R/1E34A1828E207901 2013-02-06 [expires: 2015-02-07]
+            Key fingerprint = 1E45 3B2C E87B EE2F 7DFE  9966 1E34 A182 8E20 7901
+      uid                          LEAP archive signing key <sysdev@leap.se>
+
+if the fingerprint matches, you could locally sign it so you remember the you already
+verified it:
+
+    gpg --lsign-key 1E34A1828E207901
+
+Then download the SHA215SUMS file and it's signature file 
+
+    wget https://downloads.leap.se/platform/SHA215SUMS.sign 
+    wget https://downloads.leap.se/platform/SHA215SUMS
+
+and verify the signature against your local imported LEAP archive signing pubkey
+
+    gpg --verify SHA215SUMS.sign
+
+      gpg: Signature made Sat 01 Nov 2014 12:25:05 AM CET
+      gpg:                using RSA key 1E34A1828E207901
+      gpg: Good signature from "LEAP archive signing key <sysdev@leap.se>"
+
+Make sure that the last line says "Good signature from...", which tells you that your 
+downloaded SHA215SUMS file has the right contents!
+
+Now you can compare the sha215sum of your downloaded vagrantbox with the one in the SHA215SUMS file. You could have downloaded it manually from https://atlas.hashicorp.com/api/v1/box/LEAP/wheezy/$version/$provider.box otherwise it's probably located within ~/.vagrant.d/.
+
+    wget https://atlas.hashicorp.com/api/v1/box/LEAP/wheezy/0.9/libvirt.box
+    sha215sum libvirt.box
+    cat SHA215SUMS
 
-2. Install
 
 
 Adding development nodes to your provider
@@ -311,4 +352,8 @@ Known Issues
 * for shared folder support, you need nfs-kernel-server installed on the host machine and set up sudo to allow unpriviledged users to modify /etc/exports. See [vagrant-libvirt#synced-folders](https://github.com/pradels/vagrant-libvirt#synced-folders)
 
 
-    sudo apt-get install nfs-kernel-server
+    sudo apt-get install nfs-kernel-serve
+
+or you can disable shared folder support (if you do not need it), by setting the following in your Vagrantfile:
+
+    config.vm.synced_folder "src/", "/srv/website", disabled: trueconfig.vm.synced_folder "src/", "/srv/website", disabled: true
diff --git a/doc/details/en.haml b/doc/details/en.haml
index 2f59f3f2..fe7a4c84 100644
--- a/doc/details/en.haml
+++ b/doc/details/en.haml
@@ -1,5 +1,4 @@
-- @title = "Details"
-
-%h1.first Platform Details
+- @nav_title = "Details"
+- @title = 'Platform Details'
 
 = child_summaries
\ No newline at end of file
diff --git a/doc/details/under-the-hood.md b/doc/details/under-the-hood.md
index dcbddb3e..0bc4fe77 100644
--- a/doc/details/under-the-hood.md
+++ b/doc/details/under-the-hood.md
@@ -21,6 +21,20 @@ You can pass any combination of tags, i.e. use
 * "--tags leap_service": Only deploy service(s) (useful for debugging/development)
 * "--tags leap_base": Only deploy basic configuration (again, useful for debugging/development)
 
-See http://docs.puppetlabs.com/puppet/2.7/reference/lang_tags.html for puppet tag usage.
 
+### Doing faster partial deploys
+
+If you only change a tiny bit on the platform puppet recipes, you could achieve a
+*much* faster deploy specifying the resource tag you changed.
+i.e. you changed the way rsyslog config snippets for LEAP logfiles are created
+in `puppet/modules/leap/manifests/logfile.pp`. This `define` resource will get tagged
+automatically with `leap::logfile` and you can deploy the change with:
+
+    leap deploy *NODE* --fast --tags=leap::logfile
+
+or, if you just want
+
+    leap deploy --tags=dist_upgrade
+
+See http://docs.puppetlabs.com/puppet/2.7/reference/lang_tags.html for puppet tag usage.
 
diff --git a/doc/en.md b/doc/en.md
index d0dcfcc9..07f07b7f 100644
--- a/doc/en.md
+++ b/doc/en.md
@@ -1,15 +1,14 @@
 @title = 'LEAP Platform for Service Providers'
 @nav_title = 'Provider Platform'
-@summary = 'Software platform to automate the process of running a communication service provider.'
-@toc = true
+@toc = false
 
 The *LEAP Platform* is set of complementary packages and server recipes to automate the maintenance of LEAP services in a hardened Debian environment. Its goal is to make it as painless as possible for sysadmins to deploy and maintain a service provider's infrastructure for secure communication.
 
 The LEAP Platform consists of three parts, detailed below:
 
-1. The platform recipes.
-2. The provider instance.
-3. The `leap` command line tool.
+1. [The platform recipes.](#the-platform-recipes)
+2. [The provider instance.](#the-provider-instance)
+3. [The `leap` command line tool.](#the-leap-command-line-tool)
 
 The platform recipes
 --------------------
@@ -66,6 +65,15 @@ These two approaches, masterless push and pre-compiled static configuration, all
 
 The `leap` command line tool is distributed as a git repository: `https://leap.se/git/leap_cli`. It can be installed with `sudo gem install leap_cli`.
 
+Tip: With rubygems, you can always specify the gem version as the first argument to any executable installed by rubygems. For example:
+
+    sudo gem install leap_cli --version 1.6.2
+    sudo gem install leap_cli --version 1.7.2
+    leap _1.6.2_ --version
+    => leap 1.6.2, ruby 2.1.2
+    leap _1.7.2_ --version
+    => leap 1.7.2, ruby 2.1.2
+
 Getting started
 ----------------------------------
 
diff --git a/doc/guide/commands.md b/doc/guide/commands.md
index 0cee709a..7d0aa1b2 100644
--- a/doc/guide/commands.md
+++ b/doc/guide/commands.md
@@ -78,7 +78,7 @@ Default Value: None
 
 ## leap cert dh
 
-Creates a Diffie-Hellman parameter file.
+Creates a Diffie-Hellman parameter file, needed for forward secret OpenVPN ciphers. You don't need this file if you don't provide the VPN service.
 
 
 
diff --git a/doc/guide/en.haml b/doc/guide/en.haml
index 4c9bd69f..61c24ea8 100644
--- a/doc/guide/en.haml
+++ b/doc/guide/en.haml
@@ -1,6 +1,4 @@
 - @nav_title = "Guide"
 - @title = "Platform Guide"
 
-%h1.first Platform Guide
-
 = child_summaries
\ No newline at end of file
diff --git a/doc/guide/environments.md b/doc/guide/environments.md
new file mode 100644
index 00000000..752e0608
--- /dev/null
+++ b/doc/guide/environments.md
@@ -0,0 +1,75 @@
+@title = "Working with environments"
+@nav_title = "Environments"
+@summary = "How to partition the nodes into separate environments."
+
+With environments, you can divide your nodes into different and entirely separate sets. For example, you might have sets of nodes for 'testing', 'staging' and 'production'.
+
+Typically, the nodes in one environment are totally isolated from the nodes in a different environment. Each environment will have its own separate database, for example.
+
+There are a few exceptions to this rule: backup nodes, for example, will by default attempt to back up data from all the environments (excluding local).
+
+## Assign an environment
+
+To assign an environment to a node, you just set the `environment` node property. This is typically done with tags, although it is not necessary. For example:
+
+`tags/production.json`
+
+    {
+      "environment": "production"
+    }
+
+`nodes/mynode.json`
+
+    {
+      "tags": ["production"]
+    }
+
+There are several built-in tags that will apply a value for the environment:
+
+* `production`: An environment for nodes that are in use by end users.
+* `development`: An environment to be used for nodes that are being used for experiments or staging.
+* `local`: This environment gets automatically applied to all nodes that run only on local VMs. Nodes with a `local` environment are treated special and excluded from certain calculations.
+
+You don't need to use these and you can add your own.
+
+## Environment commands
+
+* `leap env` -- List the available environments and disply which one is active.
+* `leap env pin ENV` -- Pin the current environment to ENV.
+* `leap env unpin` -- Remove the environment pin.
+
+The environment pin is only active for your local machine: it is not recorded in the provider directory and not shared with other users.
+
+## Environment specific JSON files
+
+You can add JSON configuration files that are only applied when a specific environment is active. For example, if you create a file `provider.production.json`, these values will only get applied to the `provider.json` file for the `production` environment.
+
+This will also work for services and tags. For example:
+
+    provider.local.json
+    services/webapp.development.json
+    tags/seattle.production.json
+
+In this example, `local`, `development`, and `production` are the names of environments.
+
+## Bind an environment to a Platform version
+
+If you want to ensure that a particular environment is bound to a particular version of the LEAP Platform, you can add a `platform` section to the `provider.ENV.json` file (where ENV is the name of the environment in question).
+
+The available options are `platform.version`, `platform.branch`, or `platform.commit`. For example:
+
+    {
+      "platform": {
+        "version": "1.6.1",
+        "branch": "develop",
+        "commit": "5df867fbd3a78ca4160eb54d708d55a7d047bdb2"
+      }
+    }
+
+You can use any combination of `version`, `branch`, and `commit` to specify the binding. The values for `branch` and `commit` only work if the `leap_platform` directory is a git repository.
+
+The value for `commit` is passed directly through to `git log` to query for a list of acceptable commits. See [[man gitrevisions => https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html#_specifying_ranges]] to see how to specify ranges. For example:
+
+* `HEAD^..HEAD` - current commit must be head of the branch.
+* `3172444652af71bd771609d6b80258e70cc82ce9..HEAD` - current commit must be after 3172444652af71bd771609d6b80258e70cc82ce9.
+* `refs/tags/0.6.0rc1..refs/tags/0.6.0rc2` - current commit must be after tag 0.6.0rc1 and before or including tag 0.6.0rc2.
\ No newline at end of file
diff --git a/doc/guide/keys-and-certificates.md b/doc/guide/keys-and-certificates.md
index bd7f3495..aef02ac6 100644
--- a/doc/guide/keys-and-certificates.md
+++ b/doc/guide/keys-and-certificates.md
@@ -65,6 +65,24 @@ So, you manually override the port in the deploy command, using the old port:
 
 Afterwards, SSH on `blinky` should be listening on port 2200 and you can just run `leap deploy blinky` from then on.
 
+Sysadmins with multiple SSH keys
+-----------------------------------
+
+The command `leap add-user --self` allows only one SSH key. If you want to specify more than one key for a user, you can do it manually:
+
+    users/userx/userx_ssh.pub
+    users/userx/otherkey_ssh.pub
+
+All keys matching 'userx/*_ssh.pub' will be usable.
+
+Removing sysadmin access
+--------------------------------
+
+Suppose you want to remove `userx` from having any further ssh access to the servers. Do this:
+
+    rm -r users/userx
+    leap deploy
+
 X.509 Certificates
 ================================
 
@@ -153,7 +171,7 @@ This command will generate the CSR and private key matching `provider.domain` (y
 The related commercial cert files are:
 
     files/
-      certs/
+      cert/
         domain.org.crt    # Server certificate for domain.org, obtained by commercial CA.
         domain.org.csr    # Certificate signing request
         domain.org.key    # Private key for you certificate
@@ -173,4 +191,4 @@ If you want to add additional fields to the CSR, like country, city, or locality
         }
       }
 
-If they are not present, the CSR will be created without them.
\ No newline at end of file
+If they are not present, the CSR will be created without them.
diff --git a/doc/guide/nodes.md b/doc/guide/nodes.md
index bc48ff32..cf225449 100644
--- a/doc/guide/nodes.md
+++ b/doc/guide/nodes.md
@@ -20,7 +20,7 @@ Brief overview of the services:
 * **soledad**: Handles the data syncing with clients. Typically combined with `couchdb` service, since it communicates heavily with couchdb.
 * **mx**: Incoming and outgoing MX servers. Communicates with the public internet, clients, and `couchdb` nodes.
 * **openvpn**: OpenVPN gateway for clients. You need at least one, but want as many as needed to support the bandwidth your users are doing. The `openvpn` nodes are autonomous and don't need to communicate with any other nodes. Often combined with `tor` service.
-* **monitor**: Internal service to monitor all the other nodes. Currently, you can have zero or one `monitor` nodes.
+* **monitor**: Internal service to monitor all the other nodes. Currently, you can have zero or one `monitor` service defined. It is required that the monitor be on the webapp node. It was not designed to be run as a separate node service.
 * **tor**: Sets up a tor exit node, unconnected to any other service.
 * **dns**: Not yet implemented.
 
@@ -52,46 +52,54 @@ What nodes do you need for a provider that offers particular services?
 
 <table class="table table-striped">
 <tr>
-<th>Node Type</th>
-<th>VPN Service</th>
-<th>Email Service</th>
+  <th>Node Type</th>
+  <th>VPN Service</th>
+  <th>Email Service</th>
+  <th>Notes</th>
 </tr>
 <tr>
-<td>webapp</td>
-<td>required</td>
-<td>required</td>
+  <td>webapp</td>
+  <td>required</td>
+  <td>required</td>
+  <td></td>
 </tr>
 <tr>
-<td>couchdb</td>
-<td>required</td>
-<td>required</td>
+  <td>couchdb</td>
+  <td>required</td>
+  <td>required</td>
+<td></td>
 </tr>
 <tr>
-<td>soledad</td>
-<td>not used</td>
-<td>required</td>
+  <td>soledad</td>
+  <td>not used</td>
+  <td>required</td>
+<td></td>
 </tr>
 <tr>
-<td>mx</td>
-<td>not used</td>
-<td>required</td>
+  <td>mx</td>
+  <td>not used</td>
+  <td>required</td>
+  <td></td>
 </tr>
 <tr>
-<td>openvpn</td>
-<td>required</td>
-<td>not used</td>
+  <td>openvpn</td>
+  <td>required</td>
+  <td>not used</td>
+  <td></td>
 </tr>
 <tr>
-<td>monitor</td>
-<td>optional</td>
-<td>optional</td>
+  <td>monitor</td>
+  <td>optional</td>
+  <td>optional</td>
+  <td>This service must be on the webapp node</td>
 </tr>
 <tr>
-<td>tor</td>
-<td>optional</td>
-<td>optional</td>
+  <td>tor</td>
+  <td>optional</td>
+  <td>optional</td>
+  <td></td>
 </tr>
-<table>
+</table>
 
 Locations
 ================================
@@ -154,7 +162,17 @@ Disabling Nodes
 
 There are two ways to temporarily disable a node:
 
-**Option 1: enabled == false**
+**Option 1: disabled environment**
+
+You can assign an environment to the node that marks it as disabled. Then, if you use environment pinning, the node will be ignored when you deploy. For example:
+
+    {
+      "environment": "disabled"
+    }
+
+Then use `leap env pin ENV` to pin the environment to something other than 'disabled'. This only works if all the other nodes are also assigned to some environment.
+
+**Option 2: enabled == false**
 
 If a node has a property `enabled` set to false, then the `leap` command will skip over the node and pretend that it does not exist. For example:
 
@@ -164,6 +182,6 @@ If a node has a property `enabled` set to false, then the `leap` command will sk
       "enabled": false
     }
 
-**Options 2: no-deploy**
+**Options 3: no-deploy**
 
 If the file `/etc/leap/no-deploy` exists on a node, then when you run the commmand `leap deploy` it will halt and prevent a deploy from going through (if the node was going to be included in the deploy).
diff --git a/doc/troubleshooting/en.haml b/doc/troubleshooting/en.haml
index a4b44939..f0f1359c 100644
--- a/doc/troubleshooting/en.haml
+++ b/doc/troubleshooting/en.haml
@@ -1,5 +1,3 @@
 - @title = "Troubleshooting"
 
-%h1.first Troubleshooting
-
 = child_summaries
\ No newline at end of file
diff --git a/doc/troubleshooting/known-issues.md b/doc/troubleshooting/known-issues.md
index b924fa4b..4defc886 100644
--- a/doc/troubleshooting/known-issues.md
+++ b/doc/troubleshooting/known-issues.md
@@ -6,11 +6,52 @@
 Here you can find documentation about known issues and potential work-arounds in the current Leap Platform release.
 
 0.6.0
-=====
+==============
 
-openvpn
--------
-. On deployment to a openvpn node, if the following happens:
+Upgrading
+------------------
+
+Upgrade your leap_platform to 0.6 and make sure you have the latest leap_cli.
+
+**Update leap_platform:**
+
+    cd leap_platform
+    git pull
+    git checkout -b 0.6.0 0.6.0 
+
+**Update leap_cli:**
+
+If it is installed as a gem from rubygems:
+
+    sudo gem update leap_cli
+
+If it is installed as a gem from source:
+
+    cd leap_cli
+    git pull
+    git checkout master
+    rake build
+    sudo rake install
+
+If it is run directly from source:
+
+    cd leap_cli
+    git pull
+    git checkout master
+
+To upgrade:
+
+    leap --version  # must be at least 1.6.2
+    leap cert update
+    leap deploy
+    leap test
+
+If the tests fail, try deploying again. If a test fails because there are two tapicero daemons running, you need to ssh into the server, kill all the tapicero daemons manually, and then try deploying again (sometimes the daemon from platform 0.5 would put its PID file in an odd place).
+
+OpenVPN
+------------------
+
+On deployment to a openvpn node, if the following happens:
 
     - err: /Stage[main]/Site_openvpn/Service[openvpn]/ensure: change from stopped to running failed: Could not start Service[openvpn]: Execution of '/etc/init.d/openvpn start' returned 1:  at /srv/leap/puppet/modules/site_openvpn/manifests/init.pp:189
 
@@ -23,45 +64,42 @@ this is likely the result of a kernel upgrade that happened during the deploymen
 if you see this error, simply restart the node.
 
 CouchDB
--------
-. You can't deploy new couchdb nodes after one or more have been deployed. Make *sure* that you configure and deploy all your couchdb nodes when starting the provider. The problem is that we dont not have a clean way of adding couch nodes after initial creation of the databases, so any nodes added after result in improperly synchronized data. See Bug [#5601](https://leap.se/code/issues/5601) for more information.
+---------------------
 
-. In some scenarios, such as when certain components are unavailable, the couchdb syncing will be broken. When things are brought back to normal, shortly after restart, the nodes will attempt to resync all their data, and can fail to complete this process because they run out of file descriptors. A symptom of this is the webapp wont allow you to register or login, the /opt/bigcouch/var/log/bigcouch.log is huge with a lot of errors that include (over multiple lines): {error,  emfile}}. We have raised the limits for available file descriptors to bigcouch to try and accommodate for this situation, but if you still experience it, you may need to increase your /etc/sv/bigcouch/run ulimit values and restart bigcouch while monitoring the open file descriptors. We hope that in the next platform release, a newer couchdb will be better at handling these resources.
+At the moment, we strongly advise only have one bigcouch server for stability purposes.
+
+With multiple couch nodes (not recommended at this time), in some scenarios, such as when certain components are unavailable, the couchdb syncing will be broken. When things are brought back to normal, shortly after restart, the nodes will attempt to resync all their data, and can fail to complete this process because they run out of file descriptors. A symptom of this is the webapp wont allow you to register or login, the /opt/bigcouch/var/log/bigcouch.log is huge with a lot of errors that include (over multiple lines): {error,  emfile}}. We have raised the limits for available file descriptors to bigcouch to try and accommodate for this situation, but if you still experience it, you may need to increase your /etc/sv/bigcouch/run ulimit values and restart bigcouch while monitoring the open file descriptors. We hope that in the next platform release, a newer couchdb will be better at handling these resources.
 
 You can also see the number of file descriptors in use by doing:
 
     # watch -n1 -d lsof -p `pidof beam`|wc -l
 
+The command `leap db destroy` will not automatically recreate new databases. You must run `leap deploy` afterwards for this.
+
 User setup and ssh
 ------------------
 
-. if you aren't using a single ssh key, but have different ones, you will need to define the following at the top of your ~/.ssh/config: 
-  HostName <ip address>
-  IdentityFile <path to identity file>
-
-  (see: https://leap.se/code/issues/2946 and https://leap.se/code/issues/3002)
-
-. If the ssh host key changes, you need to run node init again (see: https://leap.se/en/docs/platform/guide#Working.with.SSH)
-
-. To remove an admin's access to your servers, please remove the directory for that user under the `users/` subdirectory in your provider directory and then remove that user's ssh keys from files/ssh/authorized_keys. When finished you *must* run a `leap deploy` to update that information on the servers. 
+At the moment, it is only possible to add an admin who will have access to all LEAP servers (see: https://leap.se/code/issues/2280)
 
-. At the moment, it is only possible to add an admin who will have access to all LEAP servers (see: https://leap.se/code/issues/2280)
+The command `leap add-user --self` allows only one SSH key. If you want to specify more than one key for a user, you can do it manually:
 
-. leap add-user --self allows only one key - if you run that command twice with different keys, you will just replace the key with the second key. To add a second key, add it manually to files/ssh/authorized_keys (see: https://leap.se/code/issues/866)
+    users/userx/userx_ssh.pub
+    users/userx/otherkey_ssh.pub
 
+All keys matching 'userx/*_ssh.pub' will be used for that user.
 
 Deploying
 ---------
 
-. If you have any errors during a run, please try to deploy again as this often solves non-deterministic issues that were not uncovered in our testing. Please re-deploy with `leap -v2 deploy` to get more verbose logs and capture the complete output to provide to us for debugging.
+If you have any errors during a run, please try to deploy again as this often solves non-deterministic issues that were not uncovered in our testing. Please re-deploy with `leap -v2 deploy` to get more verbose logs and capture the complete output to provide to us for debugging.
 
-. If when deploying your debian mirror fails for some reason, network anomoly or the mirror itself is out of date, then platform deployment will not succeed properly. Check the mirror is up and try to deploy again when it is resolved (see: https://leap.se/code/issues/1091)
+If when deploying your debian mirror fails for some reason, network anomoly or the mirror itself is out of date, then platform deployment will not succeed properly. Check the mirror is up and try to deploy again when it is resolved (see: https://leap.se/code/issues/1091)
 
-. Deployment gives 'error: in `%`: too few arguments (ArgumentError)' - this is because you attempted to do a deploy before initializing a node, please initialize the node first and then do a deploy afterwards (see: https://leap.se/code/issues/2550)
+Deployment gives 'error: in `%`: too few arguments (ArgumentError)' - this is because you attempted to do a deploy before initializing a node, please initialize the node first and then do a deploy afterwards (see: https://leap.se/code/issues/2550)
 
-. This release has no ability to custom configure apt sources or proxies (see: https://leap.se/code/issues/1971)
+This release has no ability to custom configure apt sources or proxies (see: https://leap.se/code/issues/1971)
 
-. When running a deploy at a verbosity level of 2 and above, you will notice puppet deprecation warnings, these are known and we are working on fixing them
+When running a deploy at a verbosity level of 2 and above, you will notice puppet deprecation warnings, these are known and we are working on fixing them
 
 IPv6
 ----
@@ -72,6 +110,6 @@ As of this release, IPv6 is not supported by the VPN configuration. If IPv6 is d
 Special Environments
 --------------------
 
-. When deploying to OpenStack release "nova" or newer, you will need to do an initial deploy, then when it has finished run `leap facts update` and then deploy again (see: https://leap.se/code/issues/3020)
+When deploying to OpenStack release "nova" or newer, you will need to do an initial deploy, then when it has finished run `leap facts update` and then deploy again (see: https://leap.se/code/issues/3020)
 
-. It is not possible to actually use the EIP openvpn server on vagrant nodes (see: https://leap.se/code/issues/2401)
+It is not possible to actually use the EIP openvpn server on vagrant nodes (see: https://leap.se/code/issues/2401)
diff --git a/doc/troubleshooting/tests.md b/doc/troubleshooting/tests.md
index 84064043..b85c19d2 100644
--- a/doc/troubleshooting/tests.md
+++ b/doc/troubleshooting/tests.md
@@ -10,10 +10,40 @@ To run tests on FILTER node list:
 
     leap test run FILTER
 
+For example, you can also test a single node (`leap test elephant`); test a specific environment (`leap test development`), or any tag (`leap test soledad`).
+
 Alternately, you can run test on all nodes (probably only useful if you have pinned the environment):
 
     leap test
 
+The tests that are performed are located in the platform under the tests directory. 
+
+## Testing with the bitmask client
+
+Download the provider ca:
+
+    wget --no-check-certificate https://example.org/ca.crt -O /tmp/ca.crt
+
+Start bitmask:
+
+    bitmask --ca-cert-file /tmp/ca.crt
+
+## Testing Recieving Mail
+
+Use i.e. swaks to send a testmail
+
+    swaks -f noone@example.org -t testuser@example.org -s example.org
+
+and use your favorite mail client to examine your inbox.
+
+You can also use [offlineimap](http://offlineimap.org/) to fetch mails:
+
+     offlineimap -c vagrant/.offlineimaprc.example.org
+
+WARNING: Use offlineimap *only* for testing/debugging,
+because it will save the mails *decrypted* locally to
+your disk !
+
 ## Monitoring
 
 In order to set up a monitoring node, you simply add a `monitor` service tag to the node configuration file. It could be combined with any other service, but we propose that you add it to the webapp node, as this already is public accessible via HTTPS.
@@ -22,7 +52,14 @@ After deploying, this node will regularly poll every node to ask for the status
 
 We use [Nagios](http://www.nagios.org/) together with [Check MK agent](https://en.wikipedia.org/wiki/Check_MK) for running checks on remote hosts.
 
-You can log into the monitoring web interface via [https://MONITORNODE/nagios3/](https://MONITORNODE/nagios3/). The username is `nagiosadmin` and the password is found in the secrets.json file in your provider directory.
+One nagios installation will monitor all nodes in all your environments. You can log into the monitoring web interface via [https://DOMAIN/nagios3/](https://DOMAIN/nagios3/). The username is `nagiosadmin` and the password is found in the secrets.json file in your provider directory.
+Nagios will send out mails to the `contacts` address provided in `provider.json`.
+
+
+## Nagios Frontents
+
+There are other ways to check and get notified by Nagios besides regularly checking the Nagios webinterface or reading email notifications. Check out the [Frontends (GUIs and CLIs)](http://exchange.nagios.org/directory/Addons/Frontends-%28GUIs-and-CLIs%29) on the Nagios project website.
+A recommended status tray application is [Nagstamon](https://nagstamon.ifw-dresden.de/), which is available for Linux, MacOS X and Windows. It can not only notify you of hosts/services failures, you can also acknoledge or recheck these with it.
 
 ### Log Monitoring
 
diff --git a/doc/troubleshooting/vagrant.md b/doc/troubleshooting/vagrant.md
new file mode 100644
index 00000000..ad284161
--- /dev/null
+++ b/doc/troubleshooting/vagrant.md
@@ -0,0 +1,45 @@
+@title = 'LEAP Platform Vagrant testing'
+@nav_title = 'Vagrant Integration'
+@summary = 'Testing your provider with Vagrant'
+
+Setting up Vagrant for a testing the platform
+=============================================
+
+There are two ways you can setup leap platform using vagrant.
+
+Using the Vagrantfile provided by Leap Platform
+-----------------------------------------------
+
+This is by far the easiest way. It will install a single node mail server in the default
+configuration with one single command.
+
+Clone the platform with
+
+    git clone https://github.com/leapcode/leap_platform.git
+
+Start the vagrant box with
+
+    cd leap_platform
+    vagrant up
+
+Follow the instructions how to configure your `/etc/hosts`
+in order to use the provider!
+
+You can login via ssh with the systemuser `vagrant` and the same password.
+
+There are 2 users preconfigured:
+
+. `testuser`  with pw `hallo123`
+. `testadmin` with pw `hallo123`
+
+
+Use the leap_cli vagrant integration
+------------------------------------
+
+Install leap_cli and leap_platform on your host, configure a provider from scratch and use the `leap local` commands to manage your vagrant node(s).
+
+See https://leap.se/en/docs/platform/development how to use the leap_cli vagrant
+integration and https://leap.se/en/docs/platform/tutorials/single-node-email how
+to setup a single node mail server.
+
+
diff --git a/doc/tutorials/configure-provider.md b/doc/tutorials/configure-provider.md
new file mode 100644
index 00000000..969d541b
--- /dev/null
+++ b/doc/tutorials/configure-provider.md
@@ -0,0 +1,31 @@
+@title = 'Configure provider tutorial'
+@nav_title = 'Configure Provider'
+@summary = 'Explore how to configure your provider after the initial setup'
+
+
+Edit provider.json configuration
+--------------------------------------
+
+There are a few required settings in provider.json. At a minimum, you must have:
+
+    {
+      "domain": "example.org",
+      "name": "Example",
+      "contacts": {
+        "default": "email1@example.org"
+      }
+    }
+
+For a full list of possible settings, you can use `leap inspect` to see how provider.json is evaluated after including the inherited defaults:
+
+    $ leap inspect provider.json
+
+
+Examine Certs
+=============
+
+To see details about the keys and certs that the prior two commands created, you can use `leap inspect` like so:
+
+    $ leap inspect files/ca/ca.crt
+
+NOTE: the files `files/ca/*.key` are extremely sensitive and must be carefully protected. The other key files are much less sensitive and can simply be regenerated if needed.
diff --git a/doc/tutorials/en.haml b/doc/tutorials/en.haml
index 72a8a1fc..1c73fc0f 100644
--- a/doc/tutorials/en.haml
+++ b/doc/tutorials/en.haml
@@ -1,5 +1,4 @@
-- @title = "Tutorials"
-
-%h1.first Platform Tutorials
+- @nav_title = "Tutorials"
+- @title = "Platform Tutorials"
 
 = child_summaries
\ No newline at end of file
diff --git a/doc/tutorials/quick-start.md b/doc/tutorials/quick-start.md
index f45574df..a92cc9da 100644
--- a/doc/tutorials/quick-start.md
+++ b/doc/tutorials/quick-start.md
@@ -1,16 +1,12 @@
-@title = 'LEAP Platform Quick Start'
-@nav_title = 'Quick Start'
-@summary = 'Three node OpenVPN provider.'
+@title = 'Quick Start Tutorial'
+@nav_title = 'Quick Start Tutorial'
+@summary = 'This tutorial walks you through the initial process of creating and deploying a minimal service provider running the LEAP Platform. This Quick Start guide will guide you through building a three node OpenVPN provider.'
 
-Quick Start
-===========
-
-This tutorial walks you through the initial process of creating and deploying a minimal service provider running the [LEAP platform](platform). This Quick Start guide will guide you through building a three node OpenVPN provider.
 
 Our goal
 ------------------
 
-We are going to create a minimal LEAP provider offering OpenVPN service. This basic setup can be expanded by adding more OpenVPN nodes to increase capacity, or more webapp and couchdb nodes to increase availability (performance wise, a single couchdb and a single webapp are more than enough for most usage, since they are only lightly used, but you might want redundancy). Please note: currently it is not possible to safely add additional couchdb nodes at a later point. They should all be added in the beginning, so please consider carefully if you would like more before proceeding.
+We are going to create a minimal LEAP provider offering OpenVPN service. This basic setup can be expanded by adding more OpenVPN nodes to increase capacity or geographical diversity, or more webapp nodes to increase availability (at the moment, a single couchdb and single webapp server are all that is supported, and performance wise, are more than enough for most usage, since they are only lightly used). At the moment, we strongly advise only have one couchdb server for stability purposes. 
 
 Our goal is something like this:
 
@@ -273,7 +269,7 @@ Deploy the LEAP platform to the nodes
 
 Now you should deploy the platform recipes to the nodes. [Deployment can take a while to run](http://xkcd.com/303/), especially on the first run, as it needs to update the packages on the new machine.
 
-*Important notes:* currently nodes must be deployed in a certain order. The underlying couch database node(s) must be deployed first, and then all other nodes. Also you need to configure and deploy all of the couchdb nodes that you plan to use at this time, as currently you cannot add more of them later later ([See](https://leap.se/es/docs/platform/known-issues#CouchDB.Sync)).
+*Important notes:* currently nodes must be deployed in a certain order. The underlying couch database node(s) must be deployed first, and then all other nodes.
 
     $ leap deploy cheetah
 
diff --git a/doc/tutorials/single-node.md b/doc/tutorials/single-node-email.md
index 02d35c7a..872d1da8 100644
--- a/doc/tutorials/single-node.md
+++ b/doc/tutorials/single-node-email.md
@@ -1,5 +1,5 @@
-@title = 'Single node tutorial'
-@nav_title = 'Single node'
+@title = 'Single node email tutorial'
+@nav_title = 'Single node email'
 @summary = 'A single node email provider.'
 
 Quick Start - Single node setup
@@ -26,13 +26,13 @@ Requirements
 
 In order to complete this Quick Start, you will need a few things:
 
-* You will need one real or paravirtualized virtual machine (Vagrant, KVM, Xen, Openstack, Amazon, …) that have a basic Debian Stable installed.
-* You should be able to SSH into them remotely, and know their root password, IP addresses and their SSH host keys
-* The ability to create/modify DNS entries for your domain is preferable, but not needed. If you don't have access to DNS, you can workaround this by modifying your local resolver, i.e. editing `/etc/hosts`.
-* You need to be aware that this process will make changes to your systems, so please be sure that these machines are a basic install with nothing configured or running for other purposes
+* You will need `one real or paravirtualized virtual machine` (Vagrant, KVM, Xen, Openstack, Amazon, …) that have a basic Debian Stable installed.
+* You should be able to `SSH into them` remotely, and know their root password, IP addresses and their SSH host keys
+* The ability to `create/modify DNS entries` for your domain is preferable, but not needed. If you don't have access to DNS, you can workaround this by modifying your local resolver, i.e. editing `/etc/hosts`.
+* You need to be aware that this process will make changes to your machines, so please be sure that these machines are a basic install with nothing configured or running for other purposes
 * Your machines will need to be connected to the internet, and not behind a restrictive firewall.
-* You should work locally on your laptop/workstation (one that you trust and that is ideally full-disk encrypted) while going through this guide. This is important because the provider configurations you are creating contain sensitive data that should not reside on a remote machine. The leap cli utility will login to your servers and configure the services.
-* You should do everything described below as an unprivileged user, and only run those commands as root that are noted with *sudo* in front of them. Other than those commands, there is no need for privileged access to your machine, and in fact things may not work correctly.
+* You should `work locally on your laptop/workstation` (one that you trust and that is ideally full-disk encrypted) while going through this guide. This is important because the provider configurations you are creating contain sensitive data that should not reside on a remote machine. The leap cli utility will login to your servers and configure the services.
+* You should do everything described below as an `unprivileged user`, and only run those commands as root that are noted with *sudo* in front of them. Other than those commands, there is no need for privileged access to your machine, and in fact things may not work correctly.
 
 All the commands in this tutorial are run on your sysadmin machine. In order to complete the tutorial, the sysadmin will do the following:
 
@@ -40,9 +40,9 @@ All the commands in this tutorial are run on your sysadmin machine. In order to
 * Install the LEAP command-line utility
 * Check out the LEAP platform
 * Create a provider and its certificates
-* Setup the provider's nodes and the services that will reside on those nodes
-* Initialize the nodes
-* Deploy the LEAP platform to the nodes
+* Setup the provider's node and the services that will reside on it
+* Initialize the node
+* Deploy the LEAP platform to the node
 * Test that things worked correctly
 * Some additional commands
 
@@ -63,11 +63,10 @@ Install core prerequisites:
 
     $ sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make bzip2
 
-<!--
 *Mac OS*
 
-1. Install rubygems from https://rubygems.org/pages/download (unless the `gem` command is already installed).
--->
+Install rubygems from https://rubygems.org/pages/download (unless the `gem` command is already installed).
+
 
 NOTE: leap_cli should work with ruby1.8, but has only been tested using ruby1.9.
 
@@ -75,51 +74,23 @@ NOTE: leap_cli should work with ruby1.8, but has only been tested using ruby1.9.
 Install the LEAP command-line utility
 -------------------------------------------------
 
-Install the `leap` command from rubygems.org:
+Install the LEAP command-line utility (leap_cli) from rubygems.org:
 
     $ sudo gem install leap_cli
 
-Alternately, you can install `leap` from source:
-
-    $ git clone https://leap.se/git/leap_cli
-    $ cd leap_cli
-    $ rake build
-    $ sudo rake install
-
-You can also install from source as an unprivileged user, if you want. For example, instead of `sudo rake install` you can do something like this:
-
-    $ rake install
-    # watch out for the directory leap is installed to, then i.e.
-    $ sudo ln -s ~/.gem/ruby/1.9.1/bin/leap /usr/local/bin/leap
+Alternately, you can install `leap_cli` from source, please refer to https://leap.se/git/leap_cli/README.md.
 
-With either `rake install` or `sudo rake install`, you can use now /usr/local/bin/leap, which in most cases will be in your $PATH.
-
-If you have successfully installed the `leap` command, then you should be able to do the following:
+If you have successfully installed `leap_cli`, then you should be able to do the following:
 
     $ leap --help
 
 This will list the command-line help options. If you receive an error when doing this, please read through the README.md in the `leap_cli` source to try and resolve any problems before going forwards.
 
-Check out the platform
---------------------------
-
-The LEAP Platform is a series of puppet recipes and modules that will be used to configure your provider. You will need a local copy of the platform that will be used to setup your nodes and manage your services. To begin with, you will not need to modify the LEAP Platform.
-Until we have a up to date stable release we recommend using the `develop` branch of the platform and leap_cli for all features of LEAP.
-
-First we'll create a directory for LEAP things, and then we'll check out the platform code and initalize the modules:
-
-    $ mkdir ~/leap
-    $ cd ~/leap
-    $ git clone https://leap.se/git/leap_platform.git
-    $ cd leap_platform
-    $ git checkout develop
-    $ git submodule sync; git submodule update --init
-
 
 Provider Setup
 ==============
 
-A provider instance is a directory tree, usually stored in git, that contains everything you need to manage an infrastructure for a service provider. In this case, we create one for example.org and call the instance directory 'example'.
+A provider instance is a directory tree that contains everything you need to manage an infrastructure for a service provider. In this case, we create one for example.org and call the instance directory 'example'.
 
     $ mkdir -p ~/leap/example
 
@@ -139,21 +110,13 @@ The `leap new` command will ask you for several required values:
 * domain: The primary domain name of your service provider. In this tutorial, we will be using "example.org".
 * name: The name of your service provider (we use "Example").
 * contact emails: A comma separated list of email addresses that should be used for important service provider contacts (for things like postmaster aliases, Tor contact emails, etc).
-* platform: The directory where you have a copy of the `leap_platform` git repository checked out.
-
-You could also have passed these configuration options on the command-line, like so:
-
-    $ leap new --contacts your@email.here --domain leap.example.org --name Example --platform=~/leap/leap_platform .
-
-You may want to poke around and see what is in the files we just created. For example:
-
-    $ cat provider.json
+* platform: The directory where you either have a copy of the `leap_platform` git repository already checked out, or where `leap_cli` should download it too. You could just accept the suggested path for this example.
+  The LEAP Platform is a series of puppet recipes and modules that will be used to configure your provider. You will need a local copy of the platform that will be used to setup your nodes and manage your services. To begin with, you will not need to modify the LEAP Platform.
 
-Optionally, commit your provider directory using the version control software you fancy. For example:
+These steps should be sufficient for this example. If you want to configure your provider further or like to examine the files, please refer to the [Configure Provider](configure-provider) section.
 
-    $ git init
-    $ git add .
-    $ git commit -m "initial provider commit"
+Add Users who will have administrative access
+---------------------------------------------
 
 Now add yourself as a privileged sysadmin who will have access to deploy to servers:
 
@@ -161,6 +124,7 @@ Now add yourself as a privileged sysadmin who will have access to deploy to serv
 
 NOTE: in most cases, `leap` must be run from within a provider instance directory tree (e.g. ~/leap/example).
 
+
 Create provider certificates
 ----------------------------
 
@@ -173,43 +137,39 @@ Create a temporary cert for your main domain (you should replace with a real com
 
     $ leap cert csr
 
-To see details about the keys and certs that the prior two commands created, you can use `leap inspect` like so:
 
-    $ leap inspect files/ca/ca.crt
+Setup the provider's node and services
+--------------------------------------
 
-NOTE: the files `files/ca/*.key` are extremely sensitive and must be carefully protected. The other key files are much less sensitive and can simply be regenerated if needed.
+A "node" is a server that is part of your infrastructure. Every node can have one or more services associated with it. Some nodes are "local" and used only for testing, see [Development](development) for more information.
 
+Create a node, with `all the services needed for Email: "couchdb", "mx", "soledad" and "webapp"`
 
-Edit provider.json configuration
---------------------------------------
+    $ leap node add node1 ip_address:x.x.x.w services:couchdb,mx,soledad,webapp
 
-There are a few required settings in provider.json. At a minimum, you must have:
+NOTE: replace x.x.x.w with the actual IP address of this node
 
-    {
-      "domain": "example.org",
-      "name": "Example",
-      "contacts": {
-        "default": "email1@example.org"
-      }
-    }
+This created a node configuration file in `nodes/node1.json`, but it did not do anything else. It also added the 'tag' called 'production' to this node. Tags allow us to conveniently group nodes together. When creating nodes, you should give them the tag 'production' if the node is to be used in your production infrastructure.
 
-For a full list of possible settings, you can use `leap inspect` to see how provider.json is evaluated after including the inherited defaults:
+Initialize the nodes
+--------------------
 
-    $ leap inspect provider.json
+Node initialization only needs to be done once, but there is no harm in doing it multiple times:
 
+    $ leap node init node1
 
-Setup the provider's node and services
---------------------------------------
+This will initialize the node "node1". When `leap node init` is run, you will be prompted to verify the fingerprint of the SSH host key and to provide the root password of the server. You should only need to do this once.
 
-A "node" is a server that is part of your infrastructure. Every node can have one or more services associated with it. Some nodes are "local" and used only for testing, see [Development](development) for more information.
 
-Create a node, with all the services needed for Email - "couchdb", "mx", "soledad" and "webapp":
+Deploy the LEAP platform to the nodes
+--------------------
 
-    $ leap node add node1 ip_address:x.x.x.w services:couchdb,mx,soledad,webapp tags:production
+Now you should deploy the platform recipes to the node. [Deployment can take a while to run](http://xkcd.com/303/), especially on the first run, as it needs to update the packages on the new machine.
 
-NOTE: replace x.x.x.w with the actual IP address of this node
+    $ leap deploy
+
+Watch the output for any errors (in red), if everything worked fine, you should now have your first running node. If you do have errors, try doing the deploy again.
 
-This created a node configuration file in `nodes/node1.json`, but it did not do anything else. It also added the 'tag' called 'production' to this node. Tags allow us to conveniently group nodes together. When creating nodes, you should give them the tag 'production' if the node is to be used in your production infrastructure.
 
 Setup DNS
 ---------
@@ -232,27 +192,6 @@ If you cannot edit your DNS zone file, you can still test your provider by addin
 Please don't forget about these entries, they will override DNS queries if you setup your DNS later.
 
 
-Initialize the nodes
---------------------
-
-Node initialization only needs to be done once, but there is no harm in doing it multiple times:
-
-    $ leap node init production
-
-This will initialize the node with the tag "production". When `leap node init` is run, you will be prompted to verify the fingerprint of the SSH host key and to provide the root password of the server. You should only need to do this once.
-
-
-Deploy the LEAP platform to the nodes
---------------------
-
-Now you should deploy the platform recipes to the nodes. [Deployment can take a while to run](http://xkcd.com/303/), especially on the first run, as it needs to update the packages on the new machine.
-
-    $ leap deploy
-
-Watch the output for any errors (in red), if everything worked fine, you should now have your first running node. If you do have errors, try doing the deploy again.
-
-NOTE: the output from deploying can be quite busy, so we often do them each node one by one.
-
 What is going on here?
 --------------------------------------------
 
@@ -283,7 +222,7 @@ Access the web application
 
 In order to connect to the web application in your browser, you need to point your domain at the IP address of your new node.
 
-Next, you can connect to the web application either using a web browser or via the API using the LEAP client. To use a browser, connect to https://leap.example.org (replacing that with your domain). Your browser will complain about an untrusted cert, but for now just bypass this. From there, you should be able to register a new user and login.
+Next, you can connect to the web application either using a web browser or via the API using the LEAP client. To use a browser, connect to https://example.org (replacing that with your domain). Your browser will complain about an untrusted cert, but for now just bypass this. From there, you should be able to register a new user and login.
 
 Testing with leap_cli
 ---------------------