9 files changed, 644 insertions, 0 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..906f249
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,40 @@
+# -*- 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
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
+
+sys.path.insert(0, ROOT)
+sys.path.insert(0, BASE_DIR)
+
+# -- 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 = [
+    'sphinx.ext.autodoc',
+    #'sphinx.ext.intersphinx'
+]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ONAP on Vagrant'
diff --git a/docs/source/features/configure_execution.rst b/docs/source/features/configure_execution.rst
new file mode 100644
index 0000000..df08605
--- /dev/null
+++ b/docs/source/features/configure_execution.rst
@@ -0,0 +1,72 @@
+=======================
+Modify execution values
+=======================
+
+In order to provide a flexible platform that adjusts to different developer
+needs, there are two mechanisms to configure the execution of this project.
+
+Settings configuration file
+---------------------------
+
+The first mechanism refers to the process to replace default configuration
+values in the settings configuration file. This file needs to be placed into
+the *./etc* folder and named *settings.yaml*. It must contain the key/pair
+configuration values that will be overriden.
+
+.. note::
+
+    There are sample files (e. g. settings.yaml.development and
+    settings.yaml.testing) placed into the *./etc* folder. Their purpose is to
+    provide a reference of different configurations.
+
+.. end
+
+Configuration values:
+
++------------------+-------------------+---------------------------------------+
+| Key              | Values            | Description                           |
++==================+===================+=======================================+
+| build_image      | "True" or "False" | Determines if the Docker image is     |
+|                  |                   | retrieved from public hub or built    |
+|                  |                   | from source code.                     |
++------------------+-------------------+---------------------------------------+
+| clone_repo       | "True" or "False" | Determines if all the source code     |
+|                  |                   | repositories of a given component are |
+|                  |                   | cloned locally.                       |
++------------------+-------------------+---------------------------------------+
+| compile_repo     | "True" or "False" | Determines if all the source code     |
+|                  |                   | repositories of a given component are |
+|                  |                   | going to be compiled.                 |
++------------------+-------------------+---------------------------------------+
+| enable_oparent   | "True" or "False" | Determines if the OParent project     |
+|                  |                   | will be used during the maven         |
+|                  |                   | compilation.                          |
++------------------+-------------------+---------------------------------------+
+| skip_get_images  | "True" or "False" | Determines if the process to build or |
+|                  |                   | retrieve docker images of a given     |
+|                  |                   | component are going to skipped.       |
++------------------+-------------------+---------------------------------------+
+| skip_install     | "True" or "False" | Determines if the process to start    |
+|                  |                   | the services of a given component     |
+|                  |                   | will be started.                      |
++------------------+-------------------+---------------------------------------+
+
+Parameters
+----------
+
+The **skip_get_images** and **skip_install** are the only two configuration
+values that can be overriden using *-g* and *-i* respectively by the run scripts
+(*./tools/run.sh* and *.\\tools\\Run.ps1*).
+
+.. note::
+
+    The script parameters take precendence of the configuration file.
+
+.. end
+
+.. code-block:: console
+
+   $ ./tools/run.sh sdc -g
+
+.. end
+
diff --git a/docs/source/features/consuming_scripts.rst b/docs/source/features/consuming_scripts.rst
new file mode 100644
index 0000000..4290c25
--- /dev/null
+++ b/docs/source/features/consuming_scripts.rst
@@ -0,0 +1,88 @@
+==============================
+Using the provisioning scripts
+==============================
+
+Vagrant is a platform that uses prebaked images called
+*vagrant boxes* to guarranty that running multiple times a
+provisioning script will result in an expected output. This
+mechanism is crucial for reducing the number of external factors
+during the creation, development and testing of provisioning scripts. 
+However, it's possible to provide an ONAP development enviroment
+without having to install Vagrant tool. This document explains how to
+consume the provisioning scripts localed in **./lib** folder to
+provision a development environment and the environment variables
+that modifies their behavior.
+
+This project was built on an Ubuntu 14.04 ("Trusty") Operating System,
+therefore it's necessary to have an user who has *sudo* permissions to
+access to a Bare Metal or Virtual Machine.
+
+The following instructions retrieve the provisioning scripts and place
+them into the */var/onap/* folder.
+
+.. code-block:: console
+
+    $ sudo apt-get install git -y
+    $ git clone https://git.onap.org/integration/devtool
+    $ cd /var/
+    $ ln -s ~/devtool/lib/ ./onap
+
+.. end
+
+Loading a provisioning script will be based on the desired ONAP
+service, for example to setup the development environment for Active
+and Available Inventory (AAI) service will be required to load the
+*/var/onap/aai* script.
+
+.. note::
+
+    The **git_src_folder** environment variable specifies the
+    source code destination folder, it's default value is */opt/onap/*
+    but it can be changed only after is loaded the provisioning
+    scripts.
+
+.. end
+
+.. code-block:: console
+
+    # source /var/onap/aai
+
+.. end
+
+Lastly, every script has defined a initialization function with
+*init_* as prefix. This function is the starting point to provision
+the chosen ONAP service. This example uses the *init_aai* function
+to provision a AAI Developement environment.
+
+.. note::
+
+    The **compile_repo** environment variable defines whether or not
+    the source code located on the repositories of the service.
+    Enabling this value can impact the provisioning time of the
+    service.
+
+.. end
+.. note::
+
+    **nexus_docker_repo**, **nexus_username** and **nexus_password**
+    environment variables specify the connectivity to a private Docker
+    Hub.
+
+.. end
+.. note::
+
+    **build_image** environment variable allows the Docker images
+    from source code.  Enabling this value can impact the
+    provisioning time of the service.
+
+.. end
+
+.. code-block:: console
+
+    # init_aai
+
+.. end
+
+As result, the source code is pulled into */opt/onap/aai/* folder and the
+AAI services are up and running with the proper connection to the
+Titan Distributed Graph Database.
diff --git a/docs/source/features/example_usage.rst b/docs/source/features/example_usage.rst
new file mode 100644
index 0000000..1aae887
--- /dev/null
+++ b/docs/source/features/example_usage.rst
@@ -0,0 +1,151 @@
+=================================================
+Example usage to bring up a developer environment
+=================================================
+
+In the example, we will bring up a single ONAP component using the Devtool ONAP
+tool.
+
+There are multiple scenarios in which this tool can be made use of by a
+developer, they usually fall in the following use cases.
+
+Use case 1: Use Devtool ONAP to just clone project related source code
+----------------------------------------------------------------------
+
+In this use case, the developer needs just the source code of the project to work on.
+
+Since the Devtool ONAP project supports building docker containers and compiling
+source files, we need to first edit the settings.yaml file to add key value pairs
+indicating we need to only clone repo and not build docker image or compile then.
+By default, Devtool ONAP clones repo, but to not run the build process and cloning
+docker images, the following are required to be added in the settings file.
+
+.. code-block:: console
+
+    skip_get_images: "True"
+
+.. end
+
+The reason this is done is because as mentioned in the
+`configure execution docs. <https://git.onap.org/integration/devtool/tree/doc/source/features/configure_execution.rst>`,
+the default values taken are:
+
+.. code-block:: console
+
+    'build_image'         => 'True',
+    'clone_repo'          => 'True',
+    'compile_repo'        => 'False',
+    'enable_oparent'      => 'True',
+    'skip_get_images'     => 'False',
+    'skip_install'        => 'True'
+
+.. end
+
+We override them and skip_get_images is given precedence over build_image.
+
+Use case 2: Use Devtool ONAP to clone project related source code and clone Docker Images
+-----------------------------------------------------------------------------------------
+
+In this use case, the developer needs to clone docker images of the project to work on.
+
+For this case, we will edit the settings.yaml file to add key value pairs indicating we
+need to clone repo and clone docker image from Nexus.
+
+.. code-block:: console
+
+    build_images: "False"
+    compile_repo: "True"
+    skip_get_images: "False"
+    skip_install: "True"
+
+.. end
+
+Use case 3: Use Devtool ONAP to clone project related source code and build Docker Images locally
+-------------------------------------------------------------------------------------------------
+
+In this use case, the developer needs to build docker images of the project to work on.
+
+For this case, we will edit the settings.yaml file to add key value pairs indicating we need to
+clone repo and build docker image locally and not fetch them from Nexus.
+
+.. code-block:: console
+
+    build_images: "True"
+    compile_repo: "True"
+    skip_get_images: "False"
+    skip_install: "True"
+
+.. end
+
+Use case 4: Use Devtool ONAP to clone project related source code and build Docker Images and start services
+------------------------------------------------------------------------------------------------------------
+
+In this use case, the developer needs to build docker images of the project he or
+she wanted to work on and start the services running inside them.
+
+For this case, we will edit the settings.yaml file to add key value pairs indicating
+we need to clone repo, compile repo, build docker image and run the image.
+
+.. code-block:: console
+
+    build_images: "True"
+    compile_repo: "True"
+    skip_get_images: "False"
+    skip_install: "False"
+
+.. end
+
+Once the required changes to the settings file is added, we can use the run.sh
+script in tools directory to setup the development environment.
+
+Example steps for setting up a development environment for VFC project.
+-----------------------------------------------------------------------
+
+In this example we will be using Devtool ONAP to get all the source code of VFC
+project and the developer can point the IDE to the cloned repo in the ./opt directory
+and start the development process.
+
+.. code-block:: console
+
+   $ ./tools/run.sh vfc
+
+.. end
+
+At the end of the setup process, all the VFC related source code will be present
+in the devtool/opt/ directory. The developer can point an IDE to this directory
+and start contributing. When the changes are done, the developer can SSH into the VM
+running VFC and tests can be executed by running Maven for Java and Tox for Python
+from the ~/opt/vfc directory.
+
+.. code-block:: console
+
+   $ vagrant ssh vfc
+   $ cd ~/opt/onap/vfc/<vfc-subrepo>
+   $ tox -e py27
+
+.. end
+
+This way the tool helps the developer to clone repos of a particular project,
+without having to manually search for repos and setup an environment.
+
+Also, if something gets messed up in the VM, the developer can tear down the VM
+and spin a fresh one without having to lose the changes made to the source code since
+the ./opt files are in sync from the host to the VM.
+
+.. code-block:: console
+
+   $ vagrant destroy vfc
+
+.. end
+
+Testing
+-------
+
+Use the run.sh script to test if the provisioning scripts run without errors.
+
+And example test to check the number of covered repositories with this tool.
+
+.. code-block:: console
+
+   $ ./tools/run.sh testing -y -c coverity_repos -s functions
+
+.. end
diff --git a/docs/source/features/features.rst b/docs/source/features/features.rst
new file mode 100644
index 0000000..9055301
--- /dev/null
+++ b/docs/source/features/features.rst
@@ -0,0 +1,16 @@
+.. _features:
+
+=================
+Advanced features
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   openstack.rst
+   consuming_scripts.rst
+   configure_execution.rst
+   example_usage.rst
+
+This chapter explains how to use Devtool ONAP tool for Advanced features
+like different providers.
diff --git a/docs/source/features/openstack.rst b/docs/source/features/openstack.rst
new file mode 100644
index 0000000..f44bc62
--- /dev/null
+++ b/docs/source/features/openstack.rst
@@ -0,0 +1,89 @@
+==================
+OpenStack Provider
+==================
+
+It's possible to use Vagrant to provision VMs on OpenStack using the
+`Vagrant OpenStack Cloud Provider <https://github.com/ggiamarchi/vagrant-openstack-provider/>`.
+The only requirement for the Cloud provider is to have an Ubuntu Cloud
+image accesible to your tenant and a Security Rule that allows to do
+SSH into the instance.
+
+Environment variables
+---------------------
+
+The usage of environment variables in OpenStack command-line clients
+is to avoid repeating some values.  These variables have *OS_* as
+prefix. This provider will use them for authentication to Keystone
+service.
+
+.. code-block:: console
+
+    export OS_AUTH_URL=http://<keystone_ip>:5000/v3
+    export OS_TENANT_NAME=<project_or_tenant_name>
+    export OS_PROJECT_NAME=<project_or_tenant_name>
+    export OS_USERNAME=<openstack_username>
+    export OS_PASSWORD=<openstack_password>
+    export OS_REGION_NAME=<openstack_region_name>
+    export OS_IDENTITY_API_VERSION=<keystone_version_number>
+    export OS_PROJECT_DOMAIN_ID=<openstack_domain_name>
+
+.. end
+
+OpenStack Vagrant provider needs additional information about the
+name of the image to be used and the networking where the instance
+will be provisioned.  That information can be passed using the
+following variables
+
+.. code-block:: console
+
+    export OS_IMAGE=<ubuntu_cloud_image_name>
+    export OS_NETWORK=<neutron_private_network>
+    export OS_FLOATING_IP_POOL=<neutron_floating_ip_pool>
+    export OS_SEC_GROUP=<onap-ssh-secgroup>
+
+.. end
+
+Tenant setup
+------------
+
+The *tools/setup_openstack.sh* script can be useful to get an idea
+of the process to setup the OpenStack environment with the necessary
+requirements. This script depends on the Environment Variables
+explained previously.
+
+----
+
+Devstack
+--------
+
+It's possible to use this plugin to provision instances on
+`Devstack <https://docs.openstack.org/devstack/latest/>`. This is
+an example of the *local.conf* file that can be used as input
+for Devstack
+
+.. path local.conf
+.. code-block:: ini
+
+    [[local|localrc]]
+    ADMIN_PASSWORD=<password>
+    DATABASE_PASSWORD=<password>
+    RABBIT_PASSWORD=<password>
+    SERVICE_PASSWORD=<password>
+    SERVICE_TOKEN=<token>
+
+    # Used to only upload the Ubuntu Cloud Image
+    DOWNLOAD_DEFAULT_IMAGES=False
+    IMAGE_URLS+="http://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img"
+
+    # (Optional) These values helps to improve the experience deploying and using Devstack
+    GIT_BASE=https://git.openstack.org
+    FORCE_CONFIG_DRIVE="True"
+    disable_service tempest
+
+.. end
+
+.. note::
+
+    There is a validation that checks if the
+    *vagrant-openstack-provider* plugin is installed raising an error
+    for those cases when it isn't.
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..af5777c
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,23 @@
+ONAP on Vagrant tool
+====================
+
+This project collects instructions to setup a development environment
+using different providers like VirtualBox, Libvirt or OpenStack.
+
+.. seealso::
+
+    You may want to read the `Bootstrap documentation`__ to get an idea of the
+    concepts. 
+
+    __ https://wiki.onap.org/display/DW/ONAP+on+Vagrant
+
+Table of contents
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   Installation Guide <install/index>
+   Known Issues <install/known_issues>
+   Advanced Features <features/features>
+
diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst
new file mode 100644
index 0000000..62f57e6
--- /dev/null
+++ b/docs/source/install/index.rst
@@ -0,0 +1,102 @@
+==================
+Installation Guide
+==================
+
+This project collects instructions related to the automatic creation
+of a development environment. However, this requires only two
+components previous to its execution.  These are an automation
+building tool (Vagrant) and a provider platform (VirtualBox, Libvirt
+and OpenStack). This section explains how to install the most common
+set of configuration(Vagrant/VirtualBox) in different Operating
+Systems.
+
+Ubuntu 14.04 ("Trusty")
+-----------------------
+
+.. code-block:: console
+
+    $ wget -q https://releases.hashicorp.com/vagrant/2.0.1/vagrant_2.0.1_x86_64.deb
+    $ sudo dpkg -i vagrant_2.0.1_x86_64.deb
+
+    $ echo "deb http://download.virtualbox.org/virtualbox/debian trusty contrib" >> /etc/apt/sources.list
+    $ wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add -
+    $ wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | sudo apt-key add -
+    $ sudo apt-get update -y
+    $ sudo apt-get install -y virtualbox-5.1 dkms
+
+    $ sudo apt install -y nfs-kernel-server
+
+.. end
+
+CentOS
+------
+
+.. code-block:: console
+
+    $ wget -q https://releases.hashicorp.com/vagrant/2.0.1/vagrant_2.0.1_x86_64.rpm
+    $ sudo yum install vagrant_2.0.1_x86_64.rpm
+
+    $ wget -q http://download.virtualbox.org/virtualbox/rpm/rhel/virtualbox.repo -P /etc/yum.repos.d
+    $ sudo yum --enablerepo=epel install dkms
+    $ wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | rpm --import -
+    $ sudo yum install -y VirtualBox-5.1
+
+    $ sudo yum install -y nfs-utils nfs-utils-lib
+
+.. end
+
+Mac OS
+------
+
+.. code-block:: console
+
+    $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+    $ brew cask install vagrant
+    $ brew cask install virtualbox
+
+.. end
+
+Windows 7+ (PowerShell v2+)
+---------------------------
+
+.. code-block:: console
+
+    PS C:\> Set-ExecutionPolicy AllSigned
+    PS C:\> iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
+    PS C:\> choco install vagrant
+    PS C:\> choco install virtualbox
+
+.. end
+
+.. note::
+
+    Some corporations use Proxy Servers to protect their assets
+    from security threats. This project uses the Proxy Environment
+    variables to connect to those servers in order to download the
+    content required during the setup. The methods to setup these
+    variables depends on the Operating system that is used.
+
+    * Linux or Mac OS
+
+    .. code-block:: console
+
+        $ export http_proxy=<proxy>
+        $ export https_proxy=<proxy>
+        $ export no_proxy=<no_proxy_urls>
+
+    .. end
+
+    * Windows
+
+    .. code-block:: console
+
+        C:\> setx http_proxy <proxy>
+        C:\> setx https_proxy <proxy>
+        C:\> setx no_proxy <no_proxy_urls>
+
+    .. end
+
+.. note::
+
+    Vagrant can be configured to use a different default provider
+    through the environment variable **VAGRANT_DEFAULT_PROVIDER**.
diff --git a/docs/source/install/known_issues.rst b/docs/source/install/known_issues.rst
new file mode 100644
index 0000000..8db55e7
--- /dev/null
+++ b/docs/source/install/known_issues.rst
@@ -0,0 +1,63 @@
+============
+Known Issues
+============
+
+Virtualbox guest additions conflict with shared directories
+-----------------------------------------------------------
+
+If the **vagrant-vbguest** plugin is installed on the host, then an
+updated version of the Virtualbox guest additions will be installed
+on the guest in the /opt directory.  Once this projects Vagrantfile
+mounts the ./opt directory on the host to the /opt directory on the
+guest during the provisioning process, the guest addtions on the
+guest are hidden and subsequent mounts of shared directories with the
+host will fail.
+
+The simplest workaround appears to be uninstalling the
+*vagrant-vbguest* plugin on the host system.  This has been observed
+to work on a Windows 10 host using virtualbox 5.1.26.
+
+Check if vagrant-vbguest plugin is installed
+
+- Linux or Mac
+
+.. code-block:: console
+
+    $ vagrant plugin list
+.. end
+
+- Windows
+
+.. code-block:: console
+
+    C:\> vagrant plugin list
+.. end
+
+Remove vagrant-vbguest plugin
+
+- Linux or Mac
+
+.. code-block:: console
+
+    $ vagrant plugin uninstall vagrant-vbguest
+.. end
+
+- Windows
+
+.. code-block:: console
+
+    C:\> vagrant plugin uninstall vagrant-vbguest
+.. end
+
+
+Network configuration in Windows
+--------------------------------
+
+Some Virtual Machines present a problem in their network configuration so to
+make sure the install will work as it should install the virtualbox from the
+cmd window with the following command:
+
+.. code-block:: console
+
+    c:\downloads\VirtualBox-5.1.20-114628-Win.exe -msiparams NETWORKTYPE=NDIS5
+.. end