diff --git a/stack.sh b/stack.sh
index 8ef39fe..9a0f663 100755
--- a/stack.sh
+++ b/stack.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# **stack.sh** is rackspace cloudbuilder's opinionated openstack installation.
+# **stack.sh** is rackspace cloudbuilder's opinionated openstack dev installation.
 
 # Quit script on error
 set -o errexit
@@ -12,7 +12,7 @@
 DEST=/opt
 CMD=$1
 
-# Set hte destination directories for openstack projects
+# Set the destination directories for openstack projects
 NOVA_DIR=$DEST/nova
 DASH_DIR=$DEST/dash
 GLANCE_DIR=$DEST/glance
@@ -39,17 +39,9 @@
 
 SQL_CONN=sqlite:///$NOVA_DIR/nova.sqlite
 
-# clone a git repository to a location, or if it already
-# exists, fetch and checkout remote master
-function clone_or_up {
-    if [ -d $2 ]; then
-        echo commenting out update for now for speed
-        # cd $2
-        # git fetch origin
-        # git checkout origin/master
-    else
-        git clone $1 $2
-    fi
+# clone a git repository to a location
+function ginstall {
+    git clone $1 $2
 }
 
 # You should only have to run this once
@@ -60,43 +52,63 @@
     # install python requirements
     pip install `cat $DIR/pips/*`
 
-    # TODO: kill openstackx
-    clone_or_up https://github.com/cloudbuilders/nova.git $NOVA_DIR
-    clone_or_up https://github.com/cloudbuilders/openstackx.git $API_DIR
-    clone_or_up https://github.com/cloudbuilders/noVNC.git $NOVNC_DIR
-    clone_or_up https://github.com/cloudbuilders/openstack-dashboard.git $DASH_DIR
-    clone_or_up https://github.com/cloudbuilders/python-novaclient.git $NOVACLIENT_DIR
-    clone_or_up https://github.com/cloudbuilders/keystone.git $KEYSTONE_DIR
-    clone_or_up https://github.com/cloudbuilders/glance.git $GLANCE_DIR
+    # vm service
+    ginstall https://github.com/cloudbuilders/nova.git $NOVA_DIR
+    # a websockets/html5 or flash powered VNC console for vm instances
+    ginstall https://github.com/cloudbuilders/noVNC.git $NOVNC_DIR
+    # django powered web control panel for openstack
+    ginstall https://github.com/cloudbuilders/openstack-dashboard.git $DASH_DIR
+    # python client library to nova that dashboard (and others) use
+    ginstall https://github.com/cloudbuilders/python-novaclient.git $NOVACLIENT_DIR
+    # unified auth system (manages accounts/tokens)
+    ginstall https://github.com/cloudbuilders/keystone.git $KEYSTONE_DIR
+    # image catalog
+    ginstall https://github.com/cloudbuilders/glance.git $GLANCE_DIR
+    # openstackx is a collection of extensions to openstack.compute & nova 
+    # that is *deprecated*.  The code is being moved into python-novaclient & nova.
+    ginstall https://github.com/cloudbuilders/openstackx.git $API_DIR
 
-    mkdir -p $NOVA_DIR/instances
-    mkdir -p $NOVA_DIR/networks
-
-    # these components are imported into each other...
+    # setup our checkouts so they are installed into python path
+    # allowing `import nova` or `import glance.client`
     cd $NOVACLIENT_DIR; python setup.py develop
     cd $KEYSTONE_DIR; python setup.py develop
     cd $GLANCE_DIR; python setup.py develop
     cd $API_DIR; python setup.py develop
     cd $DASH_DIR/django-openstack; python setup.py develop
     cd $DASH_DIR/openstack-dashboard; python setup.py develop
-    # HACK: dash currently imports quantum even if you aren't using it
-    cd $DASH_DIR/openstack-dashboard
-    mkdir quantum
-    touch quantum/__init__.py
-    touch quantum/client.py
 
-    # attempt to load kvm and nbd modules
-    modprobe kvm || true
+    # attempt to load modules: kvm (hardware virt) and nbd (network block 
+    # device - used to manage qcow images)
     modprobe nbd || true
+    modprobe kvm || true
+    # if kvm wasn't running before we need to restart libvirt to enable it
     /etc/init.d/libvirt-bin restart
 
-    # install dashboard
+    # setup nova instance directory
+    mkdir -p $NOVA_DIR/instances
+
+    # if there is a partition labeled nova-instances use it (ext filesystems
+    # can be labeled via e2label)
+    if [ -L /dev/disk/by-label/nova-instances ]; then
+        mount -L nova-instances /$NOVA_DIR/instances
+    fi
+
+    # *Dashboard*: setup django application to serve via apache/wsgi
+
+    # Dash currently imports quantum even if you aren't using it.  Instead 
+    # of installing quantum we can create a simple module that will pass the 
+    # initial imports
+    mkdir $DASH_DIR/openstack-dashboard/quantum
+    touch $DASH_DIR/openstack-dashboard/quantum/__init__.py
+    touch $DASH_DIR/openstack-dashboard/quantum/client.py
+    # local_settings has 
     cd $DASH_DIR/openstack-dashboard
     cp local/local_settings.py.example local/local_settings.py
     dashboard/manage.py syncdb
-    # setup apache
-    mkdir $DASH_DIR/.blackhole
 
+    # *Setup Apache*
+    # create an empty directory to use as our 
+    mkdir $DASH_DIR/.blackhole
     # FIXME(ja): can't figure out how to make $DASH_DIR work in sed, also install to available/a2e it 
     cat $DIR/files/000-default.template | sed "s/%DASH_DIR%/\/opt\/dash/g" > /etc/apache2/sites-enabled/000-default
 
@@ -104,6 +116,7 @@
 
     mkdir -p /var/log/glance
 
+    # prepare initial images for loading into glance
     if [ ! -f $DEST/tty.tgz ]; then
         wget -c http://images.ansolabs.com/tty.tgz -O $DEST/tty.tgz
     fi
@@ -119,6 +132,8 @@
 NL=`echo -ne '\015'`
 
 function screen_it {
+    # nova api crashes if we start it with a regular screen command,
+    # so send the start command by forcing text into the window.
     screen -S nova -X screen -t $1
     screen -S nova -p $1 -X stuff "$2$NL"
 }
@@ -129,8 +144,8 @@
 
 if [ "$CMD" == "run" ] || [ "$CMD" == "run_detached" ]; then
 
+    # (re)create nova.conf
     rm -f $NOVA_DIR/bin/nova.conf
-
     add_nova_flag "--verbose"
     add_nova_flag "--nodaemon"
     add_nova_flag "--dhcpbridge_flagfile=$NOVA_DIR/bin/nova.conf"
@@ -143,32 +158,31 @@
     add_nova_flag "--osapi_extensions_path=$API_DIR/extensions"
     add_nova_flag "--vncproxy_url=http://$HOST_IP:6080"
     add_nova_flag "--vncproxy_wwwroot=$NOVNC_DIR/noVNC/noVNC"
-
+    add_nova_flag "--api_paste_config=$KEYSTONE_DIR/examples/paste/nova-api-paste.ini"
+    add_nova_flag "--image_service=nova.image.glance.GlanceImageService"
     if [ -n "$FLAT_INTERFACE" ]; then
         add_nova_flag "--flat_interface=$FLAT_INTERFACE"
     fi
 
-    add_nova_flag "--api_paste_config=$KEYSTONE_DIR/examples/paste/nova-api-paste.ini"
-    add_nova_flag "--image_service=nova.image.glance.GlanceImageService"
-
-    killall dnsmasq || true
+    # create a new named screen to store things in
     screen -d -m -S nova -t nova
     sleep 1
-    rm -f $NOVA_DIR/nova.sqlite
+
+    # Clean out the instances directory
     rm -rf $NOVA_DIR/instances/*
-    mkdir -p $NOVA_DIR/instances
-    # if there is a partition labeled nova-instances use it (ext filesystems
-    # can be labeled via e2label)
-    if [ -L /dev/disk/by-label/nova-instances ]; then
-        mount -L nova-instances /$NOVA_DIR/instances
-    fi
+
+    # delete traces of nova networks from prior runs
+    killall dnsmasq || true
     rm -rf $NOVA_DIR/networks
     mkdir -p $NOVA_DIR/networks
 
-    # create the database
+    # (re)create nova database
+    rm -f $NOVA_DIR/nova.sqlite
     $NOVA_DIR/bin/nova-manage db sync
-    rm -f keystone.db
-    # add default data
+
+    # initialize keystone with default users/endpoints
+    # FIXME(ja): move initial_data.sh into this script
+    rm -f /opt/keystone/keystone.db
     curl -OL https://raw.github.com/cloudbuilders/deploy.sh/master/initial_data.sh
     BIN_DIR=$KEYSTONE_DIR/bin bash initial_data.sh
 
@@ -178,11 +192,11 @@
     # create some floating ips
     $NOVA_DIR/bin/nova-manage floating create $FLOATING_RANGE
 
+    # delete existing glance images/database.  Glance will recreate the db
+    # when it is ran.
     rm -rf /var/lib/glance/images/*
     rm -f $GLANCE_DIR/glance.sqlite
 
-    # nova api crashes if we start it with a regular screen command,
-    # so send the start command by forcing text into the window.
     screen_it n-api "$NOVA_DIR/bin/nova-api"
     screen_it g-api "cd $GLANCE_DIR; bin/glance-api --config-file=etc/glance-api.conf"
     screen_it g-reg "cd $GLANCE_DIR; bin/glance-registry --config-file=etc/glance-registry.conf"