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