Policy Installation documentation

Updates to the installation documentation
-------------------------------------------------------------

Change-Id: Ib4ac5962bccbfe2f7f3f73b822e165ae798754a5
Issue-Id: POLICY-241
Signed-off-by: Saryu Shah <ss3917@att.com>

1 files changed, 295 insertions, 2 deletions

diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst
index 4df8cd1cd..5c7d863dc 100644
--- a/docs/platform/installation.rst
+++ b/docs/platform/installation.rst
@@ -3,12 +3,305 @@
 
 Installation
 ------------
-The installation of ONAP Policy is **automated** by design.  
 
-It can be done via Docker as a standalone system (see `Standalone Quick Start`_) or via the ONAP system installation.  
+.. contents::
+    :depth: 3
 
+The installation of ONAP Policy is **automated** by design and can be done via Docker as a standalone system.  
 Various tools, including healthcheck, logs, and Swagger can be used to ensure proper operation.
 
+ONAP Policy Framework: Standalone Quick Start
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This proceedure explains how build the ONAP Policy Framework and get it running in Docker as a standalone system. 
+This proceedure assumes that:
+
+* You are using a *\*nix* operating system such as linux or macOS.
+* You are using a directory called *git* off your home directory *(~/git)* for your git repositories
+* Your local maven repository is in the location *~/.m2/repository*
+
+The procedure documented in this article has been verified to work on a MacBook laptop running macOS Sierra Version 10.12.6 and a HP Z600 desktop running Ubuntu 16.04.3 LTS.
+
+
+**Typical ONAP Policy Framework Clone Script**
+
+.. code-block:: none
+
+    #!/usr/bin/env bash
+    
+    ## script name for output
+    MOD_SCRIPT_NAME=`basename $0`
+    
+    ## the ONAP clone directory, defaults to "onap"
+    clone_dir="onap"
+    
+    ## the ONAP repos to clone
+    onap_repos="\
+    oparent \
+    ecompsdkos \
+    policy/api \
+    policy/common \
+    policy/docker \
+    policy/drools-applications \
+    policy/drools-pdp \
+    policy/engine \
+    policy/gui \
+    policy/pap \
+    policy/pdp"
+    
+    ##
+    ## Help screen and exit condition (i.e. too few arguments)
+    ##
+    Help()
+    {
+        echo ""
+        echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories"
+        echo ""
+        echo "       Usage:  $MOD_SCRIPT_NAME [-options]"
+        echo ""
+        echo "       Options"
+        echo "         -d          - the ONAP clone directory, defaults to '.'"
+        echo "         -h          - this help screen"
+        echo ""
+        exit 255;
+    }
+    
+    ##
+    ## read command line
+    ##
+    while [ $# -gt 0 ]
+    do
+        case $1 in
+            #-d ONAP clone directory
+            -d)
+                shift
+                if [ -z "$1" ]; then
+                    echo "$MOD_SCRIPT_NAME: no clone directory"
+                    exit 1
+                fi
+                clone_dir=$1
+                shift
+            ;;
+    
+            #-h prints help and exists
+            -h)
+                Help;exit 0;;
+    
+            *)    echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;;
+        esac
+    done
+    
+    if [ -f "$clone_dir" ]; then
+        echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file"
+        exit 2
+    fi
+    if [ -d "$clone_dir" ]; then
+        echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory"
+        exit 2
+    fi
+    
+    mkdir $clone_dir
+    if [ $? != 0 ]
+    then
+        echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"'
+        exit 3
+    fi
+    
+    for repo in $onap_repos
+    do
+        repoDir=`dirname "$repo"`
+        repoName=`basename "$repo"`
+    
+        if [ ! -z $dirName ]
+        then
+        mkdir "$clone_dir/$repoDir"
+        if [ $? != 0 ]
+        then
+            echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"'
+            exit 4
+        fi
+        fi
+    
+        git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo
+    done
+    
+    echo ONAP has been cloned into '"'$clone_dir'"'
+
+Execution of the script above results in the following directory hierarchy in your *~/git* directory:
+
+        * ~/git/onap
+        * ~/git/onap/ecompsdkos
+        * ~/git/onap/oparent
+        * ~/git/onap/policy
+        * ~/git/onap/policy/api
+        * ~/git/onap/policy/common
+        * ~/git/onap/policy/docker
+        * ~/git/onap/policy/drools-applications
+        * ~/git/onap/policy/drools-pdp
+        * ~/git/onap/policy/engine
+        * ~/git/onap/policy/gui
+        * ~/git/onap/policy/pap
+        * ~/git/onap/policy/pdp    
+
+
+
+Building ONAP
+^^^^^^^^^^^^^
+
+**Step 1.** Optionally, for a completely clean build, remove the ONAP built modules from your local repository.
+
+    * rm -fr ~/.m2/repository/org/onap
+    * rm -fr ~/.m2/repository/org/openecomp
+
+**Step 2**. A pom such as the one below can be used to build all the ONAP policy modules and their dependencies. Create the *pom.xml* file in the directory *~/git/onap*.
+
+**Typical pom.xml to build the ONAP Policy Framework**
+
+.. code-block:: none
+
+    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+      <modelVersion>4.0.0</modelVersion>
+      <groupId>org.onap</groupId>
+      <artifactId>onap-policy_standalone</artifactId>
+      <version>1.0.0-SNAPSHOT</version>
+      <packaging>pom</packaging>
+      <name>${project.artifactId}</name>
+      <inceptionYear>2017</inceptionYear>
+      <organization>
+        <name>ONAP</name>
+      </organization>
+    
+      <profiles>
+        <profile>
+          <id>policy-dependencies</id>
+          <activation>
+        <property>
+              <name>policyDeps</name>
+        </property>
+          </activation>
+          <modules>
+        <module>oparent</module>
+        <module>ecompsdkos/ecomp-sdk</module>
+          </modules>
+        </profile>
+        <profile>
+          <id>policy</id>
+          <activation>
+        <activeByDefault>true</activeByDefault>
+          </activation>
+          <modules>
+        <module>oparent</module>
+        <module>ecompsdkos/ecomp-sdk</module>
+        <module>policy</module>
+          </modules>
+        </profile>
+      </profiles>
+    </project>
+    
+
+
+**Step 3**.  A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml* file in the directory *~/git/onap/policy*
+
+**Typical pom.xml to build the ONAP Policy Framework Policy Modules**
+
+.. code-block:: none
+
+    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+        <modelVersion>4.0.0</modelVersion>
+        <groupId>org.onap</groupId>
+        <artifactId>onap-policy</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <packaging>pom</packaging>
+        <name>${project.artifactId}</name>
+        <inceptionYear>2017</inceptionYear>
+        <organization>
+            <name>ONAP</name>
+        </organization>
+    
+        <modules>
+            <module>common</module>
+            <module>engine</module>
+            <module>pdp</module>
+            <module>pap</module>
+            <module>drools-pdp</module>
+            <module>drools-applications</module>
+            <module>api</module>
+            <module>gui</module>
+            <module>docker</module>
+        </modules>
+    </project>
+
+**Step 4**. The build cannot currently find the * org.onap.oparent:version-check-maven-plugin* plugin so, for now, comment that plugin out in the POMs *policy/drools-pdp/pom.xml* and *policy/drools-applications/pom.xml*.
+
+**Step 5**. Build the ONAP dependencies that are required for the ONAP policy framework and which must be built first to be available to the ONAP Policy Framework proper.
+
+    * cd ~/git/onap
+    * mvn clean install -DpolicyDeps 
+
+**Step 6**. You can now build the ONAP framework
+
+a.	On *Ubuntu*, just build the Policy Framework tests and all
+
+        * cd ~/git/onap
+        * mvn clean install 
+
+b.    On *macOS*, you must build build the ONAP framework with tests turned off first. Then rebuild the framework with tests turned on and all tests will pass. Note: The reason for this behaviour will be explored later. 
+
+        * cd ~/git/onap
+        * mvn clean install -DskipTests
+        * mvn install
+ 
+
+Building the ONAP Policy Framework Docker Images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README*.
+
+**Step 1.** Prepare the Docker packages. This will pull the installation zip files needed for building the policy-pe and policy-drools Docker images into the target directory. It will not actually build the docker images; the additional steps below must be followed to actually build the Docker images.
+
+    * cd ~/git/onap/policy/docker
+    * mvn prepare-package
+
+**Step 2**. Copy the files under *policy-pe* to *target/policy-pe*.
+
+    * cp policy-pe/* target/policy-pe
+
+**Step 3**. Copy the files under *policy-drools* to *target/policy-drools*.
+
+    * cp policy-drools/* target/policy-drools
+
+**Step 4**. Run the *docker build* command on the following directories in the order below. Note that on some systems you may have to run the *docker* command as root or using *sudo*.
+
+    * docker build -t onap/policy/policy-os     policy-os
+    * docker build -t onap/policy/policy-db     policy-db
+    * docker build -t onap/policy/policy-nexus  policy-nexus
+    * docker build -t onap/policy/policy-base   policy-base
+    * docker build -t onap/policy/policy-pe     target/policy-pe
+    * docker build -t onap/policy/policy-drools target/policy-drools
+
+Starting the ONAP Policy Framework Docker Images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In order to run the containers, you can use *docker-compose*. This uses the *docker-compose.yml* yaml file to bring up the ONAP Policy Framework.
+
+**Step 1.** Make the file *config/drools/drools-tweaks.sh* executable
+
+    * chmod +x config/drools/drools-tweaks.sh
+
+**Step 2**. Set the IP address to use to be an IP address of a suitable interface on your machine. Save the IP address into the file *config/pe/ip_addr.txt*.
+
+**Step 3**. Set the environment variable *MTU* to be a suitable MTU size for the application.
+
+    * export MTU=9126
+
+**Step 4**. Run the system using *docker-compose*. Note that on some systems you may have to run the *docker-compose* command as root or using *sudo*. Note that this command takes a number of minutes to execute on a laptop or desktop computer.
+
+    * docker-compose up
+
+
+Installation Complete
+^^^^^^^^^^^^^^^^^^^^^
+
+**You now have a full standalone ONAP Policy framework up and running!**
+
+
 .. _Standalone Quick Start : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Standalone+Quick+Start