diff options
| -rw-r--r-- | docs/platform/installation.rst | 297 |
1 files changed, 295 insertions, 2 deletions
diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst index 4df8cd1cd..5c7d863dc 100644 --- a/docs/platform/installation.rst +++ b/docs/platform/installation.rst @@ -3,12 +3,305 @@ Installation ------------ -The installation of ONAP Policy is **automated** by design. -It can be done via Docker as a standalone system (see `Standalone Quick Start`_) or via the ONAP system installation. +.. contents:: + :depth: 3 +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. +ONAP Policy Framework: Standalone Quick Start +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This proceedure explains how build the ONAP Policy Framework and get it running in Docker as a standalone system. +This proceedure 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* + +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. + + +**Typical ONAP Policy Framework Clone Script** + +.. code-block:: none + + #!/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="\ + oparent \ + ecompsdkos \ + 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/ecompsdkos + * ~/git/onap/oparent + * ~/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. + + * rm -fr ~/.m2/repository/org/onap + * rm -fr ~/.m2/repository/org/openecomp + +**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*. + +**Typical pom.xml to build the ONAP Policy Framework** + +.. code-block:: none + + <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"> + <modelVersion>4.0.0</modelVersion> + <groupId>org.onap</groupId> + <artifactId>onap-policy_standalone</artifactId> + <version>1.0.0-SNAPSHOT</version> + <packaging>pom</packaging> + <name>${project.artifactId}</name> + <inceptionYear>2017</inceptionYear> + <organization> + <name>ONAP</name> + </organization> + + <profiles> + <profile> + <id>policy-dependencies</id> + <activation> + <property> + <name>policyDeps</name> + </property> + </activation> + <modules> + <module>oparent</module> + <module>ecompsdkos/ecomp-sdk</module> + </modules> + </profile> + <profile> + <id>policy</id> + <activation> + <activeByDefault>true</activeByDefault> + </activation> + <modules> + <module>oparent</module> + <module>ecompsdkos/ecomp-sdk</module> + <module>policy</module> + </modules> + </profile> + </profiles> + </project> + + + +**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* + +**Typical pom.xml to build the ONAP Policy Framework Policy Modules** + +.. code-block:: none + + <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"> + <modelVersion>4.0.0</modelVersion> + <groupId>org.onap</groupId> + <artifactId>onap-policy</artifactId> + <version>1.0.0-SNAPSHOT</version> + <packaging>pom</packaging> + <name>${project.artifactId}</name> + <inceptionYear>2017</inceptionYear> + <organization> + <name>ONAP</name> + </organization> + + <modules> + <module>common</module> + <module>engine</module> + <module>pdp</module> + <module>pap</module> + <module>drools-pdp</module> + <module>drools-applications</module> + <module>api</module> + <module>gui</module> + <module>docker</module> + </modules> + </project> + +**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*. + +**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. + + * cd ~/git/onap + * mvn clean install -DpolicyDeps + +**Step 6**. You can now build the ONAP framework + +a. On *Ubuntu*, just build the Policy Framework tests and all + + * cd ~/git/onap + * mvn clean install + +b. 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. + + * cd ~/git/onap + * mvn clean install -DskipTests + * mvn install + + +Building the ONAP Policy Framework Docker Images +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README*. + +**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. + + * cd ~/git/onap/policy/docker + * mvn prepare-package + +**Step 2**. Copy the files under *policy-pe* to *target/policy-pe*. + + * cp policy-pe/* target/policy-pe + +**Step 3**. Copy the files under *policy-drools* to *target/policy-drools*. + + * cp policy-drools/* target/policy-drools + +**Step 4**. Run the *docker build* command on the following directories in the order below. Note that on some systems you may have to run the *docker* command as root or using *sudo*. + + * docker build -t onap/policy/policy-os policy-os + * docker build -t onap/policy/policy-db policy-db + * docker build -t onap/policy/policy-nexus policy-nexus + * docker build -t onap/policy/policy-base policy-base + * docker build -t onap/policy/policy-pe target/policy-pe + * docker build -t onap/policy/policy-drools target/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 + + * 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. + + * export MTU=9126 + +**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. + + * docker-compose up + + +Installation Complete +^^^^^^^^^^^^^^^^^^^^^ + +**You now have a full standalone ONAP Policy framework up and running!** + + .. _Standalone Quick Start : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Standalone+Quick+Start |