docs: cleanup install docs
This does a few things to the home page and all-in-one single
machine install guide:
* Uses code blocks for formatting
* Adds the customary "$" to the console blocks in the
all-in-one single machine install guide
* Instructs to use "sudo su stack" and adds a note about
"sudo visudo" in the all-in-one single machine doc
* Creates a symbolic link to the sample local.conf and links to
it from the install guide (note that local.conf might be old
by now)
* Fixes the .gitignore file to only ignore local.conf in the root
of the repository, otherwise it would ignore local.conf everywhere
including the samples and doc/source/assets directories.
Change-Id: I50ae7bd32c4c1caa2ac8551fc54b31dd2dfae568
diff --git a/doc/source/assets/local.conf b/doc/source/assets/local.conf
new file mode 120000
index 0000000..cfc2a4e
--- /dev/null
+++ b/doc/source/assets/local.conf
@@ -0,0 +1 @@
+../../../samples/local.conf
\ No newline at end of file
diff --git a/doc/source/guides/single-machine.rst b/doc/source/guides/single-machine.rst
index 515ea9a..168172c 100644
--- a/doc/source/guides/single-machine.rst
+++ b/doc/source/guides/single-machine.rst
@@ -45,31 +45,37 @@
install you can skip this step and just give the user sudo privileges
below)
-::
+.. code-block:: console
- useradd -s /bin/bash -d /opt/stack -m stack
+ $ sudo useradd -s /bin/bash -d /opt/stack -m stack
Since this user will be making many changes to your system, it will need
to have sudo privileges:
-::
+.. code-block:: console
- apt-get install sudo -y || yum install -y sudo
- echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+ $ apt-get install sudo -y || yum install -y sudo
+ $ echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+.. note:: On some systems you may need to use ``sudo visudo``.
From here on you should use the user you created. **Logout** and
-**login** as that user.
+**login** as that user:
+
+.. code-block:: console
+
+ $ sudo su stack && cd ~
Download DevStack
-----------------
We'll grab the latest version of DevStack via https:
-::
+.. code-block:: console
- sudo apt-get install git -y || sudo yum install -y git
- git clone https://git.openstack.org/openstack-dev/devstack
- cd devstack
+ $ sudo apt-get install git -y || sudo yum install -y git
+ $ git clone https://git.openstack.org/openstack-dev/devstack
+ $ cd devstack
Run DevStack
------------
@@ -97,7 +103,7 @@
``local.conf`` should look something like this:
-::
+.. code-block:: ini
[[local|localrc]]
FLOATING_RANGE=192.168.1.224/27
@@ -109,11 +115,14 @@
RABBIT_PASSWORD=flopsymopsy
SERVICE_PASSWORD=iheartksl
+.. note:: There is a sample :download:`local.conf </assets/local.conf>` file
+ under the *samples* directory in the devstack repository.
+
Run DevStack:
-::
+.. code-block:: console
- ./stack.sh
+ $ ./stack.sh
A seemingly endless stream of activity ensues. When complete you will
see a summary of ``stack.sh``'s work, including the relevant URLs,
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fcf1e82..6c42a5b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -55,14 +55,14 @@
You can quickly create a separate `stack` user to run DevStack with
-::
+.. code-block:: console
$ sudo useradd -s /bin/bash -d /opt/stack -m stack
Since this user will be making many changes to your system, it should
have sudo privileges:
-::
+.. code-block:: console
$ echo "stack ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/stack
$ sudo su - stack
@@ -70,7 +70,7 @@
Download DevStack
-----------------
-::
+.. code-block:: console
$ git clone https://git.openstack.org/openstack-dev/devstack
$ cd devstack
@@ -83,7 +83,8 @@
Create a ``local.conf`` file with 4 passwords preset at the root of the
devstack git repo.
-::
+
+.. code-block:: ini
[[local|localrc]]
ADMIN_PASSWORD=secret
@@ -93,12 +94,15 @@
This is the minimum required config to get started with DevStack.
+.. note:: There is a sample :download:`local.conf </assets/local.conf>` file
+ under the *samples* directory in the devstack repository.
+
Start the install
-----------------
-::
+.. code-block:: console
- ./stack.sh
+ $ ./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