add LIBS_FROM_GIT to docs
Also reformat common configuration variables to have an additional
header level which makes it easy to direct link to specific
configuration vars when directing someone.
Reformat header markup to us a more standard == = - for h1, h2, h3
Change-Id: I10bac5a93529cdfbcde0a05f9ebdbc1799d403cd
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index a4d940d..869908f 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -22,7 +22,7 @@
- allow settings in arbitrary configuration files to be changed
local.conf
-~~~~~~~~~~
+==========
The new configuration file is ``local.conf`` and resides in the root
DevStack directory like the old ``localrc`` file. It is a modified INI
@@ -96,7 +96,7 @@
whitespace around ``=`` (equals).
Minimal Configuration
-~~~~~~~~~~~~~~~~~~~~~
+=====================
While ``stack.sh`` is happy to run without a ``localrc`` section in
``local.conf``, devlife is better when there are a few minimal variables
@@ -136,9 +136,11 @@
by default.
Common Configuration Variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==============================
-Set DevStack install directory
+Installation Directory
+----------------------
+
| *Default: ``DEST=/opt/stack``*
| The DevStack install directory is set by the ``DEST`` variable.
| By setting it early in the ``localrc`` section you can reference it
@@ -150,7 +152,27 @@
DEST=/opt/stack
-stack.sh logging
+Libraries from Git
+------------------
+
+ | *Default: ``LIBS_FROM_GIT=""``*
+
+ | By default devstack installs OpenStack server components from
+ git, however it installs client libraries from released versions
+ on pypi. This is appropriate if you are working on server
+ development, but if you want to see how an unreleased version of
+ the client affects the system you can have devstack install it
+ from upstream, or from local git trees.
+ | Multiple libraries can be specified as a comma separated list.
+ |
+
+ ::
+
+ LIBS_FROM_GIT=python-keystoneclient,oslo.config
+
+Enable Logging
+--------------
+
| *Defaults: ``LOGFILE="" LOGDAYS=7 LOG_COLOR=True``*
| By default ``stack.sh`` output is only written to the console
where is runs. It can be sent to a file in addition to the console
@@ -178,7 +200,9 @@
LOG_COLOR=False
-Screen logging
+Logging the Screen Output
+-------------------------
+
| *Default: ``SCREEN_LOGDIR=""``*
| By default DevStack runs the OpenStack services using ``screen``
which is useful for watching log and debug output. However, in
@@ -196,7 +220,9 @@
*Note the use of ``DEST`` to locate the main install directory; this
is why we suggest setting it in ``local.conf``.*
-One syslog to bind them all
+Enabling Syslog
+---------------
+
| *Default: ``SYSLOG=False SYSLOG_HOST=$HOST_IP SYSLOG_PORT=516``*
| Logging all services to a single syslog can be convenient. Enable
syslogging by setting ``SYSLOG`` to ``True``. If the destination log
@@ -211,6 +237,8 @@
SYSLOG_PORT=516
A clean install every time
+--------------------------
+
| *Default: ``RECLONE=""``*
| By default ``stack.sh`` only clones the project repos if they do
not exist in ``$DEST``. ``stack.sh`` will freshen each repo on each
@@ -222,10 +250,18 @@
RECLONE=yes
- Swift
- Default: SWIFT_HASH="" SWIFT_REPLICAS=1 SWIFT_DATA_DIR=$DEST/data/swift
- Swift is now used as the back-end for the S3-like object store. When enabled Nova's objectstore (n-obj in ENABLED_SERVICES) is automatically disabled. Enable Swift by adding it services to ENABLED_SERVICES:
- enable_service s-proxy s-object s-container s-account
+Swift
+-----
+
+ | Default: SWIFT_HASH=""
+ | SWIFT_REPLICAS=1
+ | SWIFT_DATA_DIR=$DEST/data/swift
+
+ | Swift is now used as the back-end for the S3-like object store.
+ When enabled Nova's objectstore (n-obj in ENABLED_SERVICES) is
+ automatically disabled. Enable Swift by adding it services to
+ ENABLED_SERVICES: enable_service s-proxy s-object s-container
+ s-account
Setting Swift's hash value is required and you will be prompted for
it if Swift is enabled so just set it to something already:
@@ -259,6 +295,8 @@
work correctly.*
Service Catalog Backend
+-----------------------
+
| *Default: ``KEYSTONE_CATALOG_BACKEND=sql``*
| DevStack uses Keystone's ``sql`` service catalog backend. An
alternate ``template`` backend is also available. However, it does
@@ -274,6 +312,8 @@
``files/keystone_data.sh``
Cinder
+------
+
| Default:
| VOLUME_GROUP="stack-volumes" VOLUME_NAME_PREFIX="volume-" VOLUME_BACKING_FILE_SIZE=10250M
| The logical volume group used to hold the Cinder-managed volumes
@@ -289,6 +329,8 @@
VOLUME_BACKING_FILE_SIZE=10250M
Multi-host DevStack
+-------------------
+
| *Default: ``MULTI_HOST=False``*
| Running DevStack with multiple hosts requires a custom
``local.conf`` section for each host. The master is the same as a
@@ -311,6 +353,8 @@
ENABLED_SERVICES=n-vol,n-cpu,n-net,n-api
API rate limits
+---------------
+
| Default: ``API_RATE_LIMIT=True``
| Integration tests such as Tempest will likely run afoul of the
default rate limits configured for Nova. Turn off rate limiting
@@ -322,7 +366,7 @@
API_RATE_LIMIT=False
Examples
-~~~~~~~~
+========
- Eliminate a Cinder pass-through (``CINDER_PERIODIC_INTERVAL``):
diff --git a/stackrc b/stackrc
index 18e1de3..b1a9e20 100644
--- a/stackrc
+++ b/stackrc
@@ -134,6 +134,19 @@
# Another option is https://git.openstack.org
GIT_BASE=${GIT_BASE:-git://git.openstack.org}
+# Which libraries should we install from git instead of using released
+# versions on pypi?
+#
+# By default devstack is now installing libraries from pypi instead of
+# from git repositories by default. This works great if you are
+# developing server components, but if you want to develop libraries
+# and see them live in devstack you need to tell devstack it should
+# install them from git.
+#
+# ex: LIBS_FROM_GIT=python-keystoneclient,oslo.config
+#
+# Will install those 2 libraries from git, the rest from pypi.
+
##############
#
# OpenStack Server Components