From 3a8dadd4d31dd564a08a9e285cc6f3318dc243b3 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Thu, 4 Nov 2010 17:36:32 -0400 Subject: [PATCH] Getting Started Guide. --- doc/source/administration.guide.rst | 1 + doc/source/concepts.and.introduction.rst | 3 +- doc/source/getting.started.rst | 83 ++++++++++++++++++++---- doc/source/index.rst | 4 +- doc/source/quickstart.rst | 8 +++ doc/source/reaching.out.rst | 28 ++++++++ 6 files changed, 110 insertions(+), 17 deletions(-) create mode 100644 doc/source/reaching.out.rst diff --git a/doc/source/administration.guide.rst b/doc/source/administration.guide.rst index 8c36d3d44f2e..2d09bed717f4 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 2055298122ee..5810280b43aa 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 a0148e4b6871..6873c49cd8f7 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 `_ 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 `_ +and running:: + + python setup.py install Configuration --------------- -These instructions are incomplete, but we are actively updating the `OpenStack wiki `_ with more configuration information. +Configuring the host system +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -On the volume node +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) - -:: +* 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 3c05d721de79..9a62570ed66e 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 91e3c9ccbb5a..511ed24835c0 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 000000000000..0d8f675e06cc --- /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