From 709849e717da1f0c509d0cf62414141e62a09eb7 Mon Sep 17 00:00:00 2001
From: Thatcher Peskens <thatcher@dotcloud.com>
Date: Tue, 26 Mar 2013 16:29:21 -0700
Subject: [PATCH] Added Amazon AWS tutorial (can be activated after @sub_'s
 pull request is accepted.

---
 .../documentation/installation/amazon.rst     | 95 +++++++++++++------
 .../documentation/installation/index.rst      |  1 +
 2 files changed, 65 insertions(+), 31 deletions(-)

diff --git a/docs/sources/documentation/installation/amazon.rst b/docs/sources/documentation/installation/amazon.rst
index 730a77e62c..5260b992bd 100644
--- a/docs/sources/documentation/installation/amazon.rst
+++ b/docs/sources/documentation/installation/amazon.rst
@@ -1,54 +1,87 @@
 Amazon EC2
 ==========
 
-
+    Please note this is a community contributed installation path. The only 'official' installation is using the :ref:`ubuntu_linux` installation path. This version
+    may be out of date because it depends on some binaries to be updated and published
 
 Installation
 ------------
 
-Install vagrant from http://www.vagrantup.com/ (or use your package manager)
+Docker can now be installed on Amazon EC2 with a single vagrant command. Vagrant 1.1 or higher is required.
 
-clone the repo
+1. Install vagrant from http://www.vagrantup.com/ (or use your package manager)
+2. Install the vagrant aws plugin
+
+   ::
+
+       vagrant plugin install vagrant-aws
 
 
-Docker can be installed with Vagrant on Amazon EC2, using Vagrant 1.1 is required for EC2, but deploying is as simple as:
+3. Get the docker sources, this will give you the latest Vagrantfile and puppet manifests.
 
-::
+   ::
 
-    $ export AWS_ACCESS_KEY_ID=xxx \
-        AWS_SECRET_ACCESS_KEY=xxx \
-        AWS_KEYPAIR_NAME=xxx \
-        AWS_SSH_PRIVKEY=xxx
-
-::
-
-    $ vagrant plugin install vagrant-aws
-
-::
-
-    $ vagrant up --provider=aws
-
-The environment variables are:
-
-* ``AWS_ACCESS_KEY_ID`` - The API key used to make requests to AWS
-* ``AWS_SECRET_ACCESS_KEY`` - The secret key to make AWS API requests
-* ``AWS_KEYPAIR_NAME`` - The ID of the keypair used for this EC2 instance
-* ``AWS_SSH_PRIVKEY`` - The path to the private key for the named keypair
+      git clone https://github.com/dotcloud/docker.git
 
 
-Make sure your default security zone on AWS includes rights to SSH to your container. Otherwise access will
-fail silently.
+4. Check your AWS environment.
+
+   Create a keypair specifically for EC2, give it a name and save it to your disk. *I usually store these in my ~/.ssh/ folder*.
+
+   Check that your default security group has an inbound rule to accept SSH (port 22) connections.
 
 
-.. code-block:: bash
 
-    vagrant ssh
+5. Inform Vagrant of your settings
 
-Now you are in the VM, run docker
+   Vagrant will read your access credentials from your environment, so we need to set them there first. Make sure
+   you have everything on amazon aws setup so you can (manually) deploy a new image to EC2.
 
-.. code-block:: bash
+   ::
 
-    docker
+       export AWS_ACCESS_KEY_ID=xxx
+       export AWS_SECRET_ACCESS_KEY=xxx
+       export AWS_KEYPAIR_NAME=xxx
+       export AWS_SSH_PRIVKEY=xxx
+
+   The environment variables are:
+
+   * ``AWS_ACCESS_KEY_ID`` - The API key used to make requests to AWS
+   * ``AWS_SECRET_ACCESS_KEY`` - The secret key to make AWS API requests
+   * ``AWS_KEYPAIR_NAME`` - The name of the keypair used for this EC2 instance
+   * ``AWS_SSH_PRIVKEY`` - The path to the private key for the named keypair, for example ``~/.ssh/docker.pem``
+
+   You can check if they are set correctly by doing something like
+
+   ::
+
+      echo $AWS_ACCESS_KEY_ID
+
+6. Do the magic!
+
+   ::
+
+      vagrant up --provider=aws
+
+
+   If it stalls indefinitely on ``[default] Waiting for SSH to become available...``, Double check your default security
+   zone on AWS includes rights to SSH (port 22) to your container.
+
+   If you have an advanced AWS setup, you might want to have a look at the https://github.com/mitchellh/vagrant-aws
+
+7. Connect to your machine
+
+   .. code-block:: bash
+
+      vagrant ssh
+
+8. Your first command
+
+   Now you are in the VM, run docker
+
+   .. code-block:: bash
+
+      docker
 
 
 Continue with the :ref:`hello_world` example.
\ No newline at end of file
diff --git a/docs/sources/documentation/installation/index.rst b/docs/sources/documentation/installation/index.rst
index 593004f813..095bc2bca7 100644
--- a/docs/sources/documentation/installation/index.rst
+++ b/docs/sources/documentation/installation/index.rst
@@ -15,3 +15,4 @@ Contents:
    ubuntulinux
    macos
    windows
+   amazon