initial draft of platform documentation

4 files changed, 194 insertions, 0 deletions

diff --git a/docs/platform/command.md b/docs/platform/command.md
new file mode 100644
index 0000000..eda426b
--- /dev/null
+++ b/docs/platform/command.md
@@ -0,0 +1,3 @@
+leap command line reference
+
+(i am working on an auto dump of the --help text)
\ No newline at end of file
diff --git a/docs/platform/en.md b/docs/platform/en.md
new file mode 100644
index 0000000..35e8acd
--- /dev/null
+++ b/docs/platform/en.md
@@ -0,0 +1,51 @@
+LEAP Platform Tools
+
+Platform recipes (leap_platform)
+=================================
+
+The LEAP platform recipes define an abstract service provider. It consists of puppet modules designed to work together to provide a system administrator everything they need to manage a service provider infrastructure that provides secure communication services.
+
+Typically, a system administrator will not need to modify the LEAP platform recipes, although they are free to fork and merge as desired. Most service providers using the LEAP platform will use the same platform recipes.
+
+The recipes are abstract. In order to configure settings for a particular service provider, a system administrator creates a provider instance. The platform recipes also include a base provider that provider instances inherit from.
+
+Provider instance
+================================
+
+A "provider instance" is a directory tree (typically tracked in git) containing all the configurations for a service provider's infrastructure. A provider instance primarily consists of:
+
+* A configuration file for each server (node) in the provider's infrastructure (e.g. nodes/vpn1.json)
+* A global configuration file for the provider (e.g. provider.json).
+* Additional files, such as certificates and keys (e.g. files/nodes/vpn1/vpn1_ssh.pub).
+* A pointer to the platform recipes (as defined in "Leapfile")
+
+A minimal provider instance directory looks like this:
+
+    └── bitmask                 # provider instance directory
+        ├── common.json         # settings common to all nodes
+        ├── Leapfile            # specifies which platform recipe directory to use
+        ├── provider.json       # global settings of the provider
+        ├── files/              # keys, certificates, and other files.
+        ├── nodes/              # a directory for node configurations, one node per file
+        └── users/              # public key information for privileged sysadmins
+
+A provider instance directory contains everything needed to manage all the servers that compose a provider's infrastructure. Because of this, you can use normal git development work-flow to manage your provider instance.
+
+Command line program (leap_cli)
+=======================================
+
+The command line program `leap` is used by sysadmins to manage everything about a service provider's infrastructure. Except when creating an new provider instance, `leap` is run from within the directory tree of a provider instance.
+
+The `leap` command line has many capabilities, including:
+
+* Create, initialize, and deploy nodes (e.g. servers)
+* Manage keys and certificates
+* Query information about the node configurations
+
+Traditional system configuration automation systems, like puppet or chef, deploy changes to servers using a pull method. Each server pulls a manifest from a central master server and uses this to alter the state of the server.
+
+Instead, LEAP uses a masterless push method: The user runs 'leap deploy' from the provider instance directory on their desktop machine to push the changes out to every server (or a subset of servers). LEAP still uses puppet, but there is no central master server that each node must pull from.
+
+One other significant difference between LEAP and typical system automation is how interactions among servers are handled. Rather than store a central database of information about each server that can be queried when a recipe is applied, the `leap` command compiles static representation of all the information a particular server will need in order to apply the recipes. In compiling this static representation, `leap` can use arbitrary programming logic to query and manipulate information about other servers.
+
+These two approaches, masterless push and pre-compiled static configuration, allow the sysadmin to manage a set of LEAP servers using traditional software development techniques of branching and merging, to more easily create local testing environments using virtual servers, and to deploy without the added complexity and failure potential of a master server.
diff --git a/docs/platform/examples.md b/docs/platform/examples.md
new file mode 100644
index 0000000..b28b04f
--- /dev/null
+++ b/docs/platform/examples.md
@@ -0,0 +1,3 @@
+
+
+
diff --git a/docs/platform/quick-start.md b/docs/platform/quick-start.md
new file mode 100644
index 0000000..92d788e
--- /dev/null
+++ b/docs/platform/quick-start.md
@@ -0,0 +1,137 @@
+Installation
+--------------------------------
+
+Install prerequisites:
+
+    sudo apt-get install git ruby ruby-dev rsync openssh-client openssl
+
+This tutorial should work with ruby1.8, but has only been tested using ruby1.9.
+
+Install the `leap` command:
+
+    sudo gem install leap_cli
+
+Alternately, you can install `leap` from source:
+
+    git clone git://leap.se/leap_cli.git
+    cd leap_cli
+    rake build
+    rake install
+
+Create a provider instance
+---------------------------------------
+
+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 bitmask.net and call the instance directory 'bitmask'.
+
+    mkdir -p ~/leap/bitmask
+
+Now, we will initialize this directory to make it a provider instance. Your provider instance will need to know where it can find local copy of the git repository leap_platform, which holds the puppet recipes you will need to manage your servers. Typically, you will not need to modify leap_platform.
+
+    cd ~/leap/bitmask
+    leap init --domain bitmask.net --name Bitmask --platform ../leap_platform .
+
+In this case, `../leap_platform` will be created if it does not exist.
+
+You may want to poke around and see what is in the files we just created. For example:
+
+    cat provider.json
+
+Now add yourself as a privileged sysadmin who will have access to deploy to servers:
+
+    leap add-user --self
+
+NOTE: in most cases, `leap` must be run from within a provider instance directory tree (e.g. ~/leap/bitmask).
+
+Now generate required X509 certificates and keys:
+
+    leap cert ca
+    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
+
+Create nodes
+----------------------------------------
+
+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. These local nodes exist only as virtual machines on your computer and cannot be accessed from outside (see `leap help local` for more information).
+
+Create a local node, with the service "webapp":
+
+    leap node add --local web1 services:webapp
+
+This created a node configuration file, but it did not create the virtual machine. In order to test our node "web1", we need to first spin up a virtual machine. The next command will probably take a very long time, because it will need to download an image to create the virtual machine (about 700mb).
+
+    leap local start
+
+Now that the virtual machine for web1 is running, you need to initialize it and then deploy the recipes to it. You only need to initialize a node once, but there is no harm in doing it multiple times. These commands will take a while to run the first time, as it needs to update the package cache on the new virtual machine.
+
+    leap node init web1
+    leap deploy web1
+
+That is it, you should now have your first running node. However, the LEAP web application requires a database to run, so let's add a "couchdb" node:
+
+    leap node add --local db1 services:couchdb
+    leap local start
+    leap node init db1
+    leap deploy db1
+
+What is going on here?
+--------------------------------------------
+
+(explain about hiera files, general deploy process)
+
+Additional commands
+-------------------------------------------
+
+Here are a few useful commands you can run on your new local nodes:
+
+* `leap ssh web1` -- SSH into node web1 (requires `leap node init web1` first).
+* `leap list` -- list all nodes.
+* `leap list --print ip_address` -- list a particular attribute of all nodes.
+* `leap local reset web1` -- return web1 to a pristine state.
+* `leap local stop` -- stop all local virtual machines.
+* `leap local status` -- get the running state of all the local virtual machines.
+
+See the full command reference for more information.
+
+Node filters
+-------------------------------------------
+
+Many of the `leap` commands take a "node filter". You can use a node filter to target a command at one or more nodes.
+
+A node filter consists of one or more keywords, with an optional "+" before each keyword.
+
+* keywords can be a node name, a service type, or a tag.
+* the "+" before the keyword constructs an AND condition
+* otherwise, multiple keywords together construct an OR condition
+
+Examples:
+
+* `leap list openvpn` -- list all nodes with service openvpn.
+* `leap list openvpn +production` -- only nodes of service type openvpn AND tag production.
+* `leap deploy webapp openvpn` -- deploy to all webapp OR openvpn nodes.
+* `leap node init vpn1` -- just init the node named vpn1.
+
+Running on real hardware
+-----------------------------------
+
+The steps required to initialize and deploy to nodes on the public internet are basically the same as we have seen so far for local testing nodes. There are a few key differences:
+
+* Obviously, you will need to acquire a real or virtual machine that you can SSH into remotely.
+* When creating the node configuration, you should give it the tag "production" if the node is to be used in your production infrastructure.
+* When creating the node configuration, you need to specify the IP address of the node.
+
+For example:
+
+    leap node add vpn1 tags:production services:openvpn ip_address:4.4.4.4
+
+Also, running `leap node init NODE_NAME` on a real server will prompt you to verify the fingerprint of the SSH host key and to provide the root password of the server NODE_NAME. You should only need to do this once.
+
+What services do I need
+-----------------------------------
+
+Run `leap list` to see a list of available services.
+
+todo: link to another document that details the different service types and which are required.
+