From 584979ce2eeb0c2e590a996657e601bfd5543eee Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Thu, 13 Dec 2018 08:22:12 -0500 Subject: [PATCH] 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 --- .gitignore | 2 +- doc/source/assets/local.conf | 1 + doc/source/guides/single-machine.rst | 35 +++++++++++++++++----------- doc/source/index.rst | 16 ++++++++----- 4 files changed, 34 insertions(+), 20 deletions(-) create mode 120000 doc/source/assets/local.conf diff --git a/.gitignore b/.gitignore index e5e1f6aba0..956e13e21c 100644 --- a/.gitignore +++ b/.gitignore @@ -28,7 +28,7 @@ files/get-pip.py* files/ir-deploy* files/ironic-inspector* files/etcd* -local.conf +^local.conf local.sh localrc proto diff --git a/doc/source/assets/local.conf b/doc/source/assets/local.conf new file mode 120000 index 0000000000..cfc2a4e9d8 --- /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 515ea9a9ee..168172c630 100644 --- a/doc/source/guides/single-machine.rst +++ b/doc/source/guides/single-machine.rst @@ -45,31 +45,37 @@ We need to add a user to install DevStack. (if you created a user during 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 @@ do the following: ``local.conf`` should look something like this: -:: +.. code-block:: ini [[local|localrc]] FLOATING_RANGE=192.168.1.224/27 @@ -109,11 +115,14 @@ do the following: RABBIT_PASSWORD=flopsymopsy SERVICE_PASSWORD=iheartksl +.. note:: There is a sample :download:`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 fcf1e82d34..6c42a5b4e9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -55,14 +55,14 @@ are usually fine). 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 @@ have sudo privileges: Download DevStack ----------------- -:: +.. code-block:: console $ git clone https://git.openstack.org/openstack-dev/devstack $ cd devstack @@ -83,7 +83,8 @@ Create a local.conf 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 @@ devstack git repo. This is the minimum required config to get started with DevStack. +.. note:: There is a sample :download:`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