update front page of devstack docs
The devstack docs have gotten a bit meandering so even the quick start
guide doesn't get you to a working setup without referencing other
pages. This attempts to pull this back in a bit.
Change-Id: I608331cbdae9cbe4f3e8bd3814415af0390a54d0
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 68ec174..c1302eb 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,163 +1,131 @@
-DevStack
-========
+.. Documentation Architecture for the devstack docs.
+
+ It is really easy for online docs to meander over time as people
+ attempt to add the small bit of additional information they think
+ people need, into an existing information architecture. In order to
+ prevent that we need to be a bit strict as to what's on this front
+ page.
+
+ This should *only* be the quick start narrative. Which should end
+ with 2 sections: what you can do with devstack once it's set up,
+ and how to go beyond this setup. Both should be a set of quick
+ links to other documents to let people explore from there.
+
+==========
+ DevStack
+==========
.. image:: assets/images/logo-blue.png
DevStack is a series of extensible scripts used to quickly bring up a
-complete OpenStack environment. It is used interactively as a
-development environment and as the basis for much of the OpenStack
-project's functional testing.
+complete OpenStack environment based on the latest versions of
+everything from git master. It is used interactively as a development
+environment and as the basis for much of the OpenStack project's
+functional testing.
The source is available at
`<https://git.openstack.org/cgit/openstack-dev/devstack>`__.
-.. toctree::
- :glob:
- :maxdepth: 1
+.. warning::
- overview
- configuration
- plugins
- plugin-registry
- faq
- hacking
+ DevStack will make substantial changes to your system during
+ installation. Only run DevStack on servers or virtual machines that
+ are dedicated to this purpose.
Quick Start
------------
+===========
-#. Select a Linux Distribution
-
- Only Ubuntu 14.04 (Trusty), Fedora 22 (or Fedora 23) and CentOS/RHEL
- 7 are documented here. OpenStack also runs and is packaged on other
- flavors of Linux such as OpenSUSE and Debian.
-
-#. Install Selected OS
-
- In order to correctly install all the dependencies, we assume a
- specific minimal version of the supported distributions to make it as
- easy as possible. We recommend using a minimal install of Ubuntu or
- Fedora server in a VM if this is your first time.
-
-#. Download DevStack
-
- ::
-
- git clone https://git.openstack.org/openstack-dev/devstack
-
- The ``devstack`` repo contains a script that installs OpenStack and
- templates for configuration files
-
-#. Configure
-
- We recommend at least a :ref:`minimal-configuration` be set up.
-
-#. Add Stack User
-
- Devstack should be run as a non-root user with sudo enabled
- (standard logins to cloud images such as "ubuntu" or "cloud-user"
- are usually fine).
-
- You can quickly create a separate `stack` user to run DevStack with
-
- ::
-
- devstack/tools/create-stack-user.sh; su stack
-
-#. Start the install, this will take a few minutes.
-
- ::
-
- cd devstack; ./stack.sh
-
-Guides
-======
-
-Walk through various setups used by stackers
-
-.. toctree::
- :glob:
- :maxdepth: 1
-
- guides/single-vm
- guides/single-machine
- guides/lxc
- guides/multinode-lab
- guides/neutron
- guides/devstack-with-nested-kvm
- guides/nova
- guides/devstack-with-lbaas-v2
-
-All-In-One Single VM
---------------------
-
-Run :doc:`OpenStack in a VM <guides/single-vm>`. The VMs launched in your cloud will be slow as
-they are running in QEMU (emulation), but it is useful if you don't have
-spare hardware laying around. :doc:`[Read] <guides/single-vm>`
-
-All-In-One Single Machine
--------------------------
-
-Run :doc:`OpenStack on dedicated hardware <guides/single-machine>` This can include a
-server-class machine or a laptop at home.
-:doc:`[Read] <guides/single-machine>`
-
-All-In-One LXC Container
--------------------------
-
-Run :doc:`OpenStack in a LXC container <guides/lxc>`. Beneficial for intermediate
-and advanced users. The VMs launched in this cloud will be fully accelerated but
-not all OpenStack features are supported. :doc:`[Read] <guides/lxc>`
-
-Multi-Node Lab
---------------
-
-Setup a :doc:`multi-node cluster <guides/multinode-lab>` with dedicated VLANs for VMs & Management.
-:doc:`[Read] <guides/multinode-lab>`
-
-DevStack with Neutron Networking
---------------------------------
-
-Building a DevStack cluster with :doc:`Neutron Networking <guides/neutron>`.
-This guide is meant for building lab environments with a dedicated
-control node and multiple compute nodes.
-
-DevStack with KVM-based Nested Virtualization
----------------------------------------------
-
-Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization
-<guides/devstack-with-nested-kvm>`. With this setup, Nova instances
-will be more performant than with plain QEMU emulation.
-
-Nova and devstack
---------------------------------
-
-Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
-
-DevStack Documentation
-======================
-
-Overview
---------
-
-:doc:`An overview of DevStack goals and priorities <overview>`
-
-Configuration
+Install Linux
-------------
-:doc:`Configuring and customizing the stack <configuration>`
+Start with a clean and minimal install of a Linux system. Devstack
+attempts to support Ubuntu 14.04/16.04, Fedora 23/24, CentOS/RHEL 7,
+as well as Debian and OpenSUSE.
-Plugins
+If you do not have a preference, Ubuntu 16.04 is the most tested, and
+will probably go the smoothest.
+
+Download DevStack
+-----------------
+
+::
+
+ git clone https://git.openstack.org/openstack-dev/devstack
+
+The ``devstack`` repo contains a script that installs OpenStack and
+templates for configuration files
+
+Create a local.conf
+-------------------
+
+Create a ``local.conf`` file with 4 passwords preset
+
+::
+
+ [[local|localrc]]
+ ADMIN_PASSWORD=secret
+ DATABASE_PASSWORD=$ADMIN_PASSWORD
+ RABBIT_PASSWORD=$ADMIN_PASSWORD
+ SERVICE_PASSWORD=$ADMIN_PASSWORD
+
+This is the minimum required config to get started with DevStack.
+
+Add Stack User
+--------------
+
+Devstack should be run as a non-root user with sudo enabled
+(standard logins to cloud images such as "ubuntu" or "cloud-user"
+are usually fine).
+
+You can quickly create a separate `stack` user to run DevStack with
+
+::
+
+ devstack/tools/create-stack-user.sh; su stack
+
+Start the install
+-----------------
+
+::
+
+ cd devstack; ./stack.sh
+
+This will take a 15 - 20 minutes, largely depending on the speed of
+your internet connection. Many git trees and packages will be
+installed during this process.
+
+Profit!
-------
-:doc:`Extending DevStack with new features <plugins>`
+You now have a working DevStack! Congrats!
-FAQ
----
+Your devstack will have installed ``keystone``, ``glance``, ``nova``,
+``cinder``, ``neutron``, and ``horizon``. Floating IPs will be
+available, guests have access to the external world.
-:doc:`The DevStack FAQ <faq>`
+You can access horizon to experience the web interface to
+OpenStack, and manage vms, networks, volumes, and images from
+there.
-Contributing
-------------
+You can ``source openrc`` in your shell, and then use the
+``openstack`` command line tool to manage your devstack.
-:doc:`Pitching in to make DevStack a better place <hacking>`
+You can ``cd /opt/stack/tempest`` and run tempest tests that have
+been configured to work with your devstack.
+Going further
+-------------
+
+Learn more about our :doc:`configuration system <configuration>` to
+customize devstack for your needs.
+
+Read :doc:`guides <guides>` for specific setups people have (note:
+guides are point in time contributions, and may not always be kept
+up to date to the latest devstack).
+
+Enable :doc:`devstack plugins <plugins>` to support additional
+services, features, and configuration not present in base devstack.
+
+Get :doc:`the big picture <overview>` of what we are trying to do
+with devstack, and help us by :doc:`contributing to the project
+<hacking>`.