X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fplatform%2Finstallation.rst;h=0f068ea8f3f50612cbfbae4cfb01f4750e7120b9;hb=b0c7e3bd5a3fa546c1f87298ca4312b728a25495;hp=4df8cd1cdb383f84b44a3a992a2b5aad705c9f88;hpb=ba1936f39aa89170d265fb685acfe0cec022698e;p=policy%2Fengine.git diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst index 4df8cd1cd..0f068ea8f 100644 --- a/docs/platform/installation.rst +++ b/docs/platform/installation.rst @@ -1,14 +1,276 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -Installation ------------- -The installation of ONAP Policy is **automated** by design. +Standalone Quick Start Installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It can be done via Docker as a standalone system (see `Standalone Quick Start`_) or via the ONAP system installation. +.. contents:: + :depth: 2 +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. +This article explains how to build the ONAP Policy Framework and get it running in Docker as a standalone system. +This article 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* +* You have added settings to access the ONAP Nexus to your M2 configuration, see `Maven Settings Example `_ (bottom of the linked page) + +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. + +Cloning the ONAP repositories +----------------------------- + +Run a script such as the script below to clone the required modules from the `ONAP git repository `_. This script clones the ONAP policy code and also clones some modules that ONAP Policy is dependent on. + +ONAP Policy requires all the *policy* modules from the ONAP repository. It also requires the ONAP Parent *oparent* module and the ONAP ECOMP SDK *ecompsdkos* module. + + +.. code-block:: bash + :caption: Typical ONAP Policy Framework Clone Script + :linenos: + + #!/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="\ + 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/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. + + .. code-block:: bash + + rm -fr ~/.m2/repository/org/onap + rm -fr ~/.m2/repository/org/openecomp + rm -fr ~/.m2/repisotory/com/att + + +**Step 2:** 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*. + +.. code-block:: xml + :caption: Typical pom.xml to build the ONAP Policy Framework + :linenos: + + + 4.0.0 + org.onap + onap-policy + 1.0.0-SNAPSHOT + pom + ${project.artifactId} + 2017 + + ONAP + + + + common + engine + pdp + pap + drools-pdp + drools-applications + api + gui + docker + + + + +**Step 3:** You can now build the ONAP framework + + .. code-block:: bash + + cd ~/git/onap + mvn clean install + + +Building the ONAP Policy Framework Docker Images +------------------------------------------------ +The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README.md*. + + +**Step 1:** Build the policy engine docker image: + + .. code-block:: bash + + cd ~/git/onap/policy/engine/packages/docker/target + docker build -t onap/policy-pe policy-pe + + +**Step 2:** Build the Drools PDP docker image: + + .. code-block:: bash + + cd ~/git/onap/policy/drools-pdp/packages/docker/target + docker build -t onap/policy-drools 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. + + .. code-block:: bash + + 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. + + .. code-block:: bash + + export MTU=9126 + + +**Step 4:** Determine if you want policies pre-loaded or not. By default, all the configuration and operational policies will be pre-loaded by the docker compose script. If you do not wish for that to happen, then export this variable: + + .. code-block:: bash + + export PRELOAD_POLICIES=false + + +**Step 5:** 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. + + .. code-block:: bash + + docker-compose up + + +**You now have a full standalone ONAP Policy framework up and running!** + + +Installation of Controllers and Policies +---------------------------------------- + +You may now install a controller and policies on the ONAP Policy Framework. Follow either of the HowTos below to install either the Amsterdam or Beijing controller and policies. + + * `Installation of Amsterdam Controller and vCPE Policy `_ + * `Installation of Beijing Controller and Policies `_ + + + .. _Standalone Quick Start : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Standalone+Quick+Start + +End of Document +