update readmes

stack.sh

@@ -4,7 +4,11 @@
 
 # This script installs and configures *nova*, *glance*, *dashboard* and *keystone*
 
-# FIXME: talk about single or multi-node installs
+# This script allows you to specify configuration options of what git 
+# repositories to use, enabled services, network configuration and various
+# passwords.  If you are crafty you can run the script on multiple nodes using
+# shared settings for common resources (mysql, rabbitmq) and build a multi-node
+# developer install.
 
 # To keep this script simple we assume you are running on an **Ubuntu 11.04
 # Natty** machine.  It should work in a VM or physical server.  Additionally we
@@ -95,11 +99,16 @@ set -o xtrace
 #
 # We try to have sensible defaults, so you should be able to run ``./stack.sh``
 # in most cases.
-
+#
-
+# We our settings from ``stackrc``.  This file is distributed with devstack and
-# FIXME: TALK ABOUT stackrc and localrc
+# contains locations for what repositories to use.  If you want to use other 
-
+# repositories and branches, you can add your own settings with another file 
-# Import variables
+# called ``localrc``
+#
+# If ``localrc`` exists, then ``stackrc`` will load those settings.  This is 
+# useful for changing a branch or repostiory to test other versions.  Also you
+# can store your other settings like **MYSQL_PASS** or **ADMIN_PASSWORD** instead
+# of letting devstack generate random ones for you.
 source ./stackrc
 
 # Destination path for installation ``DEST``
@@ -136,6 +145,9 @@ fi
 # Nova Network Configuration
 # --------------------------
 
+# FIXME: more documentation about why these are important flags.  Also 
+# we should make sure we use the same variable names as the flag names.
+
 PUBLIC_INTERFACE=${PUBLIC_INTERFACE:-eth0}
 FIXED_RANGE=${FIXED_RANGE:-10.0.0.0/24}
 FIXED_NETWORK_SIZE=${FIXED_NETWORK_SIZE:-256}
@@ -153,6 +165,17 @@ MULTI_HOST=${MULTI_HOST:-0}
 # If you are using FlatDHCP on multiple hosts, set the ``FLAT_INTERFACE``
 # variable but make sure that the interface doesn't already have an
 # ip or you risk breaking things.
+#
+# **DHCP Warning**:  If your flat interface device uses DHCP, there will be a 
+# hiccup while the network is moved from the flat interface to the flat network 
+# bridge.  This will happen when you launch your first instance.  Upon launch 
+# you will lose all connectivity to the node, and the vm launch will probably 
+# fail.
+# 
+# If you are running on a single node and don't need to access the VMs from 
+# devices other than that node, you can set the flat interface to the same
+# value as ``FLAT_NETWORK_BRIDGE``.  This will stop the network hiccup from 
+# occuring.
 FLAT_INTERFACE=${FLAT_INTERFACE:-eth0}
 
 ## FIXME(ja): should/can we check that FLAT_INTERFACE is sane?
@@ -568,14 +591,20 @@ screen_it dash "cd $DASH_DIR && sudo /etc/init.d/apache2 restart; sudo tail -f /
 # lets you login to it with username/password of user/password.  TTY is useful 
 # for basic functionality.  We all include an Ubuntu cloud build of **Natty**.
 # Natty uses cloud-init, supporting login via keypair and sending scripts as
-# userdata.  Read more about cloud-init at https://help.ubuntu.com/community/CloudInit
+# userdata.  
+#
+# Read more about cloud-init at https://help.ubuntu.com/community/CloudInit
 
 if [[ "$ENABLED_SERVICES" =~ "g-reg" ]]; then
     # create a directory for the downloadedthe images tarballs.
     mkdir -p $FILES/images
 
-    # Downloads a tty image (ami/aki/ari style), then extracts it.  Upon extraction
+    # Debug Image (TTY)
-    # we upload to glance with the glance cli tool.
+    # -----------------
+
+    # Downloads the image (ami/aki/ari style), then extracts it.  Upon extraction
+    # we upload to glance with the glance cli tool.  TTY is a stripped down 
+    # version of ubuntu.
     if [ ! -f $FILES/tty.tgz ]; then
         wget -c http://images.ansolabs.com/tty.tgz -O $FILES/tty.tgz
     fi
@@ -583,17 +612,20 @@ if [[ "$ENABLED_SERVICES" =~ "g-reg" ]]; then
     # extract ami-tty/image, aki-tty/image & ari-tty/image
     tar -zxf $FILES/tty.tgz -C $FILES/images
 
-    # add a debugging images to glance
+    # Use glance client to add the kernel, ramdisk and finally the root 
+    # filesystem.  We parse the results of the uploads to get glance IDs of the
+    # ramdisk and kernel and use them for the root filesystem.
     RVAL=`glance add -A $SERVICE_TOKEN name="tty-kernel" is_public=true container_format=aki disk_format=aki < $FILES/images/aki-tty/image`
     KERNEL_ID=`echo $RVAL | cut -d":" -f2 | tr -d " "`
     RVAL=`glance add -A $SERVICE_TOKEN name="tty-ramdisk" is_public=true container_format=ari disk_format=ari < $FILES/images/ari-tty/image`
     RAMDISK_ID=`echo $RVAL | cut -d":" -f2 | tr -d " "`
     glance add -A $SERVICE_TOKEN name="tty" is_public=true container_format=ami disk_format=ami kernel_id=$KERNEL_ID ramdisk_id=$RAMDISK_ID < $FILES/images/ami-tty/image
 
+    # Ubuntu 11.04 aka Natty
+    # ----------------------
 
-    # Ubuntu 11.04 aka Natty - downloaded from ubuntu enterprise cloud images.  This
+    # Downloaded from ubuntu enterprise cloud images.  This
     # image doesn't use the ramdisk functionality
-   
     if [ ! -f $FILES/natty.tgz ]; then
         wget -c http://uec-images.ubuntu.com/natty/current/natty-server-cloudimg-amd64.tar.gz -O $FILES/natty.tgz
     fi
@@ -623,8 +655,8 @@ if [[ "$ENABLED_SERVICES" =~ "key" ]]; then
     echo "the password: $ADMIN_PASSWORD"
 fi
 
-# Summary
+# Fin
-# =======
+# ===
 
 # End our timer and give a timing summary
 END_TIME=`python -c "import time; print time.time()"`