Merge branch 'update_platform_docs' into 'master'

Update platform docs

See merge request !1

3 files changed, 68 insertions, 92 deletions

diff --git a/pages/docs/platform/tutorials/configure-provider.md b/pages/docs/platform/tutorials/configure-provider.md
new file mode 100644
index 0000000..969d541
--- /dev/null
+++ b/pages/docs/platform/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/pages/docs/platform/tutorials/quick-start.md b/pages/docs/platform/tutorials/quick-start.md
index 132fd32..f886484 100644
--- a/pages/docs/platform/tutorials/quick-start.md
+++ b/pages/docs/platform/tutorials/quick-start.md
@@ -6,34 +6,34 @@
 Testing Leap platform with Vagrant
 ==================================
 
-There are two ways how you can setup leap platform 
+There are two ways how you can setup leap platform
 using vagrant.
 
 Use the leap_cli vagrant integration
 ------------------------------------
 
-Install leap_cli and leap_platform on your host, 
-configure a provider from scratch and use the 
+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 
+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 how 
+https://leap.se/en/docs/platform/tutorials/single-node-email how
 to setup a single node mail server.
 
 
 Using the Vagrantfile provided by Leap Platform
 -----------------------------------------------
 
-This is by far the easiest way. 
+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 0.6.1 platform branch with
+Clone the platform with
 
-    git clone -b 0.6.1 https://github.com/leapcode/leap_platform.git
+    git clone https://github.com/leapcode/leap_platform.git
 
-Start the vagrant box with 
+Start the vagrant box with
 
     cd leap_platform
     vagrant up
@@ -43,7 +43,7 @@ in order to use the provider!
 
 You can login via ssh with the systemuser `vagrant` and the same password.
 
-There are 2 users preconfigured: 
+There are 2 users preconfigured:
 
 . `testuser`  with pw `hallo123`
 . `testadmin` with pw `hallo123`
@@ -72,11 +72,12 @@ 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: 
+
+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 
+WARNING: Use offlineimap *only* for testing/debugging,
+because it will save the mails *decrypted* locally to
 your disk !
 
diff --git a/pages/docs/platform/tutorials/single-node-email.md b/pages/docs/platform/tutorials/single-node-email.md
index 8e7ff50..872d1da 100644
--- a/pages/docs/platform/tutorials/single-node-email.md
+++ b/pages/docs/platform/tutorials/single-node-email.md
@@ -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,7 +40,7 @@ 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 node and the services that will reside on it 
+* 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
@@ -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,47 +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:
+Alternately, you can install `leap_cli` from source, please refer to https://leap.se/git/leap_cli/README.md.
 
-    $ 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
-
-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.
-
-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 --recursive https://leap.se/git/leap_platform.git
-
 
 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
 
@@ -135,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 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:
+* 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.
 
-    $ cat provider.json
+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.
 
-Optionally, commit your provider directory using the version control software you fancy. For example:
-
-    $ 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:
 
@@ -157,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
 ----------------------------
 
@@ -169,39 +137,15 @@ 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
-
-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.
-
-
-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
-
 
 Setup the provider's node and services
 --------------------------------------
 
 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":
+Create a node, with `all the services needed for Email: "couchdb", "mx", "soledad" and "webapp"`
 
-    $ leap node add node1 ip_address:x.x.x.w services:couchdb,mx,soledad,webapp tags:production
+    $ leap node add node1 ip_address:x.x.x.w services:couchdb,mx,soledad,webapp
 
 NOTE: replace x.x.x.w with the actual IP address of this node
 
@@ -212,9 +156,9 @@ 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
+    $ leap node init node1
 
-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.
+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.
 
 
 Deploy the LEAP platform to the nodes