1. devstack
  2. Commit cea7ec8d4bd9f93568eb2e9e05c306535f0ec292
Browse code

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

Sean Dague authored on 2016/08/05 21:29:54
Showing 3 changed files
doc/source/guides.rst
History View file @ cea7ec8
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,68 @@
0 
+Guides
1 
+======
2 
+
3 
+.. warning::
4 
+
5 
+   The guides are point in time contributions, and may not always be
6 
+   up to date with the latest work in devstack.
7 
+
8 
+Walk through various setups used by stackers
9 
+
10 
+.. toctree::
11 
+   :glob:
12 
+   :maxdepth: 1
13 
+
14 
+   guides/single-vm
15 
+   guides/single-machine
16 
+   guides/lxc
17 
+   guides/multinode-lab
18 
+   guides/neutron
19 
+   guides/devstack-with-nested-kvm
20 
+   guides/nova
21 
+   guides/devstack-with-lbaas-v2
22 
+
23 
+All-In-One Single VM
24 
+--------------------
25 
+
26 
+Run :doc:`OpenStack in a VM <guides/single-vm>`. The VMs launched in your cloud will be slow as
27 
+they are running in QEMU (emulation), but it is useful if you don't have
28 
+spare hardware laying around. :doc:`[Read] <guides/single-vm>`
29 
+
30 
+All-In-One Single Machine
31 
+-------------------------
32 
+
33 
+Run :doc:`OpenStack on dedicated hardware <guides/single-machine>`  This can include a
34 
+server-class machine or a laptop at home.
35 
+:doc:`[Read] <guides/single-machine>`
36 
+
37 
+All-In-One LXC Container
38 
+-------------------------
39 
+
40 
+Run :doc:`OpenStack in a LXC container <guides/lxc>`. Beneficial for intermediate
41 
+and advanced users. The VMs launched in this cloud will be fully accelerated but
42 
+not all OpenStack features are supported. :doc:`[Read] <guides/lxc>`
43 
+
44 
+Multi-Node Lab
45 
+--------------
46 
+
47 
+Setup a :doc:`multi-node cluster <guides/multinode-lab>` with dedicated VLANs for VMs & Management.
48 
+:doc:`[Read] <guides/multinode-lab>`
49 
+
50 
+DevStack with Neutron Networking
51 
+--------------------------------
52 
+
53 
+Building a DevStack cluster with :doc:`Neutron Networking <guides/neutron>`.
54 
+This guide is meant for building lab environments with a dedicated
55 
+control node and multiple compute nodes.
56 
+
57 
+DevStack with KVM-based Nested Virtualization
58 
+---------------------------------------------
59 
+
60 
+Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization
61 
+<guides/devstack-with-nested-kvm>`. With this setup, Nova instances
62 
+will be more performant than with plain QEMU emulation.
63 
+
64 
+Nova and devstack
65 
+--------------------------------
66 
+
67 
+Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
doc/source/index.rst
History View file @ cea7ec8
... ... 
@@ -1,163 +1,131 @@
1 
-DevStack
2 
-========
1 
+.. Documentation Architecture for the devstack docs.
2 
+
3 
+   It is really easy for online docs to meander over time as people
4 
+   attempt to add the small bit of additional information they think
5 
+   people need, into an existing information architecture. In order to
6 
+   prevent that we need to be a bit strict as to what's on this front
7 
+   page.
8 
+
9 
+   This should *only* be the quick start narrative. Which should end
10 
+   with 2 sections: what you can do with devstack once it's set up,
11 
+   and how to go beyond this setup. Both should be a set of quick
12 
+   links to other documents to let people explore from there.
13 
+
14 
+==========
15 
+ DevStack
16 
+==========
3 17
4 18 
 .. image:: assets/images/logo-blue.png
5 19
6 20 
 DevStack is a series of extensible scripts used to quickly bring up a
7 
-complete OpenStack environment.  It is used interactively as a
8 
-development environment and as the basis for much of the OpenStack
9 
-project's functional testing.
21 
+complete OpenStack environment based on the latest versions of
22 
+everything from git master.  It is used interactively as a development
23 
+environment and as the basis for much of the OpenStack project's
24 
+functional testing.
10 25
11 26 
 The source is available at
12 27 
 `<https://git.openstack.org/cgit/openstack-dev/devstack>`__.
13 28
14 
-.. toctree::
15 
-   :glob:
16 
-   :maxdepth: 1
29 
+.. warning::
17 30
18 
-   overview
19 
-   configuration
20 
-   plugins
21 
-   plugin-registry
22 
-   faq
23 
-   hacking
31 
+   DevStack will make substantial changes to your system during
32 
+   installation. Only run DevStack on servers or virtual machines that
33 
+   are dedicated to this purpose.
24 34
25 35 
 Quick Start
26 
-
27 
-#. Select a Linux Distribution
28 
-
29 
-   Only Ubuntu 14.04 (Trusty), Fedora 22 (or Fedora 23) and CentOS/RHEL
30 
-   7 are documented here. OpenStack also runs and is packaged on other
31 
-   flavors of Linux such as OpenSUSE and Debian.
32 
-
33 
-#. Install Selected OS
34 
-
35 
-   In order to correctly install all the dependencies, we assume a
36 
-   specific minimal version of the supported distributions to make it as
37 
-   easy as possible. We recommend using a minimal install of Ubuntu or
38 
-   Fedora server in a VM if this is your first time.
39 
-
40 
-#. Download DevStack
41 
-
42 
-   ::
43 
-
44 
-       git clone https://git.openstack.org/openstack-dev/devstack
45 
-
46 
-   The ``devstack`` repo contains a script that installs OpenStack and
47 
-   templates for configuration files
48 
-
49 
-#. Configure
36 
+===========
50 37
51 
-   We recommend at least a :ref:`minimal-configuration` be set up.
52 
-
53 
-#. Add Stack User
54 
-
55 
-   Devstack should be run as a non-root user with sudo enabled
56 
-   (standard logins to cloud images such as "ubuntu" or "cloud-user"
57 
-   are usually fine).
58 
-
59 
-   You can quickly create a separate `stack` user to run DevStack with
60 
-
61 
-   ::
62 
-
63 
-       devstack/tools/create-stack-user.sh; su stack
64 
-
65 
-#. Start the install, this will take a few minutes.
66 
-
67 
-   ::
38 
+Install Linux
39 
+-------------
68 40
69 
-       cd devstack; ./stack.sh
41 
+Start with a clean and minimal install of a Linux system. Devstack
42 
+attempts to support Ubuntu 14.04/16.04, Fedora 23/24, CentOS/RHEL 7,
43 
+as well as Debian and OpenSUSE.
70 44
71 
-Guides
72 
-======
45 
+If you do not have a preference, Ubuntu 16.04 is the most tested, and
46 
+will probably go the smoothest.
73 47
74 
-Walk through various setups used by stackers
48 
+Download DevStack
49 
+-----------------
75 50
76 
-.. toctree::
77 
-   :glob:
78 
-   :maxdepth: 1
51 
+::
79 52
80 
-   guides/single-vm
81 
-   guides/single-machine
82 
-   guides/lxc
83 
-   guides/multinode-lab
84 
-   guides/neutron
85 
-   guides/devstack-with-nested-kvm
86 
-   guides/nova
87 
-   guides/devstack-with-lbaas-v2
53 
+   git clone https://git.openstack.org/openstack-dev/devstack
88 54
89 
-All-In-One Single VM
55 
+The ``devstack`` repo contains a script that installs OpenStack and
56 
+templates for configuration files
90 57
91 
-Run :doc:`OpenStack in a VM <guides/single-vm>`. The VMs launched in your cloud will be slow as
92 
-they are running in QEMU (emulation), but it is useful if you don't have
93 
-spare hardware laying around. :doc:`[Read] <guides/single-vm>`
58 
+Create a local.conf
59 
+-------------------
94 60
95 
-All-In-One Single Machine
61 
+Create a ``local.conf`` file with 4 passwords preset
96 62
97 
-Run :doc:`OpenStack on dedicated hardware <guides/single-machine>`  This can include a
98 
-server-class machine or a laptop at home.
99 
-:doc:`[Read] <guides/single-machine>`
63 
+::
100 64
101 
-All-In-One LXC Container
65 
+   [[local|localrc]]
66 
+   ADMIN_PASSWORD=secret
67 
+   DATABASE_PASSWORD=$ADMIN_PASSWORD
68 
+   RABBIT_PASSWORD=$ADMIN_PASSWORD
69 
+   SERVICE_PASSWORD=$ADMIN_PASSWORD
102 70
103 
-Run :doc:`OpenStack in a LXC container <guides/lxc>`. Beneficial for intermediate
104 
-and advanced users. The VMs launched in this cloud will be fully accelerated but
105 
-not all OpenStack features are supported. :doc:`[Read] <guides/lxc>`
71 
+This is the minimum required config to get started with DevStack.
106 72
107 
-Multi-Node Lab
73 
+Add Stack User
108 74 
 --------------
109 75
110 
-Setup a :doc:`multi-node cluster <guides/multinode-lab>` with dedicated VLANs for VMs & Management.
111 
-:doc:`[Read] <guides/multinode-lab>`
76 
+Devstack should be run as a non-root user with sudo enabled
77 
+(standard logins to cloud images such as "ubuntu" or "cloud-user"
78 
+are usually fine).
112 79
113 
-DevStack with Neutron Networking
80 
+You can quickly create a separate `stack` user to run DevStack with
114 81
115 
-Building a DevStack cluster with :doc:`Neutron Networking <guides/neutron>`.
116 
-This guide is meant for building lab environments with a dedicated
117 
-control node and multiple compute nodes.
82 
+::
118 83
119 
-DevStack with KVM-based Nested Virtualization
84 
+   devstack/tools/create-stack-user.sh; su stack
120 85
121 
-Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization
122 
-<guides/devstack-with-nested-kvm>`. With this setup, Nova instances
123 
-will be more performant than with plain QEMU emulation.
86 
+Start the install
87 
+-----------------
124 88
125 
-Nova and devstack
89 
+::
126 90
127 
-Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
91 
+   cd devstack; ./stack.sh
128 92
129 
-DevStack Documentation
130 
-======================
93 
+This will take a 15 - 20 minutes, largely depending on the speed of
94 
+your internet connection. Many git trees and packages will be
95 
+installed during this process.
131 96
132 
-Overview
97 
+Profit!
98 
+-------
133 99
134 
-:doc:`An overview of DevStack goals and priorities <overview>`
100 
+You now have a working DevStack! Congrats!
135 101
136 
-Configuration
102 
+Your devstack will have installed ``keystone``, ``glance``, ``nova``,
103 
+``cinder``, ``neutron``, and ``horizon``. Floating IPs will be
104 
+available, guests have access to the external world.
137 105
138 
-:doc:`Configuring and customizing the stack <configuration>`
106 
+You can access horizon to experience the web interface to
107 
+OpenStack, and manage vms, networks, volumes, and images from
108 
+there.
139 109
140 
-Plugins
110 
+You can ``source openrc`` in your shell, and then use the
111 
+``openstack`` command line tool to manage your devstack.
141 112
142 
-:doc:`Extending DevStack with new features <plugins>`
113 
+You can ``cd /opt/stack/tempest`` and run tempest tests that have
114 
+been configured to work with your devstack.
143 115
144 
-FAQ
116 
+Going further
117 
+-------------
145 118
146 
-:doc:`The DevStack FAQ <faq>`
119 
+Learn more about our :doc:`configuration system <configuration>` to
120 
+customize devstack for your needs.
147 121
148 
-Contributing
122 
+Read :doc:`guides <guides>` for specific setups people have (note:
123 
+guides are point in time contributions, and may not always be kept
124 
+up to date to the latest devstack).
149 125
150 
-:doc:`Pitching in to make DevStack a better place <hacking>`
126 
+Enable :doc:`devstack plugins <plugins>` to support additional
127 
+services, features, and configuration not present in base devstack.
151 128
129 
+Get :doc:`the big picture <overview>` of what we are trying to do
130 
+with devstack, and help us by :doc:`contributing to the project
131 
+<hacking>`.
doc/source/site-map.rst
History View file @ cea7ec8
152 132 
new file mode 100644
... ... 
@@ -0,0 +1,21 @@
0 
+:orphan:
1 
+
2 
+.. the TOC on the front page actually makes the document a lot more
3 
+   confusing. This lets us bury a toc which we can link in when
4 
+   appropriate.
5 
+
6 
+==========
7 
+ Site Map
8 
+==========
9 
+
10 
+.. toctree::
11 
+   :glob:
12 
+   :maxdepth: 3
13 
+
14 
+   overview
15 
+   configuration
16 
+   plugins
17 
+   plugin-registry
18 
+   faq
19 
+   hacking
20 
+   guides