Getting Started Guide.

6 files changed, 110 insertions, 17 deletions

diff --git a/doc/source/administration.guide.rst b/doc/source/administration.guide.rst
index 8c36d3d44..2d09bed71 100644
--- a/doc/source/administration.guide.rst
+++ b/doc/source/administration.guide.rst
@@ -30,5 +30,6 @@ Contents
    quickstart
    getting.started
    multi.node.install
+   nova.manage
    flags
    monitoring
diff --git a/doc/source/concepts.and.introduction.rst b/doc/source/concepts.and.introduction.rst
index 205529812..5810280b4 100644
--- a/doc/source/concepts.and.introduction.rst
+++ b/doc/source/concepts.and.introduction.rst
@@ -144,8 +144,7 @@ The nova-manage command is used to perform many essential functions for
 administration and ongoing maintenance of nova, such as user creation,
 vpn management, and much more.
 
-See :doc:`nova.manage` in the Administration Guide for more
-details.
+See doc:`nova.manage` in the Administration Guide for more details.
 
 
 Concept: Flags
diff --git a/doc/source/getting.started.rst b/doc/source/getting.started.rst
index a0148e4b6..6873c49cd 100644
--- a/doc/source/getting.started.rst
+++ b/doc/source/getting.started.rst
@@ -18,19 +18,31 @@
 Getting Started with Nova
 =========================
 
-This code base is continually changing so dependencies also change.
+This code base is continually changing, so dependencies also change.  If you
+encounter any problems, see the :doc:`reaching.out` page.
+The `contrib/nova.sh` script should be kept up to date, and may be a good
+resource to review when debugging.
 
 Dependencies
 ------------
 
 Related servers we rely on
 
-* RabbitMQ: messaging queue, used for all communication between components
+* **RabbitMQ**: messaging queue, used for all communication between components
 
 Optional servers
 
-* OpenLDAP: By default, the auth server uses the RDBMS-backed datastore by setting FLAGS.auth_driver to 'nova.auth.dbdriver.DbDriver'. But OpenLDAP (or LDAP) could be configured by specifying 'nova.auth.ldapdriver.LdapDriver'.  There is a script in the sources(nova/auth/slap.sh) to install a very basic openldap server on ubuntu.
-* ReDIS: There is a fake ldap driver that backends to redis. This was created for testing ldap implementation on systems that don't have an easy means to install ldap.
+* **OpenLDAP**: By default, the auth server uses the RDBMS-backed datastore by
+  setting FLAGS.auth_driver to `nova.auth.dbdriver.DbDriver`. But OpenLDAP
+  (or LDAP) could be configured by specifying `nova.auth.ldapdriver.LdapDriver`.
+  There is a script in the sources (`nova/auth/slap.sh`) to install a very basic
+  openldap server on ubuntu.
+* **ReDIS**: There is a fake ldap auth driver
+  `nova.auth.ldapdriver.FakeLdapDriver` that backends to redis. This was
+  created for testing ldap implementation on systems that don't have an easy
+  means to install ldap.
+* **MySQL**: Either MySQL or another database supported by sqlalchemy needs to
+  be avilable.  Currently, only sqlite3 an mysql have been tested.
 
 Python libraries that we use (from pip-requires):
 
@@ -38,7 +50,9 @@ Python libraries that we use (from pip-requires):
 
 Other libraries:
 
-* XenAPI: Needed only for Xen Cloud Platform or XenServer support. Available from http://wiki.xensource.com/xenwiki/XCP_SDK or http://community.citrix.com/cdn/xs/sdks.
+* **XenAPI**: Needed only for Xen Cloud Platform or XenServer support. Available
+  from http://wiki.xensource.com/xenwiki/XCP_SDK or
+  http://community.citrix.com/cdn/xs/sdks.
 
 External unix tools that are required:
 
@@ -53,7 +67,9 @@ External unix tools that are required:
 * open-iscsi and iscsitarget (if you use iscsi volumes)
 * aoetools and vblade-persist (if you use aoe-volumes)
 
-Nova uses cutting-edge versions of many packages. There are ubuntu packages in the nova-core ppa.  You can use add this ppa to your sources list on an ubuntu machine with the following commands::
+Nova uses cutting-edge versions of many packages. There are ubuntu packages in
+the nova-core ppa.  You can use add this ppa to your sources list on an ubuntu
+machine with the following commands::
 
   sudo apt-get install -y python-software-properties
   sudo add-apt-repository ppa:nova-core/ppa
@@ -68,34 +84,73 @@ Recommended
 Installation
 --------------
 
-Due to many changes it's best to rely on the `OpenStack wiki <http://wiki.openstack.org>`_ for installation instructions.
+You can install from packages for your particular Linux distribution if they are
+available.  Otherwise you can install from source by checking out the source
+files from the `Nova Source Code Repository <http://code.launchpad.net/nova>`_
+and running::
+
+    python setup.py install
 
 Configuration
 ---------------
 
-These instructions are incomplete, but we are actively updating the `OpenStack wiki <http://wiki.openstack.org>`_ with more configuration information.
-
-On the volume node
+Configuring the host system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Create a volume group (you can use an actual disk for the volume group as well)
+As you read through the Administration Guide you will notice configuration hints
+inline with documentation on the subsystem you are configuring.  Presented in
+this "Getting Started with Nova" document, we only provide what you need to
+get started as quickly as possible.  For a more detailed description of system
+configuration, start reading through :doc:`multi.node.install`.
 
-::
+* Create a volume group (you can use an actual disk for the volume group as
+  well)::
 
     # This creates a 1GB file to create volumes out of
     dd if=/dev/zero of=MY_FILE_PATH bs=100M count=10
     losetup --show -f MY_FILE_PATH
     # replace /dev/loop0 below with whatever losetup returns
+    # nova-volumes is the default for the --volume_group flag
     vgcreate nova-volumes /dev/loop0
 
+
+Configuring Nova
+~~~~~~~~~~~~~~~~
+
+Configuration of the entire system is performed through python-gflags.  The
+best way to track configuration is through the use of a flagfile.
+
+A flagfile is specified with the ``--flagfile=FILEPATH`` argument to the binary
+when you launch it.  Flagfiles for nova are typically stored in
+``/etc/nova/nova.conf``, and flags specific to a certain program are stored in
+``/etc/nova/nova-COMMAND.conf``.  Each configuration file can include another
+flagfile, so typically a file like ``nova-manage.conf`` would have as its first
+line ``--flagfile=/etc/nova/nova.conf`` to load the common flags before
+specifying overrides or additional options.
+
+A sample configuration to test the system follows::
+
+    --verbose
+    --nodaemon
+    --FAKE_subdomain=ec2
+    --auth_driver=nova.auth.dbdriver.DbDriver
+
 Running
 ---------
 
-Launch servers
+There are many parts to the nova system, each with a specific function.  They
+are built to be highly-available, so there are may configurations they can be
+run in (ie: on many machines, many listeners per machine, etc).  This part
+of the guide only gets you started quickly, to learn about HA options, see
+:doc:`multi.node.install`.
+
+Launch supporting services
 
 * rabbitmq
 * redis (optional)
+* mysql (optional)
 
-Launch nova components
+Launch nova components, each should have ``--flagfile=/etc/nova/nova.conf``
 
 * nova-api
 * nova-compute
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 3c05d721d..9a62570ed 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -30,7 +30,8 @@ Nova is written with the following design guidelines in mind:
 
 This documentation is generated by the Sphinx toolkit and lives in the source
 tree.  Additional documentation on Nova and other components of OpenStack can
-be found on the `OpenStack wiki`_.
+be found on the `OpenStack wiki`_.  Also see the :doc:`reaching.out` page for
+other ways to interact witht the community.
 
 .. _`OpenStack wiki`: http://wiki.openstack.org
 
@@ -44,6 +45,7 @@ Contents
    concepts.and.introduction
    administration.guide
    development.guide
+   reaching.out
 
 
 Indices and tables
diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst
index 91e3c9ccb..511ed2483 100644
--- a/doc/source/quickstart.rst
+++ b/doc/source/quickstart.rst
@@ -18,6 +18,14 @@
 Nova Quickstart
 ===============
 
+::
+
+    TODO(todd): * Document the assumptions about pluggable interfaces
+                  (sqlite3 instead of mysql, etc)
+                * Document env vars that can change things
+                  (USE_MYSQL, HOST_IP)
+
+
 The `contrib/novascript.sh` file in the source distribution is a script that
 will quickly set up nova to run on a single machine.  It is tested against
 Ubuntu only, but other distributions are forthcoming.
diff --git a/doc/source/reaching.out.rst b/doc/source/reaching.out.rst
new file mode 100644
index 000000000..0d8f675e0
--- /dev/null
+++ b/doc/source/reaching.out.rst
@@ -0,0 +1,28 @@
+..
+      Copyright 2010 United States Government as represented by the
+      Administrator of the National Aeronautics and Space Administration. 
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Reaching Out
+============
+
+The OpenStack community is a very friendly place.  Feel free to ask questions.
+This document points you to some of the places you may want to communicate
+with people at.
+
+::
+
+    TODO(todd): * Write This
+                * Don't end a sentence with a preposition