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