Merge "Rearrange existing documentation to fit the new standard layout"

10 files changed, 902 insertions, 0 deletions

diff --git a/doc/source/admin/image-building.rst b/doc/source/admin/image-building.rst
new file mode 100644
index 000000000..4eb9d8d7e
--- /dev/null
+++ b/doc/source/admin/image-building.rst
@@ -0,0 +1,453 @@
+.. _image-building:
+
+=========================
+Building Container Images
+=========================
+
+The ``kolla-build`` command is responsible for building Docker images.
+
+.. note::
+
+  When developing Kolla it can be useful to build images using files located in
+  a local copy of Kolla. Use the ``tools/build.py`` script instead of
+  ``kolla-build`` command in all below instructions.
+
+Generating kolla-build.conf
+===========================
+
+Install tox and generate the build configuration. The build configuration is
+designed to hold advanced customizations when building containers.
+
+Create kolla-build.conf using the following steps.
+
+::
+
+    pip install tox
+    tox -e genconfig
+
+The location of the generated configuration file is
+``etc/kolla/kolla-build.conf``, it can also be copied to ``/etc/kolla``. The
+default location is one of ``/etc/kolla/kolla-build.conf`` or
+``etc/kolla/kolla-build.conf``.
+
+Guide
+=====
+
+In general, images are built like this::
+
+    kolla-build
+
+By default, the above command would build all images based on CentOS image.
+
+The operator can change the base distro with the ``-b`` option::
+
+    kolla-build -b ubuntu
+
+There are following distros available for building images:
+
+- centos
+- oraclelinux
+- rhel
+- ubuntu
+
+.. warning::
+
+   Fedora images are deprecated since Newton and will be removed
+   in the future.
+
+It is possible to build only a subset of images by specifying them on the
+command line::
+
+    kolla-build keystone
+
+In this case, the build script builds all images whose name contains the
+``keystone`` string along with their dependencies.
+
+Multiple names may be specified on the command line::
+
+    kolla-build keystone nova
+
+The set of images built can be defined as a profile in the ``profiles`` section
+of ``kolla-build.conf``. Later, profile can be specified by ``--profile`` CLI
+argument or ``profile`` option in ``kolla-build.conf``. Kolla provides some
+pre-defined profiles:
+
+- ``infra`` infrastructure-related images
+- ``main`` core OpenStack images
+- ``aux`` auxiliary images such as trove, magnum, ironic
+- ``default`` minimal set of images for a working deploy
+
+For example, due to Magnum requires Heat, following profile can be add to
+``profiles`` section in ``kolla-build.conf`` ::
+
+    magnum = magnum,heat
+
+These images can be built using command line ::
+
+    kolla-build --profile magnum
+
+Or put following line to ``DEFAULT`` section in ``kolla-build.conf`` ::
+
+    profile = magnum
+
+
+``kolla-build`` uses ``kolla`` as default Docker namespace. This is
+controlled with the ``-n`` command line option. To push images to a Dockerhub
+repository named ``mykollarepo``::
+
+    kolla-build -n mykollarepo --push
+
+To push images to a `local registry
+<https://docs.openstack.org/kolla-ansible/latest/multinode.html#deploy-a-registry>`_,
+use ``--registry`` flag::
+
+    kolla-build --registry 172.22.2.81:5000 --push
+
+The build configuration can be customized using a config file, the default
+location being one of ``/etc/kolla/kolla-build.conf`` or
+``etc/kolla/kolla-build.conf``. This file can be generated using the following
+command::
+
+    tox -e genconfig
+
+Build OpenStack from source
+===========================
+
+When building images, there are two methods of the OpenStack install. One is
+``binary``. Another is ``source``. The ``binary`` means that OpenStack will be
+installed from apt/yum. And the ``source`` means that OpenStack will be
+installed from source code. The default method of the OpenStack install is
+``binary``. It can be changed to ``source`` using the ``-t`` option::
+
+    kolla-build -t source
+
+The locations of OpenStack source code are written in
+``etc/kolla/kolla-build.conf``.
+Now the source type supports ``url``, ``git``, and ``local``. The location of
+the ``local`` source type can point to either a directory containing the source
+code or to a tarball of the source. The ``local`` source type permits to make
+the best use of the Docker cache.
+
+``etc/kolla/kolla-build.conf`` looks like::
+
+    [glance-base]
+    type = url
+    location = http://tarballs.openstack.org/glance/glance-master.tar.gz
+
+    [keystone-base]
+    type = git
+    location = https://git.openstack.org/openstack/keystone
+    reference = stable/mitaka
+
+    [heat-base]
+    type = local
+    location = /home/kolla/src/heat
+
+    [ironic-base]
+    type = local
+    location = /tmp/ironic.tar.gz
+
+To build RHEL containers, it is necessary to include registration with RHN
+of the container runtime operating system.  To obtain a RHN
+username/password/pool id, contact Red Hat.  Use a template's header block
+overrides file, add the following::
+
+    RUN subscription-manager register --user=<user-name> \
+    --password=<password> && subscription-manager attach --pool <pool-id>
+
+Dockerfile Customisation
+========================
+
+As of the Newton release, the ``kolla-build`` tool provides a Jinja2 based
+mechanism which allows operators to customise the Dockerfiles used to generate
+Kolla images.
+
+This offers a lot of flexibility on how images are built, e.g. installing extra
+packages as part of the build, tweaking settings, installing plugins, and
+numerous other capabilities. Some of these examples are described in more
+detail below.
+
+Generic Customisation
+---------------------
+
+Anywhere the line ``{% block ... %}`` appears may be modified. The Kolla
+community have added blocks throughout the Dockerfiles where we think they will
+be useful, however, operators are free to submit more if the ones provided are
+inadequate.
+
+The following is an example of how an operator would modify the setup steps
+within the Horizon Dockerfile.
+
+First, create a file to contain the customisations, e.g.
+``template-overrides.j2``. In this place the following::
+
+    {% extends parent_template %}
+
+    # Horizon
+    {% block horizon_redhat_binary_setup %}
+    RUN useradd --user-group myuser
+    {% endblock %}
+
+Then rebuild the horizon image, passing the ``--template-override`` argument::
+
+    kolla-build --template-override template-overrides.j2 horizon
+
+.. note::
+
+    The above example will replace all contents from the original block. Hence
+    in many cases one may want to copy the original contents of the block before
+    making changes.
+
+    More specific functionality such as removing/appending entries is available
+    for packages, described in the next section.
+
+Package Customisation
+---------------------
+
+Packages installed as part of a container build can be overridden, appended to,
+and deleted. Taking the Horizon example, the following packages are installed
+as part of a binary install type build:
+
+* ``openstack-dashboard``
+* ``httpd``
+* ``mod_wsgi``
+* ``mod_ssl``
+* ``gettext``
+
+To add a package to this list, say, ``iproute``, first create a file, e.g.
+``template-overrides.j2``. In this place the following::
+
+    {% extends parent_template %}
+
+    # Horizon
+    {% set horizon_packages_append = ['iproute'] %}
+
+Then rebuild the horizon image, passing the ``--template-override`` argument::
+
+    kolla-build --template-override template-overrides.j2 horizon
+
+Alternatively ``template_override`` can be set in ``kolla-build.conf``.
+
+The ``append`` suffix in the above example carries special significance. It
+indicates the operation taken on the package list. The following is a complete
+list of operations available:
+
+override
+    Replace the default packages with a custom list.
+
+append
+    Add a package to the default list.
+
+remove
+    Remove a package from the default list.
+
+Using a different base image
+----------------------------
+
+Base-image can be specified by argument ``--base-image``. For example::
+
+    kolla-build --base-image registry.access.redhat.com/rhel7/rhel --base rhel
+
+
+Plugin Functionality
+--------------------
+
+The Dockerfile customisation mechanism is also useful for adding/installing
+plugins to services. An example of this is Neutron's third party L2 drivers_.
+
+The bottom of each Dockerfile contains two blocks, ``image_name_footer``, and
+``footer``. The ``image_name_footer`` is intended for image specific
+modifications, while the ``footer`` can be used to apply a common set of
+modifications to every Dockerfile.
+
+For example, to add the ``networking-cisco`` plugin to the ``neutron_server``
+image, one may want to add the following to the ``template-override`` file::
+
+    {% extends parent_template %}
+
+    {% block neutron_server_footer %}
+    RUN git clone https://git.openstack.org/openstack/networking-cisco \
+        && pip --no-cache-dir install networking-cisco
+    {% endblock %}
+
+Astute readers may notice there is one problem with this however. Assuming
+nothing else in the Dockerfile changes for a period of time, the above ``RUN``
+statement will be cached by Docker, meaning new commits added to the Git
+repository may be missed on subsequent builds. To solve this the Kolla build
+tool also supports cloning additional repositories at build time, which will be
+automatically made available to the build, within an archive named
+``plugins-archive``.
+
+.. note::
+
+    The following is available for source build types only.
+
+To use this, add a section to ``/etc/kolla/kolla-build.conf`` in the following
+format::
+
+    [<image>-plugin-<plugin-name>]
+
+Where ``<image>`` is the image that the plugin should be installed into, and
+``<plugin-name>`` is the chosen plugin identifier.
+
+Continuing with the above example, add the following to
+``/etc/kolla/kolla-build.conf``::
+
+    [neutron-server-plugin-networking-cisco]
+    type = git
+    location = https://git.openstack.org/openstack/networking-cisco
+    reference = master
+
+The build will clone the repository, resulting in the following archive
+structure::
+
+    plugins-archive.tar
+    |__ plugins
+        |__networking-cisco
+
+The template now becomes::
+
+    {% block neutron_server_footer %}
+    ADD plugins-archive /
+    pip --no-cache-dir install /plugins/*
+    {% endblock %}
+
+Many of the Dockerfiles already copy the ``plugins-archive`` to the image and
+install available plugins at build time.
+
+Additions Functionality
+-----------------------
+
+The Dockerfile customisation mechanism is also useful for adding/installing
+additions into images. An example of this is adding your jenkins job build
+metadata (say formatted into a jenkins.json file) into the image.
+
+Similarly to the plugins mechanism, the Kolla build tool also supports cloning
+additional repositories at build time, which will be automatically made
+available to the build, within an archive named ``additions-archive``. The main
+difference between ``plugins-archive`` and ``additions-archive`` is that
+``plugins-archive`` is copied to the relevant images and processed to install
+available plugins while ``additions-archive`` processing is left to the Kolla
+user.
+
+.. note::
+
+    The following is available for source build types only.
+
+To use this, add a section to ``/etc/kolla/kolla-build.conf`` in the following
+format::
+
+    [<image>-additions-<additions-name>]
+
+Where ``<image>`` is the image that the plugin should be installed into, and
+``<additions-name>`` is the chosen additions identifier.
+
+Continuing with the above example, add the following to
+``/etc/kolla/kolla-build.conf``::
+
+    [neutron-server-additions-jenkins]
+    type = local
+    location = /path/to/your/jenkins/data
+
+The build will copy the directory, resulting in the following archive
+structure::
+
+    additions-archive.tar
+    |__ additions
+        |__jenkins
+
+Alternatively, it is also possible to create an ``additions-archive.tar`` file
+yourself without passing by ``/etc/kolla/kolla-build.conf`` in order to use the
+feature for binary build type.
+
+The template now becomes::
+
+    {% block neutron_server_footer %}
+    ADD additions-archive /
+    RUN cp /additions/jenkins/jenkins.json /jenkins.json
+    {% endblock %}
+
+Custom Repos
+------------
+
+Red Hat
+-------
+The build method allows the operator to build containers from custom repos.
+The repos are accepted as a list of comma separated values and can be in the
+form of ``.repo``, ``.rpm``, or a url. See examples below.
+
+Update ``rpm_setup_config`` in ``/etc/kolla/kolla-build.conf``::
+
+    rpm_setup_config = https://trunk.rdoproject.org/centos7/currrent/delorean.repo,https://trunk.rdoproject.org/centos7/delorean-deps.repo
+
+If specifying a ``.repo`` file, each ``.repo`` file will need to exist in the
+same directory as the base Dockerfile (``kolla/docker/base``)::
+
+    rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo
+
+Ubuntu
+------
+For Debian based images, additional apt sources may be added to the build as
+follows::
+
+    apt_sources_list = custom.list
+
+Known issues
+============
+
+#. Can't build base image because Docker fails to install systemd or httpd.
+
+   There are some issues between Docker and AUFS. The simple workaround to
+   avoid the issue is that add ``-s devicemapper`` or ``-s btrfs`` to
+   ``DOCKER_OPTS``. Get more information about `the issue from the Docker bug
+   tracker <https://github.com/docker/docker/issues/6980>`_ and `how to
+   configure Docker with BTRFS back end <https://docs.docker.com/engine/userguide/storagedriver/btrfs-driver/#prerequisites>`_.
+
+#. Mirrors are unreliable.
+
+   Some of the mirrors Kolla uses can be unreliable. As a result occasionally
+   some containers fail to build. To rectify build problems, the build tool
+   will automatically attempt three retries of a build operation if the first
+   one fails. The retry count is modified with the ``--retries`` option.
+
+Kolla-ansible with Local Registry
+---------------------------------
+
+To make kolla-ansible pull images from a local registry, set
+``"docker_registry"`` to ``"172.22.2.81:5000"`` in
+``"/etc/kolla/globals.yml"``. Make sure Docker is allowed to pull images from
+insecure registry. See
+`Docker Insecure Registry
+<https://docs.openstack.org/kolla-ansible/latest/multinode.html#deploy-a-registry>`_.
+
+Building behind a proxy
+-----------------------
+
+We can insert http_proxy settings into the images to
+fetch packages during build, and then unset them at the end to avoid having
+them carry through to the environment of the final images. Note however, it's
+not possible to drop the info completely using this method; it will still be
+visible in the layers of the image.
+
+To set the proxy settings, we can add this to the template's header block::
+
+    ENV http_proxy=https://evil.corp.proxy:80
+    ENV https_proxy=https://evil.corp.proxy:80
+
+To unset the proxy settings, we can add this to the template's footer block::
+
+    ENV http_proxy=""
+    ENV https_proxy=""
+
+Besides this configuration options, the script will automatically read these
+environment variables. If the host system proxy parameters match the ones
+going to be used, no other input parameters will be needed. These are the
+variables that will be picked up from the user env::
+
+    HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, FTP_PROXY,
+    ftp_proxy, NO_PROXY, no_proxy
+
+Also these variables could be overwritten using ``--build-args``, which have
+precedence.
+
+.. _drivers: https://wiki.openstack.org/wiki/Neutron#Plugins
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
new file mode 100644
index 000000000..4724b3bb2
--- /dev/null
+++ b/doc/source/admin/index.rst
@@ -0,0 +1,18 @@
+===================
+Administrator Guide
+===================
+
+Building Container Images
+-------------------------
+
+If you are a system administrator running Kolla, this section contains
+information that should help you understand how to build container image
+or build some images using ``--template-override``.
+
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   image-building
+   template-override/*
diff --git a/doc/source/admin/template-override/opendaylight-source.rst b/doc/source/admin/template-override/opendaylight-source.rst
new file mode 100644
index 000000000..61a3415ba
--- /dev/null
+++ b/doc/source/admin/template-override/opendaylight-source.rst
@@ -0,0 +1,27 @@
+==================
+OpenDaylight Build
+==================
+
+The `opendaylight-template-overrides.j2` template override shows how to build
+an OpenDaylight container image with a different version than the one packaged
+with the distro.
+
+Building OpenDaylight Container Images
+======================================
+
+kolla-build.conf
+----------------
+
+Point to the desired version of OpenDaylight in `kolla-build.conf`:
+
+.. code-block:: console
+
+    [opendaylight]
+    type = url
+    location = https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/integration/distribution-karaf/0.6.0-Carbon/distribution-karaf-0.6.0-Carbon.tar.gz
+
+Build the container by executing the following command:
+
+::
+
+    kolla-build --type source --template-override contrib/template-override/opendaylight-template-overrides.j2 opendaylight
diff --git a/doc/source/admin/template-override/ovs-dpdk.rst b/doc/source/admin/template-override/ovs-dpdk.rst
new file mode 100644
index 000000000..e47cfe0ff
--- /dev/null
+++ b/doc/source/admin/template-override/ovs-dpdk.rst
@@ -0,0 +1,31 @@
+OVS-DPDK Source build
+=====================
+
+CentOS and Oracle Linux currently do not provide packages
+for ovs with dpdk.
+The Ubuntu packages do not support UIO based drivers.
+To use the uio_pci_generic driver on Ubuntu a source build is required.
+
+Building ovs with dpdk containers from source
+---------------------------------------------
+
+- Append the following to /etc/kolla/kolla-build.conf to select the version
+  of ovs and dpdk to use for your source build.
+
+kolla-build.conf
+________________
+
+[openvswitch-base-plugin-ovs]
+type = git
+location = https://github.com/openvswitch/ovs.git
+reference = v2.7.0
+
+[openvswitch-base-plugin-dpdk]
+type = git
+location = http://dpdk.org/git/dpdk
+reference = v17.02
+
+- To build the container execute the follow command::
+
+    tools/build.py --template-override \
+    contrib/template-override/ovs-dpdk.j2 dpdk
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 000000000..d4a23cab2
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'openstackdocstheme',
+    'sphinx.ext.autodoc',
+]
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'kolla'
+copyright = u'2013-present, OpenStack Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+from kolla.version import version_info as kolla_version
+# The full version, including alpha/beta/rc tags.
+release = kolla_version.version_string_with_vcs()
+# The short X.Y version.
+version = kolla_version.canonical_version_string()
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = []
+html_theme = 'openstackdocs'
+# html_static_path = ['static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+# Must set this variable to include year, month, day, hours, and minutes.
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     '%s.tex' % project,
+     u'%s Documentation' % project,
+     u'OpenStack Foundation', 'manual'),
+]
+
+# openstackdocstheme options
+repository_name = 'openstack/kolla'
+bug_project = 'kolla'
+bug_tag = ''
diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst
new file mode 100644
index 000000000..7b6ce18f4
--- /dev/null
+++ b/doc/source/contributor/CONTRIBUTING.rst
@@ -0,0 +1,88 @@
+.. _CONTRIBUTING:
+
+=================
+How To Contribute
+=================
+
+Basics
+======
+
+#. Our source code is hosted on `OpenStack Kolla Git`_. Bugs should be filed on
+   launchpad_.
+
+#. Please follow OpenStack `Gerrit Workflow`_ to contribute to Kolla.
+
+#. Note the branch you're proposing changes to. ``master`` is the current focus
+   of development. Kolla project has a strict policy of only allowing backports
+   in ``stable/branch``, unless when not applicable. A bug in a
+   ``stable/branch`` will first have to be fixed in ``master``.
+
+#. Please file a launchpad_ blueprint for any significant code change and a bug
+   for any significant bug fix.  See how to reference a bug or a blueprint in
+   the commit message here_. For simple changes, contributors may optionally
+   add the text "TrivialFix" to the commit message footer to indicate to
+   reviewers a bug is not required.
+
+.. _OpenStack Kolla Git: https://git.openstack.org/cgit/openstack/kolla/
+.. _launchpad: https://bugs.launchpad.net/kolla
+.. _here: https://wiki.openstack.org/wiki/GitCommitMessages
+
+Please use the existing sandbox repository, available at
+https://git.openstack.org/cgit/openstack-dev/sandbox, for learning, understanding
+and testing the `Gerrit Workflow`_.
+
+.. _Gerrit Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Adding a new service
+====================
+
+Kolla aims to both containerise and deploy all services within the OpenStack
+"big tent". This is a constantly moving target as the ecosystem grows, so these
+guidelines aim to help make adding a new service to Kolla a smooth experience.
+
+The image
+---------
+Kolla follows Docker best practices
+(https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)
+when designing and implementing services where at all possible.
+
+We use ``jinja2`` templating syntax to help manage the volume and complexity
+that comes with maintaining multiple Dockerfiles for multiple different base
+operating systems.
+
+Images should be created under the ``docker`` directory. OpenStack services
+should inherit from the provided ``openstack-base`` image, while supporting and
+infrastructure services (e.g. mongodb) should inherit from ``base``.
+
+Services consisting of only one service should be placed in an image named the
+same as that service, e.g. ``horizon``. Services that consist of multiple
+processes generally use a base image and child images, e.g. ``glance-base``,
+``glance-api``, and ``glance-registry``.
+
+Jinja2 'blocks' are employed throughout the Dockerfile's to help operators
+customise various stages of the build (refer to
+https://docs.openstack.org/kolla/latest/image-building.html#dockerfile-customisation)
+
+Some of these blocks are free form however, there are a subset that should be
+common to every Dockerfile. The overall structure for a multi container service
+is as follows::
+
+    FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}
+    LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
+
+    {% block << service >>_header %}{% endblock %}
+
+    {% import "macros.j2" as macros with context %}
+
+    << binary specific steps >>
+
+    << source specific steps >>
+
+    << common steps >>
+
+    {% block << service >>_footer %}{% endblock %}
+    {% block footer %}{% endblock %}
+
+.. NOTE::
+  The generic footer block ``{% block footer %}{% endblock %}`` should not be
+  included in base images (e.g. glance-base).
diff --git a/doc/source/contributor/bug-triage.rst b/doc/source/contributor/bug-triage.rst
new file mode 100644
index 000000000..d5d24ca15
--- /dev/null
+++ b/doc/source/contributor/bug-triage.rst
@@ -0,0 +1,8 @@
+==========
+Bug triage
+==========
+
+The triage of Kolla bugs follows the OpenStack-wide process documented
+on `BugTriage <https://wiki.openstack.org/wiki/BugTriage>`_ in the wiki.
+Please reference `Bugs <https://wiki.openstack.org/wiki/Bugs>`_ in the
+wiki for further details.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
new file mode 100644
index 000000000..13430a481
--- /dev/null
+++ b/doc/source/contributor/index.rst
@@ -0,0 +1,17 @@
+============
+Development
+============
+
+Contributing
+------------
+
+This guide is to tell someone who would like to contribute to
+Kolla project. Following this guide to propose your first patch for Kolla.
+And we are welcome everyone to join our project!
+
+.. toctree::
+   :maxdepth: 2
+
+   CONTRIBUTING.rst
+   running-tests
+   bug-triage
diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst
new file mode 100644
index 000000000..e60671c9f
--- /dev/null
+++ b/doc/source/contributor/running-tests.rst
@@ -0,0 +1,116 @@
+.. _running-tests:
+
+=============
+Running tests
+=============
+
+Kolla contains a suite of tests in the
+``tests`` and ``kolla/tests`` directories.
+
+Any proposed code change in gerrit is automatically rejected by the OpenStack
+Jenkins server [#f1]_ if the change causes test failures.
+
+It is recommended for developers to run the test suite before submitting patch
+for review. This allows to catch errors as early as possible.
+
+Preferred way to run the tests
+------------------------------
+
+The preferred way to run the unit tests is using ``tox``. It executes tests in
+isolated environment, by creating separate virtualenv and installing
+dependencies from the ``requirements.txt`` and ``test-requirements.txt`` files,
+so the only package you install is ``tox`` itself:
+
+.. code-block:: console
+
+    $ pip install tox
+
+See `the unit testing section of the Testing wiki page`_ for more information.
+Following are some simple examples.
+
+To run the Python 2.7 tests:
+
+.. code-block:: console
+
+    $ tox -e py27
+
+To run the style tests:
+
+.. code-block:: console
+
+    $ tox -e pep8
+
+To run multiple tests separate items by commas:
+
+.. code-block:: console
+
+    $ tox -e py27,py35,pep8
+
+.. _the unit testing section of the Testing wiki page: https://wiki.openstack.org/wiki/Testing#Unit_Tests
+
+Running a subset of tests
+-------------------------
+
+Instead of running all tests, you can specify an individual directory, file,
+class or method that contains test code, i.e. filter full names of tests by a
+string.
+
+To run the tests located only in the ``kolla/tests``
+directory use:
+
+.. code-block:: console
+
+    $ tox -e py27 kolla.tests
+
+To run the tests of a specific file say ``kolla/tests/test_set_config.py``:
+
+.. code-block:: console
+
+    $ tox -e py27 test_set_config
+
+To run the tests in the ``ConfigFileTest`` class in
+the ``kolla/tests/test_set_config.py`` file:
+
+.. code-block:: console
+
+    $ tox -e py27 test_set_config.ConfigFileTest
+
+To run the ``ConfigFileTest.test_delete_path_not_exists`` test method in
+the ``kolla/tests/test_set_config.py`` file:
+
+.. code-block:: console
+
+    $ tox -e py27 test_set_config.ConfigFileTest.test_delete_path_not_exists
+
+
+Coverage Report Generation
+--------------------------
+
+In order to get coverage report for Kolla, run the below command.
+
+.. code-block:: console
+
+    $ tox -e cover
+
+Debugging unit tests
+--------------------
+
+In order to break into the debugger from a unit test we need to insert
+a breaking point to the code:
+
+.. code-block:: python
+
+  import pdb; pdb.set_trace()
+
+Then run ``tox`` with the debug environment as one of the following::
+
+  tox -e debug
+  tox -e debug test_file_name.TestClass.test_name
+
+For more information see the `oslotest documentation
+<https://docs.openstack.org/oslotest/latest/user/features.html#debugging-with-oslo-debug-helper>`_.
+
+
+.. rubric:: Footnotes
+
+.. [#f1] See https://docs.openstack.org/infra/system-config/jjb.html
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 000000000..b5635defd
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,54 @@
+..
+      Copyright 2014-2015 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+=================================
+Welcome to Kolla's documentation!
+=================================
+
+Kolla's mission is to provide production-ready containers and deployment tools
+for operating OpenStack clouds.
+
+This documentation is for the Kolla container images. The following subprojects
+are available to help deploy Kolla:
+
+* `kolla-ansible <https://docs.openstack.org/kolla-ansible/latest/>`_
+* `kolla-kubernetes <https://docs.openstack.org/kolla-kubernetes/latest/>`_
+
+Site Notes
+==========
+
+This documentation is continually updated and may not represent the state of
+the project at any specific prior release. To access documentation for a
+previous release of kolla, append the OpenStack release name to the URL, for
+example:
+
+    https://docs.openstack.org/kolla/mitaka/
+
+Administrator Guide
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   admin/index
+
+Contributor Guide
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   contributor/index