diff options
Diffstat (limited to 'docs/APEX-Install-Guide.rst')
| -rw-r--r-- | docs/APEX-Install-Guide.rst | 1418 |
1 files changed, 1418 insertions, 0 deletions
diff --git a/docs/APEX-Install-Guide.rst b/docs/APEX-Install-Guide.rst new file mode 100644 index 000000000..3ac1eb238 --- /dev/null +++ b/docs/APEX-Install-Guide.rst @@ -0,0 +1,1418 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +APEX Installation Guide +*********************** + +.. contents:: + :depth: 3 + +Requirements +^^^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + APEX is 100% written in Java and runs on any platform that + supports a JVM, e.g. Windows, Unix, Cygwin. Some APEX + applications (such as the monitoring application) come as + web archives, they do require a war-capable web server + installed. + +Installation Requirements +------------------------- + + .. container:: ulist + + - Downloaded distribution: JAVA runtime environment + (JRE, Java 8 or later, APEX is tested with the Oracle + Java) + + - Building from source: JAVA development kit (JDK, Java + 8 or later, APEX is tested with the Oracle Java) + + - A web archive capable webserver, for instance for the + monitoring application + + .. container:: ulist + + - for instance `Apache + Tomcat <https://tomcat.apache.org/>`__ + + - Sufficient rights to install APEX on the system + + - Installation tools depending on the installation + method used: + + .. container:: ulist + + - ZIP to extract from a ZIP distribution + + .. container:: ulist + + - Windows for instance + `7Zip <http://www.7-zip.org/>`__ + + - TAR and GZ to extract from that TAR.GZ + distribution + + .. container:: ulist + + - Windows for instance + `7Zip <http://www.7-zip.org/>`__ + + - RPM to install from the RPM distribution + + .. container:: ulist + + - Install: ``sudo apt-get install rpm`` + + - DPKG to install from the DEB distribution + + .. container:: ulist + + - Install: ``sudo apt-get install dpkg`` + +Feature Requirements +-------------------- + + .. container:: paragraph + + APEX supports a number of features that require extra + software being installed. + + .. container:: ulist + + - `Apache Kafka <https://kafka.apache.org/>`__ to + connect APEX to a Kafka message bus + + - `Hazelcast <https://hazelcast.com/>`__ to use + distributed hash maps for context + + - `Infinispan <http://infinispan.org/>`__ for + distributed context and persistence + + - `Docker <https://www.docker.com/>`__ to run APEX + inside a Docker container + +Build (Install from Source) Requirements +---------------------------------------- + + .. container:: paragraph + + Installation from source requires a few development tools + + .. container:: ulist + + - GIT to retrieve the source code + + - Java SDK, Java version 8 or later + + - Apache Maven 3 (the APEX build environment) + +Get the APEX Source Code +^^^^^^^^^^^^^^^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + The first APEX source code was hosted on Github in January + 2018. By the end of 2018, APEX was added as a project in the + ONAP Policy Framework, released later in the ONAP Casablanca + release. + + .. container:: paragraph + + The APEX source code is hosted in ONAP as project APEX. The + current stable version is in the master branch. Simply clone + the master branch from ONAP using HTTPS. + + .. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + git clone https://gerrit.onap.org/r/policy/apex-pdp + +Build APEX +^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + The examples in this document assume that the APEX source + repositories are cloned to: + + .. container:: ulist + + - Unix, Cygwin: ``/usr/local/src/apex-pdp`` + + - Windows: ``C:\dev\apex-pdp`` + + - Cygwin: ``/cygdrive/c/dev/apex-pdp`` + + .. important:: + A Build requires ONAP Nexus + APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current + settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__. + + .. important:: + A Build needs Space + Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full distribution and 1-2 GB for + the downloaded dependencies + + .. important:: + A Build requires Internet (for first build) + During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven + repository. The first standard build (and any first specific build) requires Internet access to download those dependencies. + + .. important:: + Building RPM distributions + RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``, + then build APEX. + + .. container:: paragraph + + Use Maven to for a standard build without any tests. + + +-------------------------------------------------------+--------------------------------------------------------+ + | Unix, Cygwin | Windows | + +=======================================================+========================================================+ + | .. container:: | .. container:: | + | | | + | .. container:: content | .. container:: content | + | | | + | .. code:: bash | .. code:: bash | + | :number-lines: | :number-lines: | + | | | + | >c: | # cd /usr/local/src/apex-pdp | + | >cd \dev\apex | # mvn clean install -DskipTest | + | >mvn clean install -DskipTests | | + +-------------------------------------------------------+--------------------------------------------------------+ + +.. container:: paragraph + + The build takes 2-3 minutes on a standard development laptop. It + should run through without errors, but with a lot of messages from + the build process. + +.. container:: paragraph + + When Maven is finished with the build, the final screen should look + similar to this (omitting some ``success`` lines): + +.. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + [INFO] tools .............................................. SUCCESS [ 0.248 s] + [INFO] tools-common ....................................... SUCCESS [ 0.784 s] + [INFO] simple-wsclient .................................... SUCCESS [ 3.303 s] + [INFO] model-generator .................................... SUCCESS [ 0.644 s] + [INFO] packages ........................................... SUCCESS [ 0.336 s] + [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min] + [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s] + [INFO] ------------------------------------------------------------------------ + [INFO] BUILD SUCCESS + [INFO] ------------------------------------------------------------------------ + [INFO] Total time: 03:43 min + [INFO] Finished at: 2018-09-03T11:56:01+01:00 + [INFO] ------------------------------------------------------------------------ + +.. container:: paragraph + + The build will have created all artifacts required for an APEX + installation. The following example show how to change to the target + directory and how it should look like. + ++----------------------------------------------------------------------------------------------------------------------------+ +| Unix, Cygwin | ++============================================================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. container:: content | +| | +| .. code:: bash | +| :number-lines: | +| | +| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* | +| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* | +| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* | +| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ | +| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* | +| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* | +| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* | +| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ | ++----------------------------------------------------------------------------------------------------------------------------+ + ++--------------------------------------------------------------------------------------------------------+ +| Windows | ++========================================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. container:: content | +| | +| .. code:: bash | +| :number-lines: | +| | +| 03/09/2018 11:55 <DIR> . | +| 03/09/2018 11:55 <DIR> .. | +| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz | +| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb | +| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar | +| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes | +| 03/09/2018 11:54 <DIR> archive-tmp | +| 03/09/2018 11:54 89 checkstyle-cachefile | +| 03/09/2018 11:54 10,621 checkstyle-checker.xml | +| 03/09/2018 11:54 584 checkstyle-header.txt | +| 03/09/2018 11:54 86 checkstyle-result.xml | +| 03/09/2018 11:54 <DIR> classes | +| 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers | +| 03/09/2018 11:54 <DIR> etc | +| 03/09/2018 11:54 <DIR> examples | +| 03/09/2018 11:55 <DIR> install_hierarchy | +| 03/09/2018 11:54 <DIR> maven-archiver | +| 8 File(s) 292,652,686 bytes | +| 9 Dir(s) 14,138,720,256 bytes free | ++--------------------------------------------------------------------------------------------------------+ + +Install APEX +^^^^^^^^^^^^ + + .. container:: paragraph + + APEX can be installed in different ways: + + .. container:: ulist + + - Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm`` + or ``.deb`` archive + + - Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive + + - Windows, Unix, Cygwin: build from source using Maven, then + install manually + +Install with RPM and DPKG +------------------------- + + .. container:: paragraph + + The install distributions of APEX automatically install the + system. The installation directory is + ``/opt/app/policy/apex-pdp``. Log files are located in + ``/var/log/onap/policy/apex-pdp``. The latest APEX version + will be available as ``/opt/app/policy/apex-pdp/apex-pdp``. + + .. container:: paragraph + + For the installation, a new user ``apexuser`` and a new + group ``apexuser`` will be created. This user owns the + installation directories and the log file location. The user + is also used by the standard APEX start scripts to run APEX + with this user’s permissions. + + +-----------------------------------------------------------------------+ + | RPM Installation | + +=======================================================================+ + | .. container:: | + | | + | .. container:: listingblock | + | | + | .. container:: content | + | | + | .. code:: bash | + | :number-lines: | + | | + | # sudo rpm -i apex-pdp-package-full-2.0.0-SNAPSHOT.rpm | + | ********************preinst******************* | + | arguments 1 | + | ********************************************** | + | creating group apexuser . . . | + | creating user apexuser . . . | + | ********************postinst**************** | + | arguments 1 | + | *********************************************** | + +-----------------------------------------------------------------------+ + ++--------------------------------------------------------------------------------------+ +| DPKG Installation | ++======================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. container:: content | +| | +| .. code:: bash | +| :number-lines: | +| | +| # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb | +| Selecting previously unselected package apex-uservice. | +| (Reading database ... 288458 files and directories currently installed.) | +| Preparing to unpack apex-pdp-package-full-2.0.0-SNAPSHOT.deb ... | +| ********************preinst******************* | +| arguments install | +| ********************************************** | +| creating group apexuser . . . | +| creating user apexuser . . . | +| Unpacking apex-uservice (2.0.0-SNAPSHOT) ... | +| Setting up apex-uservice (2.0.0-SNAPSHOT) ... | +| ********************postinst**************** | +| arguments configure | +| *********************************************** | ++--------------------------------------------------------------------------------------+ + +.. container:: paragraph + + Once the installation is finished, APEX is fully installed and ready + to run. + +Install Manually from Archive (Unix, Cygwin) +-------------------------------------------- + + .. container:: paragraph + + Download a ``tar.gz`` archive. Create a directory where APEX + should be installed. Extract the ``tar`` archive. The following + example shows how to install APEX in ``/opt/apex`` and create a + link to ``/opt/apex/apex`` for the most recent installation. + + .. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + # cd /opt + # mkdir apex + # cd apex + # mkdir apex-full-2.0.0-SNAPSHOT + # tar xvfz ~/Downloads/apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -C apex-full-2.0.0-SNAPSHOT + # ln -s apex apex-pdp-package-full-2.0.0-SNAPSHOT + +Install Manually from Archive (Windows, 7Zip, GUI) +-------------------------------------------------- + + .. container:: paragraph + + Download a ``tar.gz`` archive and copy the file into the install + folder (in this example ``C:\apex``). Assuming you are using 7Zip, + right click on the file and extract the ``tar`` archive. Note: the + screenshots might show an older version than you have. + + .. container:: imageblock + + .. container:: content + + |Extract the TAR archive| + + .. container:: paragraph + + The right-click on the new created TAR file and extract the actual + APEX distribution. + + .. container:: imageblock + + .. container:: content + + |Extract the APEX distribution| + + .. container:: paragraph + + Inside the new APEX folder you see the main directories: ``bin``, + ``etc``, ``examples``, ``lib``, and ``war`` + + .. container:: paragraph + + Once extracted, please rename the created folder to + ``apex-full-2.0.0-SNAPSHOT``. This will keep the directory name in + line with the rest of this documentation. + +Install Manually from Archive (Windows, 7Zip, CMD) +-------------------------------------------------- + + .. container:: paragraph + + Download a ``tar.gz`` archive and copy the file into the install + folder (in this example ``C:\apex``). Start ``cmd``, for instance + typing ``Windows+R`` and then ``cmd`` in the dialog. Assuming + ``7Zip`` is installed in the standard folder, simply run the + following commands (for APEX version 2.0.0-SNAPSHOT full + distribution) + + .. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + >c: + >cd \apex + >"\Program Files\7-Zip\7z.exe" x apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -so | "\Program Files\7-Zip\7z.exe" x -aoa -si -ttar -o"apex-full-2.0.0-SNAPSHOT" + +.. container:: paragraph + + APEX is now installed in the folder + ``C:\apex\apex-full-2.0.0-SNAPSHOT``. + +Build from Source +^^^^^^^^^^^^^^^^^ + +Build and Install Manually (Unix, Windows, Cygwin) +-------------------------------------------------- + + .. container:: paragraph + + Clone the APEX GIT repositories into a directory. Go to that + directory. Use Maven to build APEX (all details on building + APEX from source can be found in *APEX HowTo: Build*). + Install from the created artifacts (``rpm``, ``deb``, + ``tar.gz``, or copying manually). + + .. important:: + Building RPM distributions + RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``, + then build APEX. + + .. container:: paragraph + + The following example shows how to build the APEX system, + without tests (``-DskipTests``) to safe some time. It + assumes that the APX GIT repositories are cloned to: + + .. container:: ulist + + - Unix, Cygwin: ``/usr/local/src/apex`` + + - Windows: ``C:\dev\apex`` + + +-------------------------------------------------------+--------------------------------------------------------+ + | Unix, Cygwin | Windows | + +=======================================================+========================================================+ + | .. container:: | .. container:: | + | | | + | .. container:: content | .. container:: content | + | | | + | .. code:: bash | .. code:: bash | + | :number-lines: | :number-lines: | + | | | + | >c: | # cd /usr/local/src/apex | + | >cd \dev\apex | # mvn clean install -DskipTests | + | >mvn clean install -DskipTests | | + +-------------------------------------------------------+--------------------------------------------------------+ + +.. container:: paragraph + + The build takes about 2 minutes without test and about 4-5 minutes + with tests on a standard development laptop. It should run through + without errors, but with a lot of messages from the build process. If + build with tests (i.e. without ``-DskipTests``), there will be error + messages and stack trace prints from some tests. This is normal, as + long as the build finishes successful. + +.. container:: paragraph + + When Maven is finished with the build, the final screen should look + similar to this (omitting some ``success`` lines): + +.. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + [INFO] tools .............................................. SUCCESS [ 0.248 s] + [INFO] tools-common ....................................... SUCCESS [ 0.784 s] + [INFO] simple-wsclient .................................... SUCCESS [ 3.303 s] + [INFO] model-generator .................................... SUCCESS [ 0.644 s] + [INFO] packages ........................................... SUCCESS [ 0.336 s] + [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min] + [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s] + [INFO] ------------------------------------------------------------------------ + [INFO] BUILD SUCCESS + [INFO] ------------------------------------------------------------------------ + [INFO] Total time: 03:43 min + [INFO] Finished at: 2018-09-03T11:56:01+01:00 + [INFO] ------------------------------------------------------------------------ + +.. container:: paragraph + + The build will have created all artifacts required for an APEX + installation. The following example show how to change to the target + directory and how it should look like. + ++-----------------------------------------------------------------------------------------------------------------------------+ +| Unix, Cygwin | ++=============================================================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. code:: bash | +| :number-lines: | +| | +| # cd packages/apex-pdp-package-full/target | +| # ls -l | +| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* | +| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* | +| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* | +| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ | +| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* | +| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* | +| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* | +| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ | +| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ | ++-----------------------------------------------------------------------------------------------------------------------------+ + ++-----------------------------------------------------------------------------------------------------------------------------+ +| Windows | ++=============================================================================================================================+ +| .. container:: | +| | +| .. container:: listingblock | +| | +| .. code:: bash | +| :number-lines: | +| | +| >cd packages\apex-pdp-package-full\target | +| >dir | +| 03/09/2018 11:55 <DIR> . | +| 03/09/2018 11:55 <DIR> .. | +| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz | +| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb | +| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar | +| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes | +| 03/09/2018 11:54 <DIR> archive-tmp | +| 03/09/2018 11:54 89 checkstyle-cachefile | +| 03/09/2018 11:54 10,621 checkstyle-checker.xml | +| 03/09/2018 11:54 584 checkstyle-header.txt | +| 03/09/2018 11:54 86 checkstyle-result.xml | +| 03/09/2018 11:54 <DIR> classes | +| 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers | +| 03/09/2018 11:54 <DIR> etc | +| 03/09/2018 11:54 <DIR> examples | +| 03/09/2018 11:55 <DIR> install_hierarchy | +| 03/09/2018 11:54 <DIR> maven-archiver | +| 8 File(s) 292,652,686 bytes | +| 9 Dir(s) 14,138,720,256 bytes free | ++-----------------------------------------------------------------------------------------------------------------------------+ + +.. container:: paragraph + + Now, take the ``.deb`` or the ``.tar.gz`` file and install APEX. + Alternatively, copy the content of the folder ``install_hierarchy`` + to your APEX directory. + +Installation Layout +^^^^^^^^^^^^^^^^^^^ + + .. container:: paragraph + + A full installation of APEX comes with the following layout. + + .. container:: listingblock + + .. container:: content + + :: + + $APEX_HOME + ├───bin (1) + ├───etc (2) + │ ├───editor + │ ├───hazelcast + │ ├───infinispan + │ └───META-INF + ├───examples (3) + │ ├───config (4) + │ ├───docker (5) + │ ├───events (6) + │ ├───html (7) + │ ├───models (8) + │ └───scripts (9) + ├───lib (10) + │ └───applications (11) + └───war (12) + + .. container:: colist arabic + + +-----------------------------------+-----------------------------------+ + | **1** | binaries, mainly scripts (bash | + | | and bat) to start the APEX engine | + | | and applications | + +-----------------------------------+-----------------------------------+ + | **2** | configuration files, such as | + | | logback (logging) and third party | + | | library configurations | + +-----------------------------------+-----------------------------------+ + | **3** | example policy models to get | + | | started | + +-----------------------------------+-----------------------------------+ + | **4** | configurations for the examples | + | | (with sub directories for | + | | individual examples) | + +-----------------------------------+-----------------------------------+ + | **5** | Docker files and additional | + | | Docker instructions for the | + | | exampples | + +-----------------------------------+-----------------------------------+ + | **6** | example events for the examples | + | | (with sub directories for | + | | individual examples) | + +-----------------------------------+-----------------------------------+ + | **7** | HTML files for some examples, | + | | e.g. the Decisionmaker example | + +-----------------------------------+-----------------------------------+ + | **8** | the policy models, generated for | + | | each example (with sub | + | | directories for individual | + | | examples) | + +-----------------------------------+-----------------------------------+ + | **9** | additional scripts for the | + | | examples (with sub directories | + | | for individual examples) | + +-----------------------------------+-----------------------------------+ + | **10** | the library folder with all Java | + | | JAR files | + +-----------------------------------+-----------------------------------+ + | **11** | applications, also known as jar | + | | with dependencies (or fat jars), | + | | individually deployable | + +-----------------------------------+-----------------------------------+ + | **12** | WAR files for web applications | + +-----------------------------------+-----------------------------------+ + +System Configuration +^^^^^^^^^^^^^^^^^^^^ + + .. container:: paragraph + + Once APEX is installed, a few configurations need to be done: + + .. container:: ulist + + - Create an APEX user and an APEX group (optional, if not + installed using RPM and DPKG) + + - Create environment settings for ``APEX_HOME`` and + ``APEX_USER``, required by the start scripts + + - Change settings of the logging framework (optional) + + - Create directories for logging, required (execution might + fail if directories do not exist or cannot be created) + +APEX User and Group +------------------- + + .. container:: paragraph + + On smaller installations and test systems, APEX can run as + any user or group. + + .. container:: paragraph + + However, if APEX is installed in production, we strongly + recommend you set up a dedicated user for running APEX. This + will isolate the execution of APEX to that user. We + recommend you use the userid ``apexuser`` but you may use + any user you choose. + + .. container:: paragraph + + The following example, for UNIX, creates a group called + ``apexuser``, an APEX user called ``apexuser``, adds the + group to the user, and changes ownership of the APEX + installation to the user. Substitute ``<apex-dir>`` with the + directory where APEX is installed. + + .. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + # sudo groupadd apexuser + # sudo useradd -g apexuser apexuser + # sudo chown -R apexuser:apexuser <apex-dir> + +.. container:: paragraph + + For other operating systems please consult your manual or system + administrator. + +Environment Settings: APEX_HOME and APEX_USER +--------------------------------------------- + + .. container:: paragraph + + The provided start scripts for APEX require two environment + variables being set: + + .. container:: ulist + + - ``APEX_USER`` with the user under whos name and permission APEX + should be started (Unix only) + + - ``APEX_HOME`` with the directory where APEX is installed (Unix, + Windows, Cygwin) + + .. container:: paragraph + + The first row in the following table shows how to set these + environment variables temporary (assuming the user is + ``apexuser``). The second row shows how to verify the settings. + The last row explains how to set those variables permanently. + + +------------------------------------------------+---------------------------------------------------------+ + | Unix, Cygwin (bash/tcsh) | Windows | + +================================================+=========================================================+ + | .. container:: | .. container:: | + | | | + | .. container:: content | .. container:: content | + | | | + | .. code:: bash | .. code:: bash | + | :number-lines: | :number-lines: | + | | | + | # export APEX_USER=apexuser | >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT | + | # cd /opt/app/policy/apex-pdp | | + | # export APEX_HOME=`pwd` | | + | | | + +------------------------------------------------+ | + | .. container:: | | + | | | + | .. container:: content | | + | | | + | .. code:: tcsh | | + | :number-lines: | | + | | | + | # setenv APEX_USER apexuser | | + | # cd /opt/app/policy/apex-pdp | | + | # setenv APEX_HOME `pwd` | | + | | | + +------------------------------------------------+---------------------------------------------------------+ + | .. container:: | .. container:: | + | | | + | .. container:: content | .. container:: content | + | | | + | .. code:: bash | .. code:: bash | + | :number-lines: | :number-lines: | + | | | + | # env | grep APEX | >set APEX_HOME | + | # APEX_USER=apexuser | APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT | + | # APEX_HOME=/opt/app/policy/apex-pdp | | + | | | + +------------------------------------------------+---------------------------------------------------------+ + + +Making Environment Settings Permanent (Unix, Cygwin) +#################################################### + + .. container:: paragraph + + For a per-user setting, edit the a user’s ``bash`` or ``tcsh`` + settings in ``~/.bashrc`` or ``~/.tcshrc``. For system-wide + settings, edit ``/etc/profiles`` (requires permissions). + + +Making Environment Settings Permanent (Windows) +############################################### + + .. container:: paragraph + + On Windows 7 do + + .. container:: ulist + + - Click on the **Start** Menu + + - Right click on **Computer** + + - Select **Properties** + + .. container:: paragraph + + On Windows 8/10 do + + .. container:: ulist + + - Click on the **Start** Menu + + - Select **System** + + .. container:: paragraph + + Then do the following + + .. container:: ulist + + - Select **Advanced System Settings** + + - On the **Advanced** tab, click the **Environment Variables** + button + + - Edit an existing variable, or create a new System variable: + 'Variable name'="APEX_HOME", 'Variable + value'="C:\apex\apex-full-2.0.0-SNAPSHOT" + + .. container:: paragraph + + For the settings to take effect, an application needs to be + restarted (e.g. any open ``cmd`` window). + +Edit the APEX Logging Settings +------------------------------ + + .. container:: paragraph + + Configure the APEX logging settings to your requirements, for + instance: + + .. container:: ulist + + - change the directory where logs are written to, or + + - change the log levels + + .. container:: paragraph + + Edit the file ``$APEX_HOME/etc/logback.xml`` for any required + changes. To change the log directory change the line + + .. container:: paragraph + + ``<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />`` + + .. container:: paragraph + + to + + .. container:: paragraph + + ``<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />`` + + .. container:: paragraph + + On Windows, it is recommended to change the log directory to: + + .. container:: paragraph + + ``<property name="VAR_LOG" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />`` + + .. container:: paragraph + + Note: Be careful about when to use ``\`` vs. ``/`` as the path + separator! + +Create Directories for Logging +------------------------------ + + .. container:: paragraph + + Make sure that the log directory exists. This is important when + APEX was installed manually or when the log directory was changed + in the settings (see above). + + +------------------------------------------------------------------+-------------------------------------------------------+ + | Unix, Cygwin | Windows | + +==================================================================+=======================================================+ + | .. container:: | .. container:: | + | | | + | .. container:: content | .. container:: content | + | | | + | .. code:: bash | .. code:: bash | + | :number-lines: | :number-lines: | + | | | + | mkdir -p /var/log/onap/policy/apex-pdp | >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs | + | chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp | | + +------------------------------------------------------------------+-------------------------------------------------------+ + +Verify the APEX Installation +############################ + + .. container:: sectionbody + + .. container:: paragraph + + When APEX is installed and all settings are realized, the + installation can be verified. + +Verify Installation - run Engine +-------------------------------- + + .. container:: paragraph + + A simple verification of an APEX installation can be done by + simply starting the APEX engine without any configuration. + On Unix (or Cygwin) start the engine using + ``$APEX_HOME/bin/apexEngine.sh``. On Windows start the + engine using ``%APEX_HOME%\bin\apexEngine.bat``. The engine + will fail to fully start. However, if the output looks + similar to the following line, the APEX installation is + realized. + + .. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + Starting Apex service with parameters [] . . . + start of Apex service failed: Apex configuration file was not specified as an argument + 2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed + org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument + at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267) + at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161) + at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68) + at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165) + usage: org.onap.policy.apex.service.engine.main.ApexMain [options...] + options + -c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file + containing the Apex configuration parameters + -h,--help outputs the usage of this command + -m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the + configuration file + -v,--version outputs the version of Apex + +Verify Installation - run an Example +------------------------------------ + + .. container:: paragraph + + A full APEX installation comes with several examples. Here, we can + fully verify the installation by running one of the examples. + + .. container:: paragraph + + We use the example called *SampleDomain* and configure the engine + to use standard in and standard out for events. Run the engine + with the provided configuration. Note: Cygwin executes scripts as + Unix scripts but runs Java as a Windows application, thus the + configuration file must be given as a Windows path. + + .. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1) + # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2) + >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3) + +.. container:: colist arabic + + +-------+---------+ + | **1** | UNIX | + +-------+---------+ + | **2** | Cygwin | + +-------+---------+ + | **3** | Windows | + +-------+---------+ + +.. container:: paragraph + + The engine should start successfully. Assuming the logging levels are + not change (default level is ``info``), the output should look + similar to this (last few lines) + +.. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + Starting Apex service with parameters [-c, v:/dev/ericsson/apex/onap/apex-pdp/packages/apex-pdp-package-full/target/install_hierarchy/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json] . . . + 2018-09-05 15:16:42,800 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-0:0.0.1 . + 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-1:0.0.1 . + 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-2:0.0.1 . + 2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-3:0.0.1 . + 2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created. + 2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . . + 2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started + 2018-09-05 15:16:44,987 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-0:0.0.1 + 2018-09-05 15:16:45,112 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-1:0.0.1 + 2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-2:0.0.1 + 2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-3:0.0.1 + 2018-09-05 15:16:45,120 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine + Started Apex service + +.. container:: paragraph + + Important are the last two line, stating that APEX has added the + final action listener to the engine and that the engine is started. + +.. container:: paragraph + + The engine is configured to read events from standard input and write + produced events to standard output. The policy model is a very simple + policy. + +.. container:: paragraph + + The following table shows an input event in the left column and an + output event in the right column. Past the input event into the + console where APEX is running, and the output event should appear in + the console. Pasting the input event multiple times will produce + output events with different values. + ++-------------------------------------------------------------+-------------------------------------------------------------+ +| Input Event | Example Output Event | ++=============================================================+=============================================================+ +| .. container:: | .. container:: | +| | | +| .. container:: content | .. container:: content | +| | | +| .. code:: bash | .. code:: bash | +| :number-lines: | :number-lines: | +| | | +| { | { | +| "nameSpace": "org.onap.policy.apex.sample.events", | "name": "Event0004", | +| "name": "Event0000", | "version": "0.0.1", | +| "version": "0.0.1", | "nameSpace": "org.onap.policy.apex.sample.events", | +| "source": "test", | "source": "Act", | +| "target": "apex", | "target": "Outside", | +| "TestSlogan": "Test slogan for External Event0", | "TestActCaseSelected": 2, | +| "TestMatchCase": 0, | "TestActStateTime": 1536157104627, | +| "TestTimestamp": 1469781869269, | "TestDecideCaseSelected": 0, | +| "TestTemperature": 9080.866 | "TestDecideStateTime": 1536157104625, | +| } | "TestEstablishCaseSelected": 0, | +| | "TestEstablishStateTime": 1536157104623, | +| | "TestMatchCase": 0, | +| | "TestMatchCaseSelected": 1, | +| | "TestMatchStateTime": 1536157104620, | +| | "TestSlogan": "Test slogan for External Event0", | +| | "TestTemperature": 9080.866, | +| | "TestTimestamp": 1469781869269 | +| | } | ++-------------------------------------------------------------+-------------------------------------------------------------+ + +.. container:: paragraph + + Terminate APEX by simply using ``CTRL+C`` in the console. + +Verify a Full Installation - REST Editor +---------------------------------------- + + .. container:: paragraph + + APEX has a REST application for viewing policy models. The + application can also be used to create new policy models close to + the engine native policy language. Start the REST editor as + follows. + + .. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + # $APEX_HOME/bin/apexApps.sh rest-editor + +.. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + >%APEX_HOME%\bin\apexApps.bat rest-editor + +.. container:: paragraph + + The script will start a simple web server + (`Grizzly <https://javaee.github.io/grizzly/>`__) and deploy a + ``war`` web archive in it. Once the editor is started, it will be + available on ``localhost:18989``. The last few line of the messages + should be: + +.. container:: listingblock + + .. container:: content + + .. code:: bash + :number-lines: + + Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . . + Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start + INFO: Started listener bound to [localhost:18989] + Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start + INFO: [HttpServer] Started. + Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ + +.. container:: paragraph + + Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and + use the URL ``http://localhost:18989/``. This will connect the + browser to the started REST editor. The start screen should be as + follows. + +.. container:: imageblock + + .. container:: content + + |REST Editor Start Screen| + + .. container:: title + + Figure 1. REST Editor Start Screen + +.. container:: paragraph + + Now load a policy model by clicking the menu ``File`` and then + ``Open``. In the opened dialog, go to the directory where APEX is + installed, then ``examples``, ``models``, ``SampleDomain``, and there + select the file ``SamplePolicyModelJAVA.json``. This will load the + policy model used to verify the policy engine (see above). Once + loaded, the screen should look as follows. + +.. container:: imageblock + + .. container:: content + + |REST Editor with loaded SampleDomain Policy Model| + + .. container:: title + + Figure 2. REST Editor with loaded SampleDomain Policy Model + +.. container:: paragraph + + Now you can use the REST editor. To finish this verification, simply + terminate your browser (or the tab), and then use ``CTRL+C`` in the + console where you started the REST editor. + +Installing WAR Applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + APEX comes with a set of WAR files. These are complete + applications that can be installed and run in an application + server. All of these applications are realized as servlets. You + can find the WAR applications in ``$APEX_HOME/war`` (UNIX, + Cygwin) or ``%APEX_HOME%\war`` (Windows). + + .. container:: paragraph + + Installing and using the WAR applications requires a web server + that can execute ``war`` web archives. We recommend to use + `Apache Tomcat <https://tomcat.apache.org/>`__, however other + web servers can be used as well. + + .. container:: paragraph + + Install Apache Tomcat including the ``Manager App``, see `V9.0 + Docs <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access>`__ + for details. Start the Tomcat service, or make sure that Tomcat + is running. + + .. container:: paragraph + + There are multiple ways to install the APEX WAR applications: + + .. container:: ulist + + - copy the ``.war`` file into the Tomcat ``webapps`` folder + + - use the Tomcat ``Manager App`` to deploy via the web + interface + + - deploy using a REST call to Tomcat + + .. container:: paragraph + + For details on how to install ``war`` files please consult the + `Tomcat + Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__ + or the `Manager App + HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html>`__. + Once you installed an APEX WAR application (and wait for + sufficient time for Tomcat to finalize the installation), open + the ``Manager App`` in Tomcat. You should see the APEX WAR + application being installed and running. + + .. container:: paragraph + + In case of errors, examine the log files in the Tomcat log + directory. In a conventional install, those log files are in + the logs directory where Tomcat is installed. + + .. container:: paragraph + + The current APEX version provides the following WAR + applications: + + .. container:: ulist + + - client-deployment-2.0.0-SNAPSHOT.war - a client to deploy + new policy models to a running engine + + - client-editor-2.0.0-SNAPSHOT.war - the standard policy REST + editor GUI + + - client-monitoring-2.0.0-SNAPSHOT.war - a client for + monitoring a running APEX engine + + - client-full-2.0.0-SNAPSHOT.war - a full client with a + one-stop-access to deployment, monitoring, and REST editor + + - examples-servlet-2.0.0-SNAPSHOT.war - an example APEX + servlet + +Running APEX in Docker +^^^^^^^^^^^^^^^^^^^^^^ + + .. container:: sectionbody + + .. container:: paragraph + + Since APEX is in ONAP, we provide a full virtualization + environment for the engine. + +Run in ONAP +----------- + + .. container:: paragraph + + Running APEX from the ONAP docker repository only requires 2 + commands: + + .. container:: olist arabic + + #. Log into the ONAP docker repo + + .. container:: listingblock + + .. container:: content + + :: + + docker login -u docker -p docker nexus3.onap.org:10003 + + .. container:: olist arabic + + #. Run the APEX docker image + + .. container:: listingblock + + .. container:: content + + :: + + docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest + + +Build a Docker Image +-------------------- + + .. container:: paragraph + + Alternatively, one can use the Dockerfile defined in the + Docker package to build an image. + + .. container:: listingblock + + .. container:: title + + APEX Dockerfile + + .. container:: content + + .. code:: bash + :number-lines: + + # + # Docker file to build an image that runs APEX on Java 8 in Ubuntu + # + FROM ubuntu:16.04 + + RUN apt-get update && \ + apt-get upgrade -y && \ + apt-get install -y software-properties-common && \ + add-apt-repository ppa:openjdk-r/ppa -y && \ + apt-get update && \ + apt-get install -y openjdk-8-jdk + + # Create apex user and group + RUN groupadd apexuser + RUN useradd --create-home -g apexuser apexuser + + # Add Apex-specific directories and set ownership as the Apex admin user + RUN mkdir -p /opt/app/policy/apex-pdp + RUN mkdir -p /var/log/onap/policy/apex-pdp + RUN chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp + + # Unpack the tarball + RUN mkdir /packages + COPY apex-pdp-package-full.tar.gz /packages + RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory /opt/app/policy/apex-pdp + RUN rm /packages/apex-pdp-package-full.tar.gz + + # Ensure everything has the correct permissions + RUN find /opt/app -type d -perm 755 + RUN find /opt/app -type f -perm 644 + RUN chmod a+x /opt/app/policy/apex-pdp/bin/* + + # Copy examples to Apex user area + RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser + + RUN apt-get clean + + RUN chown -R apexuser:apexuser /home/apexuser/* + + USER apexuser + ENV PATH /opt/app/policy/apex-pdp/bin:$PATH + WORKDIR /home/apexuser + +.. container:: + :name: footer + + .. container:: + :name: footer-text + + 2.0.0-SNAPSHOT + Last updated 2018-09-10 15:38:16 IST + +.. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png +.. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png +.. |REST Editor Start Screen| image:: images/install-guide/rest-start.png +.. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png + |