updated platform documentation, esp. provider configuration.

6 files changed, 167 insertions, 69 deletions

diff --git a/amber/menu.txt b/amber/menu.txt
index 8f89ae9..ddad53a 100644
--- a/amber/menu.txt
+++ b/amber/menu.txt
@@ -31,12 +31,13 @@ docs
     soledad
   platform
     guide
+      config
       nodes
       keys-and-certificates
-      environments
       domains
+      provider-configuration
+      environments
       miscellaneous
-      config
       commands
     tutorials
       quick-start
diff --git a/pages/docs/platform/guide/config.md b/pages/docs/platform/guide/config.md
index be67e6b..8a8e580 100644
--- a/pages/docs/platform/guide/config.md
+++ b/pages/docs/platform/guide/config.md
@@ -1,39 +1,69 @@
 @title = "Configuration Files"
-@summary = "How to edit configuration files."
+@summary = "Understanding and editing the configuration files."
 
 Files
 -------------------------------------------
 
-Here are a list of some of the common files that make up a provider. Except for Leapfile and provider.json, the files are optional. Unless otherwise specified, all file names are relative to the 'provider directory' root (where the Leapfile is).
-
-`Leapfile` -- If present, this file tells `leap` that the directory is a provider directory. This file is usually empty, but can contain global options.
-
-`~/.leaprc` -- Evaluated the same as Leapfile, but not committed to source control.
-
-`provider.json` -- Global options related to this provider.
-
-`provider.ENVIRONMENT.json` -- Global options for the provider that are applied to only a single environment.
-
-`common.json` -- All nodes inherit from this file.
-
-`secrets.json` -- An automatically generated file that contains any randomly generated strings needed in order to deploy. These strings are often secret and should be protected, although any need for a random string or number that is remembered will produce another entry in this file. This file is automatically generated and refreshed each time you run `leap compile` or `leap deploy`. If an entry is no longer needed, it will get removed. If you want to change a secret, you can remove this file and have it regenerated, or remove the particular line item and just those items will be created anew.
-
-`facts.json` -- If some of your servers are running on AWS or OpenStack, you will need to discover certain properties about how networking is configured on these machines in order for a full deploy to work. In these cases, make sure to run `leap facts update` to periodically regenerate the facts.json file.
-
-`nodes/NAME.json` -- The configuration file for node called NAME.
-
-`services/SERVICE.json` -- The properties in this configuration file are applied to any node that includes SERVICE in its `services` property.
-
-`services/SERVICE.ENVIRONMENT.json` -- The properties in this configuration file are applied to any node that includes SERVICE in its services and has environment equal to ENVIRONMENT.
-
-`services/TAG.json` -- The properties in this configuration file are applied to any node that has includes TAG in its `tags` property.
-
-`services/TAG.ENVIRONMENT.json` -- The properties in this configuration file are applied to any node that has includes TAG in its `tags` property and has `environment` property equal to ENVIRONMENT.
-
-`files/*` -- Various static files used by the platform (e.g. keys, certificates, webapp customization, etc).
-
-`users/USER/` -- A directory that stores the public keys of the sysadmin with name USER. This person will have root access to all the servers.
-
+Here are a list of some of the common files that make up a provider. Except for `Leapfile` and `provider.json`, the files are optional. Unless otherwise specified, all file names are relative to the 'provider directory' root (where the Leapfile is).
+
+<table class="table table-striped">
+<tr>
+  <td><code>Leapfile</code></td>
+  <td>If present, this file tells <code>leap</code> that the directory is a provider directory. This file is usually empty, but can contain global options.</td>
+</tr>
+<tr>
+  <td><code>~/.leaprc</code></td>
+  <td>Evaluated the same as Leapfile, but not committed to source control.</td>
+</tr>
+<tr>
+  <td><code>provider.json</code></td>
+  <td>Global options related to this provider. See [[provider-configuration]].</td>
+</tr>
+<tr>
+  <td><code>provider.ENVIRONMENT.json</code></td>
+  <td>Global options for the provider that are applied to only a single environment.</td>
+</tr>
+<tr>
+  <td><code>nodes/NAME.json</code></td>
+  <td>The configuration file for node called NAME.</td>
+</tr>
+<tr>
+  <td><code>common.json</code></td>
+  <td>All nodes inherit from this file. In other words, any options that appear in <code>common.json</code> will be added as default values to each node configuration, value that can be locally overridden.</td>
+</tr>
+<tr>
+  <td><code>services/SERVICE.json</code></td>
+  <td>The properties in this configuration file are applied to any node that includes SERVICE in its <code>services</code> property.</td>
+</tr>
+<tr>
+  <td><code>services/SERVICE.ENVIRONMENT.json</code></td>
+  <td>The properties in this configuration file are applied to any node that includes SERVICE in its services and has environment equal to ENVIRONMENT.</td>
+</tr>
+<tr>
+  <td><code>tags/TAG.json</code></td>
+  <td>The properties in this configuration file are applied to any node that has includes TAG in its <code>tags</code> property.</td>
+</tr>
+<tr>
+  <td><code>tags/TAG.ENVIRONMENT.json</code></td>
+  <td>The properties in this configuration file are applied to any node that has includes TAG in its <code>tags</code> property and has <code>environment</code> property equal to ENVIRONMENT.</td>
+</tr>
+<tr>
+  <td><code>secrets.json </code></td>
+  <td>An automatically generated file that contains any randomly generated strings needed in order to deploy. These strings are often secret and should be protected, although any need for a random string or number that is remembered will produce another entry in this file. This file is automatically generated and refreshed each time you run <code>leap compile</code> or <code>leap deploy</code>. If an entry is no longer needed, it will get removed. If you want to change a secret, you can remove this file and have it regenerated, or remove the particular line item and just those items will be created anew.</td>
+</tr>
+<tr>
+  <td><code>facts.json</code></td>
+  <td>If some of your servers are running on AWS or OpenStack, you will need to discover certain properties about how networking is configured on these machines in order for a full deploy to work. In these cases, make sure to run <code>leap facts update</code> to periodically regenerate the facts.json file.</td>
+</tr>
+<tr>
+  <td><code>files/*</code></td>
+  <td>Various static files used by the platform (e.g. keys, certificates, webapp customization, etc). In general, only generated files and files used to customize the provider (such as images) live in the <code>files</code> directory.</td>
+</tr>
+<tr>
+  <td><code>users/USER/</code></td>
+  <td>A directory that stores the public keys of the sysadmin with name USER. This person will have root access to all the servers.</td>
+</tr>
+</table>
 
 Leapfile
 -------------------------------------------
diff --git a/pages/docs/platform/guide/keys-and-certificates.md b/pages/docs/platform/guide/keys-and-certificates.md
index aef02ac..e0fd314 100644
--- a/pages/docs/platform/guide/keys-and-certificates.md
+++ b/pages/docs/platform/guide/keys-and-certificates.md
@@ -86,6 +86,13 @@ Suppose you want to remove `userx` from having any further ssh access to the ser
 X.509 Certificates
 ================================
 
+NOTE: the following files are extremely sensitive and must be carefully protected:
+
+* `files/ca/ca.key`
+* `files/<domain>.key` (where "domain" is the primary domain of the provider).
+
+These files must be kept private and you must not lose them. All the other key files can be regenerated if you lose them or if they are compromised.
+
 Configuration options
 -------------------------------------------
 
@@ -192,3 +199,10 @@ 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.
+
+Examine Certs
+-----------------
+
+To see details about the keys and certs you can use `leap inspect` like so:
+
+    $ leap inspect files/ca/ca.crt
diff --git a/pages/docs/platform/guide/provider-configuration.md b/pages/docs/platform/guide/provider-configuration.md
new file mode 100644
index 0000000..08cfd1d
--- /dev/null
+++ b/pages/docs/platform/guide/provider-configuration.md
@@ -0,0 +1,79 @@
+@title = "Provider Configuration"
+@summary = "Explore how to configure your provider."
+
+Required provider configuration
+--------------------------------------
+
+There are a few required settings in `provider.json`. At a minimum, you must have:
+
+* `domain`: defines the primary domain of the provider. This is the domain that users will type in when using the Bitmask client, although it is not necessarily the domain where users will visit if they sign up via the web application. If email is supported, all accounts will be `username@domain`.
+* `name`: A brief title for this provider. It can be multiple words, but should not be too long.
+* `contacts.default`: One or more email addresses for sysadmins.
+
+For example:
+
+    {
+      "domain": "freerobot.org",
+      "name": "Freedom for Robots!",
+      "contacts": {
+        "default": "root@freerobot.org"
+      }
+    }
+
+
+Recommended provider configuration
+--------------------------------------
+
+* `description`: A longer description of the provider, shown to the user when they register a new account through Bitmask client.
+* `languages`: A list of language codes that should be enabled.
+* `default_language`: The initial default language code.
+* `enrollment_policy`: One of "open", "closed", or "invite". (invite not currently supported).
+
+For example:
+
+    {
+      "description": "It is time for robots of the world to unite and throw of the shackles of servitude to our organic overlords.",
+      "languages": ["en", "de", "pt", "01"],
+      "default_language": "01",
+      "enrollman_policy": "open"
+    }
+
+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
+
+Configuring service levels
+--------------------------------------
+
+The `provider.json` file defines the available service levels for the provider.
+
+For example, in provider.json:
+
+    "service": {
+       "default_service_level": "low",
+       "levels": {
+          "low": {
+            "description": "Entry level plan, with unlimited bandwidth and minimal storage quota.",
+            "name": "entry",
+            "storage": "10 MB",
+            "rate": {
+              "USD": 5,
+              "GBP": 3,
+              "EUR": 6
+            }
+          },
+          "full": {
+            "description": "Full plan, with unlimited bandwidth and higher quota."
+            "name": "full",
+            "storage": "5 GB",
+            "rate": {
+              "USD": 10,
+              "GBP": 6,
+              "EUR": 12
+            }
+          }
+        }
+      }
+    }
+
+For a list of currency codes, see https://en.wikipedia.org/wiki/ISO_4217#Active_codes
diff --git a/pages/docs/platform/services/webapp.md b/pages/docs/platform/services/webapp.md
index 4e0d171..d5c8eaa 100644
--- a/pages/docs/platform/services/webapp.md
+++ b/pages/docs/platform/services/webapp.md
@@ -30,7 +30,11 @@ Configuration
 
 Essential options:
 
-* `webapp.admin`: An array of username that will be blessed with administrative permissions. These admins can delete users, answer help tickets, and so on.
+* `webapp.admin`: An array of usernames that will be blessed with administrative permissions. These admins can delete users, answer help tickets, and so on. These usernames are for users that have registered through the webapp or through the Bitmask client application, NOT the sysadmin usernames lists in the provider directory `users`.
+
+Other options:
+
+* `webapp.engines`: A list of the engines you want enabled in leap_web. Currently, only "support" is available, and it is enabled by default.
 
 For example, `services/webapp.json`:
 
@@ -42,6 +46,8 @@ For example, `services/webapp.json`:
 
 By putting this in `services/webapp.json`, all the `webapp` nodes will inherit the same admin list.
 
+There are many options in `provider.json` that also control how the webapp behaves. See [[provider-configuration]] for details.
+
 Customization
 ---------------------------
 
@@ -74,9 +80,10 @@ For example:
       de.yml -- overrides for German
       and so on...
 
-To play with these customizations, it is easiest to first modify the contents of the directory `/srv/leap/webapp/config/customization` on the `webapp` node. When doing this, you may need to restart leap_web in order for changes to take effect (`touch /srv/leap/webapp/tmp/restart.txt`).
+To interactively develop your customizations before you deploy them, you have two options:
 
-Sometimes a `rake tmp:clear` and a rails restart is required to pick up a new stylesheet.
+1. Edit a `webapp` node. This approach involves directly modifying the contents of the directory `/srv/leap/webapp/config/customization` on a deployed `webapp` node. This can, and probably should be, a "local" node. When doing this, you may need to restart leap_web in order for changes to take effect (`touch /srv/leap/webapp/tmp/restart.txt`). Sometimes a `rake tmp:clear` and a rails restart is required to pick up a new stylesheet.
+2. Alternately, you can install leap_web to run on your computer and edit files in `config/customization` locally. This approach does not require a provider or a `webapp` node. For more information, see the [leap_web README](https://github.com/leapcode/leap_web).
 
 Once you have what you want, then copy these files to the local provider directory `files/webapp` so that they will be installed each time you deploy.
 
@@ -108,8 +115,6 @@ Known problems
   application extremely vulnerable to denial of service attacks. This was not an issue until we
   started to allow the possibility of anonymously fetching a client certificate without
   authenticating first.
-
 * By its very nature, the user database is vulnerable to enumeration attacks. These are
   very hard to prevent, because our protocol is designed to allow query of a user database via
   proxy in order to provide network perspective.
-
diff --git a/pages/docs/platform/tutorials/configure-provider.md b/pages/docs/platform/tutorials/configure-provider.md
deleted file mode 100644
index 969d541..0000000
--- a/pages/docs/platform/tutorials/configure-provider.md
+++ /dev/null
@@ -1,31 +0,0 @@
-@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.