docs/platform/installation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 ************
   5 Installation
   6 ************
   7
   8 .. contents::
   9     :depth: 3
  10
  11 The installation of ONAP Policy is **automated** by design and can be done via Docker as a standalone system.
  12 Various tools, including healthcheck, logs, and Swagger can be used to ensure proper operation.
  13
  14 ONAP Policy Framework: Standalone Quick Start
  15 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  16 This article explains how to build the ONAP Policy Framework and get it running in Docker as a standalone system.
  17 This article assumes that:
  18
  19 * You are using a *\*nix* operating system such as linux or macOS.
  20 * You are using a directory called *git* off your home directory *(~/git)* for your git repositories
  21 * Your local maven repository is in the location *~/.m2/repository*
  22 * You have added settings to access the ONAP Nexus to your M2 configuration, see `Maven Settings Example <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_ (bottom of the linked page)
  23
  24 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.
  25
  26 Cloning the ONAP repositories
  27 -----------------------------
  28
  29 Run a script such as the script below to clone the required modules from the `ONAP git repository <https://gerrit.onap.org/r/#/admin/projects/?filter=policy>`_. This script clones the ONAP policy code and also clones some modules that ONAP Policy is dependent on.
  30
  31 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.
  32
  33
  34 .. code-block:: bash
  35    :caption: Typical ONAP Policy Framework Clone Script
  36    :linenos:
  37
  38     #!/usr/bin/env bash
  39
  40     ## script name for output
  41     MOD_SCRIPT_NAME=`basename $0`
  42
  43     ## the ONAP clone directory, defaults to "onap"
  44     clone_dir="onap"
  45
  46     ## the ONAP repos to clone
  47     onap_repos="\
  48     policy/api \
  49     policy/common \
  50     policy/docker \
  51     policy/drools-applications \
  52     policy/drools-pdp \
  53     policy/engine \
  54     policy/gui \
  55     policy/pap \
  56     policy/pdp"
  57
  58     ##
  59     ## Help screen and exit condition (i.e. too few arguments)
  60     ##
  61     Help()
  62     {
  63         echo ""
  64         echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories"
  65         echo ""
  66         echo "       Usage:  $MOD_SCRIPT_NAME [-options]"
  67         echo ""
  68         echo "       Options"
  69         echo "         -d          - the ONAP clone directory, defaults to '.'"
  70         echo "         -h          - this help screen"
  71         echo ""
  72         exit 255;
  73     }
  74
  75     ##
  76     ## read command line
  77     ##
  78     while [ $# -gt 0 ]
  79     do
  80         case $1 in
  81             #-d ONAP clone directory
  82             -d)
  83                 shift
  84                 if [ -z "$1" ]; then
  85                     echo "$MOD_SCRIPT_NAME: no clone directory"
  86                     exit 1
  87                 fi
  88                 clone_dir=$1
  89                 shift
  90             ;;
  91
  92             #-h prints help and exists
  93             -h)
  94                 Help;exit 0;;
  95
  96             *)    echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;;
  97         esac
  98     done
  99
 100     if [ -f "$clone_dir" ]; then
 101         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file"
 102         exit 2
 103     fi
 104     if [ -d "$clone_dir" ]; then
 105         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory"
 106         exit 2
 107     fi
 108
 109     mkdir $clone_dir
 110     if [ $? != 0 ]
 111     then
 112         echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"'
 113         exit 3
 114     fi
 115
 116     for repo in $onap_repos
 117     do
 118         repoDir=`dirname "$repo"`
 119         repoName=`basename "$repo"`
 120
 121         if [ ! -z $dirName ]
 122         then
 123             mkdir "$clone_dir/$repoDir"
 124             if [ $? != 0 ]
 125             then
 126                 echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"'
 127                 exit 4
 128             fi
 129         fi
 130
 131         git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo
 132     done
 133
 134     echo ONAP has been cloned into '"'$clone_dir'"'
 135
 136
 137 Execution of the script above results in the following directory hierarchy in your *~/git* directory:
 138
 139     *  ~/git/onap
 140     *  ~/git/onap/policy
 141     *  ~/git/onap/policy/api
 142     *  ~/git/onap/policy/common
 143     *  ~/git/onap/policy/docker
 144     *  ~/git/onap/policy/drools-applications
 145     *  ~/git/onap/policy/drools-pdp
 146     *  ~/git/onap/policy/engine
 147     *  ~/git/onap/policy/gui
 148     *  ~/git/onap/policy/pap
 149     *  ~/git/onap/policy/pdp
 150
 151
 152 Building ONAP
 153 -------------
 154
 155 **Step 1.** Optionally, for a completely clean build, remove the ONAP built modules from your local repository.
 156
 157         .. code-block:: bash
 158
 159             rm -fr ~/.m2/repository/org/onap
 160             rm -fr ~/.m2/repository/org/openecomp
 161             rm -fr ~/.m2/repisotory/com/att
 162
 163
 164 **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*.
 165
 166 .. code-block:: xml
 167    :caption: Typical pom.xml to build the ONAP Policy Framework
 168    :linenos:
 169
 170     <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">
 171         <modelVersion>4.0.0</modelVersion>
 172         <groupId>org.onap</groupId>
 173         <artifactId>onap-policy</artifactId>
 174         <version>1.0.0-SNAPSHOT</version>
 175         <packaging>pom</packaging>
 176         <name>${project.artifactId}</name>
 177         <inceptionYear>2017</inceptionYear>
 178         <organization>
 179             <name>ONAP</name>
 180         </organization>
 181
 182         <modules>
 183             <module>common</module>
 184             <module>engine</module>
 185             <module>pdp</module>
 186             <module>pap</module>
 187             <module>drools-pdp</module>
 188             <module>drools-applications</module>
 189             <module>api</module>
 190             <module>gui</module>
 191             <module>docker</module>
 192         </modules>
 193     </project>
 194
 195
 196 **Step 3**. You can now build the ONAP framework
 197
 198    *  On *Ubuntu*, just build the Policy Framework tests and all
 199
 200                 .. code-block:: bash
 201
 202                     cd ~/git/onap
 203                     mvn clean install
 204
 205    *  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.
 206
 207                 .. code-block:: bash
 208
 209                     cd ~/git/onap
 210                     mvn clean install -DskipTests
 211                     mvn install
 212
 213
 214 Building the ONAP Policy Framework Docker Images
 215 ------------------------------------------------
 216 The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README.md*.
 217
 218
 219 **Step 1.** Build the policy engine docker image:
 220
 221                 .. code-block:: bash
 222
 223                     cd ~/git/onap/policy/engine/packages/docker/target
 224                     docker build -t onap/policy-pe policy-pe
 225
 226
 227 **Step 2.** Build the Drools PDP docker image:
 228
 229                 .. code-block:: bash
 230
 231                     cd ~/git/onap/policy/drools-pdp/packages/docker/target
 232                     docker build -t onap/policy-drools policy-drools
 233
 234
 235 **Step 3.** Build the Policy Nexus docker image:
 236
 237                 .. code-block:: bash
 238
 239                     cd ~/git/onap/policy/docker
 240                     docker build -t onap/policy-nexus policy-nexus
 241
 242
 243 Starting the ONAP Policy Framework Docker Images
 244 ------------------------------------------------
 245
 246 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.
 247
 248 **Step 1.** Make the file config/drools/drools-tweaks.sh executable.
 249
 250                 .. code-block:: bash
 251
 252                     chmod +x config/drools/drools-tweaks.sh
 253
 254
 255 **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*.
 256
 257
 258 **Step 3.** Set the environment variable *MTU* to be a suitable MTU size for the application.
 259
 260                 .. code-block:: bash
 261
 262                     export MTU=9126
 263
 264
 265 **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:
 266
 267                 .. code-block:: bash
 268
 269                     export PRELOAD_POLICIES=false
 270
 271
 272 **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.
 273
 274                 .. code-block:: bash
 275
 276                     docker-compose up
 277
 278
 279 Installation Complete
 280 ---------------------
 281
 282 **You now have a full standalone ONAP Policy framework up and running!**
 283
 284
 285 .. _Standalone Quick Start : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Standalone+Quick+Start
 286
 287
 288
 289 End of Document
 290