diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/platform/installation.rst | 224 |
1 files changed, 99 insertions, 125 deletions
diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst index cd9388f7a..fc56543a7 100644 --- a/docs/platform/installation.rst +++ b/docs/platform/installation.rst @@ -1,8 +1,9 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +************ Installation ------------- +************ .. contents:: :depth: 3 @@ -12,14 +13,22 @@ Various tools, including healthcheck, logs, and Swagger can be used to ensure pr ONAP Policy Framework: Standalone Quick Start ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This procedure explains how build the ONAP Policy Framework and get it running in Docker as a standalone system. -This procedure assumes that: +This article explains how to build the ONAP Policy Framework and get it running in Docker as a standalone system. +This article 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* +* 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) -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. +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. + +Cloning the ONAP repositories +----------------------------- + +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. + +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. .. code-block:: bash @@ -27,17 +36,15 @@ The procedure documented here has been verified to work on a MacBook laptop runn :linenos: #!/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 \ @@ -47,7 +54,7 @@ The procedure documented here has been verified to work on a MacBook laptop runn policy/gui \ policy/pap \ policy/pdp" - + ## ## Help screen and exit condition (i.e. too few arguments) ## @@ -64,7 +71,7 @@ The procedure documented here has been verified to work on a MacBook laptop runn echo "" exit 255; } - + ## ## read command line ## @@ -81,15 +88,15 @@ The procedure documented here has been verified to work on a MacBook laptop runn 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 @@ -98,39 +105,38 @@ The procedure documented here has been verified to work on a MacBook laptop runn 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 + mkdir "$clone_dir/$repoDir" + if [ $? != 0 ] + then + echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"' + exit 4 + fi 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 @@ -143,76 +149,25 @@ Execution of the script above results in the following directory hierarchy in yo * ~/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 + .. code-block:: bash + + rm -fr ~/.m2/repository/org/onap + rm -fr ~/.m2/repository/org/openecomp + rm -fr ~/.m2/repisotory/com/att -**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*. +**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*. .. code-block:: xml :caption: Typical pom.xml to build the ONAP Policy Framework :linenos: - <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* - -.. code-block:: xml - :caption: Typical pom.xml to build the ONAP Policy Framework Policy Modules - :linenos: - - <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"> - + <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> @@ -223,7 +178,7 @@ Building ONAP <organization> <name>ONAP</name> </organization> - + <modules> <module>common</module> <module>engine</module> @@ -237,75 +192,94 @@ Building ONAP </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 +**Step 3**. You can now build the ONAP framework * On *Ubuntu*, just build the Policy Framework tests and all - - cd ~/git/onap - - mvn clean install + .. code-block:: bash + + cd ~/git/onap + mvn clean install * 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 + .. code-block:: bash + + 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*. +------------------------------------------------ +The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README.md*. + + +**Step 1.** Build the policy engine docker image: + + .. code-block:: bash + + cd ~/git/onap/policy/engine/packages/docker/target + docker build -t onap/policy-pe policy-pe + -**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. +**Step 2.** Build the Drools PDP docker image: - * cd ~/git/onap/policy/docker - * mvn prepare-package + .. code-block:: bash -**Step 2**. Copy the files under *policy-pe* to *target/policy-pe*. + cd ~/git/onap/policy/drools-pdp/packages/docker/target + docker build -t onap/policy-drools policy-drools - * cp policy-pe/* target/policy-pe -**Step 3**. Copy the files under *policy-drools* to *target/policy-drools*. +**Step 3.** Build the Policy Nexus docker image: - * cp policy-drools/* target/policy-drools + .. code-block:: bash -**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*. + cd ~/git/onap/policy/docker + docker build -t onap/policy-nexus policy-nexus - * 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 +SSS + +**Step 1.** Make the file config/drools/drools-tweaks.sh executable. + + .. code-block:: bash + + 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. + + .. code-block:: bash + + export MTU=9126 + + +**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: - * chmod +x config/drools/drools-tweaks.sh + .. code-block:: bash -**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*. + export PRELOAD_POLICIES=false -**Step 3**. Set the environment variable *MTU* to be a suitable MTU size for the application. - * export MTU=9126 +**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. -**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. + .. code-block:: bash - * docker-compose up + docker-compose up Installation Complete -^^^^^^^^^^^^^^^^^^^^^ +--------------------- **You now have a full standalone ONAP Policy framework up and running!** |