Added documentation for static / bare metal installation.

contrib/digitalocean/provision-digitalocean-controller.sh

@@ -5,30 +5,24 @@
 # Retrieve the region-id by using `knife digital_ocean region list`
 #
 
+if [[ -z $1 ]]; then
+  echo usage: $0 [region]
+  exit 1
+fi
+
 function echo_color {
   echo -e "\033[1m$1\033[0m"
 }
 
-function usage {
-  echo_color "Usage: provision-digitalocean-controller.sh <region-id>"
-}
-
 THIS_DIR=$(cd $(dirname $0); pwd) # absolute path
 CONTRIB_DIR=$(dirname $THIS_DIR)
 
-if [[ -z $1 ]]; then
-  usage
-  exit 1
-fi
-
 # check for Deis' general dependencies
 if ! $CONTRIB_DIR/check-deis-deps.sh; then
   echo 'Deis is missing some dependencies.'
   exit 1
 fi
 
-echo_color "Provisioning a deis controller on Digital Ocean!"
-
 # connection details for using digital ocean's API
 client_id=$DIGITALOCEAN_CLIENT_ID
 api_key=$DIGITALOCEAN_API_KEY
@@ -45,14 +39,13 @@ fi
 #################
 # chef settings #
 #################
-
 node_name=deis-controller
 run_list="recipe[deis::controller]"
 chef_version=11.6.2
 
-##########################
-# digital ocean settings #
-##########################
+#########################
+# digitalocean settings #
+#########################
 
 # the name of the location we want to work with
 region_id=$1
@@ -75,8 +68,7 @@ fi
 ################
 # SSH settings #
 ################
-
-key_name="deis-controller"
+key_name=deis-controller
 ssh_key_path=~/.ssh/$key_name
 
 # create ssh keypair and store it
@@ -110,15 +102,15 @@ echo_color "Provisioning $node_name with knife digital_ocean..."
 
 set -x
 knife digital_ocean droplet create \
-    --bootstrap-version $chef_version \
-    --server-name $node_name \
-    --image $image_id \
-    --location $region_id \
-    --size $size_id \
-    --ssh-keys $ssh_key_id \
-    --identity-file $ssh_key_path \
-    --bootstrap \
-    --run-list $run_list
+  --bootstrap-version $chef_version \
+  --server-name $node_name \
+  --image $image_id \
+  --location $region_id \
+  --size $size_id \
+  --ssh-keys $ssh_key_id \
+  --identity-file $ssh_key_path \
+  --bootstrap \
+  --run-list $run_list
 set +x
 
 # Need Chef admin permission in order to add and remove nodes and clients

contrib/ec2/provision-ec2-controller.sh

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+#
+# Usage: ./provision-ec2-controller.sh <region>
+#
 
 if [ -z $1 ]; then
   echo usage: $0 [region]

contrib/rackspace/provision-rackspace-controller.sh

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+#
+# Usage: ./provision-rackspace-controller.sh <region>
+#
 
 if [ -z $1 ]; then
   echo usage: $0 [region]

contrib/vagrant/provision-controller.sh

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+#
+# Usage: ./provision-vagrant-controller.sh
+#
 
 function echo_color {
   echo -e "\033[1m$1\033[0m"

docs/installation/digitalocean.rst

@@ -2,6 +2,8 @@
 :description: How to install a Deis controller on DigitalOcean and create your private PaaS
 :keywords: install, installation, deis, controller, setup, digitalocean
 
+.. _digitalocean_installation:
+
 DigitalOcean Installation
 =========================
 

docs/installation/ec2.rst

@@ -2,6 +2,8 @@
 :description: How to install a Deis controller on Amazon EC2 and create your private PaaS
 :keywords: install, installation, deis, controller, setup, amazon, ec2
 
+.. _ec2_installation:
+
 Amazon EC2 Installation
 =======================
 

docs/installation/index.rst

@@ -16,4 +16,5 @@ Installation
     ec2
     rackspace
     digitalocean
+    static
     vagrant

docs/installation/rackspace.rst

@@ -2,6 +2,8 @@
 :description: How to install a Deis controller on Rackspace and create your private PaaS
 :keywords: install, installation, deis, controller, setup, rackspace
 
+.. _rackspace_installation:
+
 Rackspace Installation
 ======================
 

docs/installation/static.rst

@@ -0,0 +1,134 @@
+:title: Bare Metal Installation
+:description: How to install a Deis controller on existing hardware and create your private PaaS
+:keywords: install, installation, deis, controller, setup, bare metal, hardware
+
+.. _static_installation:
+
+Bare Metal Installation
+=======================
+
+.. include:: steps1-2.txt
+
+3. Provision a Deis Controller
+------------------------------
+
+To create the controller and nodes, the Deis system expects to find Ubuntu
+Linux machines running a Docker-compatible kernel. Ubuntu 12.04.3 LTS 64-bit
+is recommended.
+
+The `knife`_ command is used to bootstrap the controller. It should
+have been installed by ``bundle install``:
+
+.. code-block:: console
+
+    $ knife bootstrap --help
+    knife bootstrap FQDN (options)
+            --bootstrap-no-proxy [NO_PROXY_URL|NO_PROXY_IP]
+                                         Do not proxy locations for the node being bootstrapped
+            --bootstrap-proxy PROXY_URL  The proxy server for the node being bootstrapped
+            --bootstrap-version VERSION  The version of Chef to install
+        -N, --node-name NAME             The Chef node name for your new node
+            --server-url URL             Chef Server URL
+    ...
+
+Run `knife`_ to create Deis' data bags:
+
+.. code-block:: console
+
+    $ # create data bags
+    $ knife data bag create deis-users 2>/dev/null
+    Created data_bag[deis-users]
+    $ knife data bag create deis-formations 2>/dev/null
+    Created data_bag[deis-formations]
+    $ knife data bag create deis-apps 2>/dev/null
+    Created data_bag[deis-apps]
+
+Run `knife`_ again with appropriate arguments to bootstrap an existing instance
+with chef and install Deis' server components. This takes several minutes
+to complete:
+
+.. code-block:: console
+
+    $ # bootstrap the controller with knife
+    $ knife bootstrap 198.51.100.22 \
+    >  --bootstrap-version 11.6.2 \
+    >  --ssh-user ubuntu \
+    >  --sudo \
+    >  --identity-file ~/.ssh/id_rsa \
+    >  --node-name deis-controller \
+    >  --run-list "recipe[deis::controller]"
+    Bootstrapping Chef on 198.51.100.22
+    198.51.100.22 --2013-11-20 15:03:46--  https://www.opscode.com/chef/install.sh
+    198.51.100.22 HTTP request sent, awaiting response... 200 OK
+    198.51.100.22 Length: 6790 (6.6K) [application/x-sh]
+    198.51.100.22 Saving to: `STDOUT'
+    198.51.100.22
+    ...
+    198.51.100.22 Chef Client finished, 74 resources updated
+    198.51.100.22
+    + set +x
+    Please ensure that "deis-controller" is added to the Chef "admins" group.
+
+.. include:: steps3-4.txt
+
+5. Register With the Controller
+-------------------------------
+
+Registration will discover SSH keys automatically and use environment
+variables to configure supported cloud providers with your credentials.
+
+.. code-block:: console
+
+    $ sudo pip install deis
+    $ deis register http://deis.example.com
+    username: myuser
+    password:
+    password (confirm):
+    email: [email protected]
+    Registered myuser
+    Logged in as myuser
+
+    Found the following SSH public keys:
+    1) id_rsa.pub
+    Which would you like to use with Deis? 1
+    Uploading /Users/myuser/.ssh/id_rsa.pub to Deis... done
+
+6. Deploy a Formation and App
+-----------------------------
+
+Bare metal nodes have the same Docker-compatible requirements as the
+controller does: Ubuntu 12.04.3 LTS 64-bit is recommended.
+
+Create a "static" formation:
+
+.. code-block:: console
+
+    $ deis formations:create dev --flavor=static
+    Creating formation... done, created dev
+    Creating runtime layer... done in 1s
+    $ # if necessary, update runtime layer contents to access your nodes
+    $ deis layers:update dev runtime --ssh_username=myuser
+
+Prepare the node for provisioning by the controller:
+
+.. code-block:: console
+
+    $ # use some command-line wizardry to capture just the public key
+    $ ssh_key=$(deis layers:info dev runtime | \
+    >           grep -Eo '\"ssh_public_key\"\: \"(.*)\"' | \
+    >           cut -d\" -f4)
+    $ authfile=.ssh/authorized_keys
+    $ tmpfile=/tmp/authorized_keys.tmp
+    $ # prepend the layer's public key to the node's authorized_keys file
+    $ ssh [email protected] \
+    >  "echo $ssh_key|cat - $authfile > $tmpfile && mv $tmpfile $authfile"
+
+Scale up the formation by adding the existing node:
+
+.. code-block:: console
+
+    $ # add the node to the formation
+    $ deis nodes:create dev node1.example.com --layer=runtime
+    Creating node for node1.example.com... done in 107s
+
+.. include:: step6.txt

docs/installation/steps1-2.txt

@@ -1,11 +1,14 @@
-*Please note: Deis is still under active development. It should not yet be used in production.*
+**PLEASE NOTE:** *Deis is in active development. It should not yet be used in production.*
 
-Creating your own PaaS requires provisioning a Deis controller on a cloud
-provider of your choice, then registering an account on that controller with
-the Deis client.
+Creating your own PaaS requires provisioning a
+Deis :ref:`Controller <controller>`.
 
-Regardless of whether your controller is hosted with Amazon EC2, Rackspace,
-or DigitalOcean, it can create and manage nodes on any of those cloud providers.
+Regardless of whether you provision a controller on
+:ref:`Amazon EC2 <ec2_installation>`,
+:ref:`Rackspace <rackspace_installation>`,
+:ref:`DigitalOcean <digitalocean_installation>`,
+or your own :ref:`bare metal <static_installation>`, it can create and manage
+nodes on any of those cloud providers.
 
 Prerequisites
 -------------
@@ -23,7 +26,7 @@ on a Chef server accessible with `knife`_.
 
 Cloning the default master branch will provide you with the latest development
 version of Deis. If you instead want to deploy the latest stable release,
-checkout the most recent tag using ``git checkout v0.1.1``, for example.
+checkout the most recent tag using ``git checkout v0.3.0``, for example.
 
 2. Configure the Chef Server
 ----------------------------

docs/installation/steps3-4.txt

@@ -20,7 +20,7 @@ Install the Deis client with `pip`_:
 
     $ pip install deis
     Downloading/unpacking deis
-      Downloading deis-0.1.1.tar.gz
+      Downloading deis-0.3.0.tar.gz
       Running setup.py egg_info for package deis
     ...
     Successfully installed deis

docs/installation/vagrant.rst

@@ -2,6 +2,8 @@
 :description: How to install a Deis controller on Vagrant for testing
 :keywords: install, installation, deis, controller, setup, vagrant, virtualbox, testing
 
+.. _vagrant_installation:
+
 Vagrant Installation
 ====================