docs/development/development.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5
   6 Policy Platform Development
   7 ---------------------------
   8
   9 .. contents::
  10     :depth: 2
  11
  12
  13 This article explains how to build the ONAP Policy Framework for development purposes. To start, the developer should consult the latest ONAP Wiki to familiarize themselves with developer best practices and how-tos to setup their environment, see `https://wiki.onap.org/display/DW/Developer+Best+Practices`.
  14
  15
  16 This article 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 * 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)
  22
  23 The procedure documented in this article has been verified to work on a MacBook laptop running macOS Yosemite Version 10.10,5, Sierra Version 10.12.6, a HP Z600 desktop running Ubuntu 16.04.3 LTS, and an Unbuntu 16.04 VM.
  24
  25 Cloning All The Policy Repositories
  26 -----------------------------------
  27
  28 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 all the ONAP Policy Framework repositories.
  29
  30 ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the ONAP ECOMP SDK *ecompsdkos* module, and the A&AI Schema module.
  31
  32
  33 .. code-block:: bash
  34    :caption: Typical ONAP Policy Framework Clone Script
  35    :linenos:
  36
  37     #!/usr/bin/env bash
  38
  39     ## script name for output
  40     MOD_SCRIPT_NAME=`basename $0`
  41
  42     ## the ONAP clone directory, defaults to "onap"
  43     clone_dir="onap"
  44
  45     ## the ONAP repos to clone
  46     onap_repos="\
  47     policy/parent \
  48     policy/common \
  49     policy/models \
  50     policy/docker \
  51     policy/api \
  52     policy/pap \
  53     policy/apex-pdp \
  54     policy/drools-pdp \
  55     policy/drools-applications \
  56     policy/xacml-pdp \
  57     policy/engine \
  58     policy/distribution"
  59
  60     ##
  61     ## Help screen and exit condition (i.e. too few arguments)
  62     ##
  63     Help()
  64     {
  65         echo ""
  66         echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories"
  67         echo ""
  68         echo "       Usage:  $MOD_SCRIPT_NAME [-options]"
  69         echo ""
  70         echo "       Options"
  71         echo "         -d          - the ONAP clone directory, defaults to '.'"
  72         echo "         -h          - this help screen"
  73         echo ""
  74         exit 255;
  75     }
  76
  77     ##
  78     ## read command line
  79     ##
  80     while [ $# -gt 0 ]
  81     do
  82         case $1 in
  83             #-d ONAP clone directory
  84             -d)
  85                 shift
  86                 if [ -z "$1" ]; then
  87                     echo "$MOD_SCRIPT_NAME: no clone directory"
  88                     exit 1
  89                 fi
  90                 clone_dir=$1
  91                 shift
  92             ;;
  93
  94             #-h prints help and exists
  95             -h)
  96                 Help;exit 0;;
  97
  98             *)    echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;;
  99         esac
 100     done
 101
 102     if [ -f "$clone_dir" ]; then
 103         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file"
 104         exit 2
 105     fi
 106     if [ -d "$clone_dir" ]; then
 107         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory"
 108         exit 2
 109     fi
 110
 111     mkdir $clone_dir
 112     if [ $? != 0 ]
 113     then
 114         echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"'
 115         exit 3
 116     fi
 117
 118     for repo in $onap_repos
 119     do
 120         repoDir=`dirname "$repo"`
 121         repoName=`basename "$repo"`
 122
 123         if [ ! -z $dirName ]
 124         then
 125             mkdir "$clone_dir/$repoDir"
 126             if [ $? != 0 ]
 127             then
 128                 echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"'
 129                 exit 4
 130             fi
 131         fi
 132
 133         git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo
 134     done
 135
 136     echo ONAP has been cloned into '"'$clone_dir'"'
 137
 138
 139 Execution of the script above results in the following directory hierarchy in your *~/git* directory:
 140
 141     *  ~/git/onap
 142     *  ~/git/onap/policy
 143     *  ~/git/onap/policy/parent
 144     *  ~/git/onap/policy/common
 145     *  ~/git/onap/policy/models
 146     *  ~/git/onap/policy/api
 147     *  ~/git/onap/policy/pap
 148     *  ~/git/onap/policy/docker
 149     *  ~/git/onap/policy/drools-applications
 150     *  ~/git/onap/policy/drools-pdp
 151     *  ~/git/onap/policy/engine
 152     *  ~/git/onap/policy/apex-pdp
 153     *  ~/git/onap/policy/xacml-pdp
 154     *  ~/git/onap/policy/distribution
 155
 156
 157 Building ONAP Policy Framework Components
 158 -----------------------------------------
 159
 160 **Step 1:** Optionally, for a completely clean build, remove the ONAP built modules from your local repository.
 161
 162     .. code-block:: bash
 163
 164         rm -fr ~/.m2/repository/org/onap
 165
 166
 167 **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*.
 168
 169 .. code-block:: xml
 170    :caption: Typical pom.xml to build the ONAP Policy Framework
 171    :linenos:
 172
 173     <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">
 174         <modelVersion>4.0.0</modelVersion>
 175         <groupId>org.onap</groupId>
 176         <artifactId>onap-policy</artifactId>
 177         <version>1.0.0-SNAPSHOT</version>
 178         <packaging>pom</packaging>
 179         <name>${project.artifactId}</name>
 180         <inceptionYear>2017</inceptionYear>
 181         <organization>
 182             <name>ONAP</name>
 183         </organization>
 184
 185         <modules>
 186             <module>parent</module>
 187             <module>common</module>
 188             <module>models</module>
 189             <module>api</module>
 190             <module>pap</module>
 191             <module>apex-pdp</module>
 192             <module>xacml-pdp</module>
 193             <module>drools-pdp</module>
 194             <module>drools-applications</module>
 195             <!-- The engine repo is being deprecated,
 196             and can be ommitted if not working with
 197             legacy api and components. -->
 198             <module>engine</module>
 199             <module>distribution</module>
 200         </modules>
 201     </project>
 202
 203 Policy Architecture/API Transition
 204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 205
 206 In Dublin, a new Policy Architecture was introduced. The legacy architecture runs in parallel with the new architecture. It will be deprecated after Frankfurt release.
 207
 208 If the developer is only interested in working with the new architecture components, the engine sub-module can be ommitted.
 209
 210
 211 **Step 3:** You can now build the Policy framework
 212
 213     .. code-block:: bash
 214
 215        cd ~/git/onap
 216        mvn clean install
 217
 218
 219
 220 Building the ONAP Policy Framework Docker Images
 221 ------------------------------------------------
 222 The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README.md*.
 223
 224 **Step 1:** Build the Policy API Docker image
 225
 226     .. code-block:: bash
 227
 228          cd ~/git/onap/policy/api/packages
 229          mvn clean install -P docker
 230
 231 **Step 2:** Build the Policy PAP Docker image
 232
 233     .. code-block:: bash
 234
 235          cd ~/git/onap/policy/pap/packages
 236          mvn clean install -P docker
 237
 238 **Step 3:** Build the Drools PDP docker image.
 239
 240 This image is a standalone vanilla Drools engine, which does not contain any pre-built drools rules or applications.
 241
 242     .. code-block:: bash
 243
 244         cd ~/git/onap/policy/drools-pdp/
 245         ./docker_verify.sh
 246
 247 **Step 4:** Build the Drools Application Control Loop image.
 248
 249 This image has the drools use case application and the supporting software built together with the Drools PDP engine. It is recommended to use this image if you are first working with ONAP Policy and wish to test or learn how the use cases work.
 250
 251     .. code-block:: bash
 252
 253         cd ~/git/onap/policy/drools-applications
 254         chmod 755 controlloop/build/docker-cl
 255         controlloop/build/docker-cl --verify
 256
 257 **Step 5:** Build the Apex PDP docker image:
 258
 259    .. code-block:: bash
 260
 261             cd ~/git/onap/policy/apex-pdp/packages/apex-pdp-docker/target
 262             docker build -t onap/policy-apex-pdp policy-apex-pdp
 263
 264 **Step 5:** Build the XACML PDP docker image:
 265
 266    .. code-block:: bash
 267
 268             cd ~/git/onap/policy/xacml-pdp/packages
 269             mvn clean install -P docker
 270
 271 **Step 7:** Build the policy engine docker image (If working with the legacy Policy Architecture/API):
 272
 273     .. code-block:: bash
 274
 275         cd ~/git/onap/policy/engine/
 276         ./docker_verify.sh
 277
 278 **Step 8:** Build the Policy SDC Distribution docker image:
 279
 280    .. code-block:: bash
 281
 282             cd ~/git/onap/policy/distribution/packages
 283             mvn clean install -Pdocker
 284
 285
 286 Starting the ONAP Policy Framework Docker Images
 287 ------------------------------------------------
 288
 289 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. This file is located in the policy/docker repository.
 290
 291 **Step 1:** Set the environment variable *MTU* to be a suitable MTU size for the application.
 292
 293     .. code-block:: bash
 294
 295         export MTU=9126
 296
 297
 298 **Step 2:** 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:
 299
 300     .. code-block:: bash
 301
 302         export PRELOAD_POLICIES=false
 303
 304
 305 **Step 3:** 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.
 306
 307     .. code-block:: bash
 308
 309         docker-compose up -d
 310
 311
 312 **You now have a full standalone ONAP Policy framework up and running!**
 313
 314
 315
 316
 317
 318 End of Document
 319