summaryrefslogtreecommitdiffstats
path: root/docs/APEX-Install-Guide.rst
diff options
context:
space:
mode:
authormmis <michael.morris@ericsson.com>2018-10-08 15:54:36 +0100
committermmis <michael.morris@ericsson.com>2018-10-09 11:50:06 +0000
commitd4e7632aa00b42c544406fe9d83621c50831fe8e (patch)
treea975f9729746a0d95e2c9e79c0e73e1d8b059558 /docs/APEX-Install-Guide.rst
parent88ca44387f65cae61b500f4219d985bd9a1687a9 (diff)
Added documentation for readthedocs
Issue-ID: POLICY-1161 Change-Id: I8a3ac2b8fbfccacd04cfd5cb3bc649d9674ec59b Signed-off-by: mmis <michael.morris@ericsson.com>
Diffstat (limited to 'docs/APEX-Install-Guide.rst')
-rw-r--r--docs/APEX-Install-Guide.rst1418
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
+