update readmes
diff --git a/stack.sh b/stack.sh
index cc70506..6115953 100755
--- a/stack.sh
+++ b/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 @@
#
# We try to have sensible defaults, so you should be able to run ``./stack.sh``
# in most cases.
-
-
-# FIXME: TALK ABOUT stackrc and localrc
-
-# Import variables
+#
+# We our settings from ``stackrc``. This file is distributed with devstack and
+# 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
+# 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 @@
# 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 @@
# 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 @@
# 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
- # we upload to glance with the glance cli tool.
+ # Debug Image (TTY)
+ # -----------------
+
+ # 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 @@
# 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 @@
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()"`