document how to create new awsbox base images using cdist

doc/MAKE_AN_IMAGE.md

@@ -1,65 +1,54 @@
 ## How do I create a new base image?
 
-You may want to contribute an update to awsbox, or you may want a custom
-base image.  Either way, here's the set of steps to follow to create
-a new base image.
+awsbox creates an instance of your application by first creating a server
+from an awsbox machine image.  This image is pre-configured with nginx, node.js,
+git publishing, and more.
 
-### 1. Create a new VM
-
-    ./awsbox.js create -t c1.medium -n awsupdate
+The base image is creating using [cdist][], and you can yourself build a custom
+image to make whatever changes you desire.  Here's the steps:
 
-This step will create a new awsbox from the current machine image.  As part
-of that it will install the latest security updates (awsbox is kinda paternal
-that way - at machine creation, it will always install latest updates for you).
+[cdist]: http://www.nico.schottelius.org/software/cdist/
 
-**NOTE:** I often choose a c1.medium instance or larger for building new base
-images - because they are faster.  They're also more expensive, but typically
-short lived.
-
-At the conclusion of this step, you'll have a new awsbox sitting in your
-aws account.
+### 1. Create a new VM
 
-### 2. Do whatever you need to do!
+First create a new VM using the amazon console.  The only requirement is that the
+image is accessible by root via ssh without a password.  To make this possible
+on an amazon AMI you need to make two changes:
 
-You may want a different version of node, you may want to change some behaviors
-in the base image, you may want to do a myriad of things.
+1. uncomment `PermitRootLogin yes` in /etc/ssh/sshd_config
+2. restart sshd with `/etc/init.d/sshd restart`
+3. modify `~root/.ssh/authorized_keys` and remove the first part of the line that
+   tells you to log in as the ec2-user
 
-Once complete, you can move onto step 3 - but if you're curious how to update
-node (a pretty common thing to want to do), read on.
+verify you can ssh in as root, and you're done.
 
-So to update node, we'll first ssh in as the ec2-user:
+### 2. get cdist
 
-    ssh ec2-user@myawsboxip
+[cdist][] is a lightweight alternative to tools like [chef][] and [puppet][].  To
+use it, you need python 3 installed on your system.
 
-Next, let's download the version of node we want to install:
+  [chef]: http://www.getchef.com/
+  [puppet]: http://puppetlabs.com
 
-    wget http://nodejs.org/dist/v0.10.24/node-v0.10.24.tar.gz
+Next, you should get [version 3.0.7 of cdist][].
 
-After that, we'll unpack, configure and install node:
+  [version 3.0.7 of cdist]:  https://codeload.github.com/telmich/cdist/tar.gz/3.0.7
 
-    $ tar xvzf node-v0.10.24.tar.gz
-    $ cd node-v0.10.24
-    $ ./configure
-    $ make -j4
-    $ sudo make install
+you can put this wherever you want, simple is good, try this:
 
-Now that node is installed, we need to make sure that all node libraries that
-were compiled against the previous version of node will still run.  That's pretty
-simple - from your computer, do this:
+    curl https://codeload.github.com/telmich/cdist/tar.gz/3.0.7 | tar xz
 
-    $ ssh app@myawsboxip 'npm rebuild'
+### 3. provision your server
 
-This command will log you in as the `app` user (the user under whom applications
-run), and will rebuild all of the binary components used by node as that user.
+Using cdist, you can now provision the server you created in #2:
 
-All done!  You're ready to move on...
+    cdist-3.0.7/bin/cdist config -v -c .cdist <server ip>
 
-### 3. Create a new base image and update the AMI list
+### 4. Create a new base image and update the AMI list
 
-    ./awsbox.js createami
+    ./awsbox.js createami <instance id>
 
-This is going to take a while...  First this command will clean up the image,
-undoing specific configuration, removing command history, etc.  Next it will
+This is going to take a while...  First this will create an image.  Next it will
 copy that AMI into all availability zones, and finally it will write out the
 region specific AMI IDs to the JSON file `defaultImages.json`.
 
@@ -69,8 +58,4 @@ A successful result will be a local modification to defaultImages.
 
 Final step, test to see that this works as you want.  You can npm install your
 modified awsbox into one of your projects, or you can just try creating a new
-vm.  When satisfied, commit!  Now you've got a commit that you can build off of
-that uses your custom AMI.  (or you can send an upstream pull request).
-
-
-
+vm.  When satisfied, commit!  Now you've got a commit that uses new base amis.