summaryrefslogtreecommitdiffstats
path: root/docs/apex/APEX-User-Manual.rst
diff options
context:
space:
mode:
authorliamfallon <liam.fallon@est.tech>2020-07-02 15:32:26 +0100
committerliamfallon <liam.fallon@est.tech>2020-07-02 17:28:37 +0100
commit3e524ba18ca3591fe122ad91643f39d6230fd644 (patch)
tree2da14520ec307d662755ee13b96be33d8b58ccd3 /docs/apex/APEX-User-Manual.rst
parentd0631367e718fb46148514b768320993b3159386 (diff)
Apex user manual: Frankfurt changes
A number of changes in Frankfurt impacted the isntallation and configuration process for apex, especially in standalone mode. Issue-ID: POLICY-2686 Change-Id: Id114416cc73ba3669bcd3a98979e7595e9e1e2ca Signed-off-by: liamfallon <liam.fallon@est.tech>
Diffstat (limited to 'docs/apex/APEX-User-Manual.rst')
-rw-r--r--docs/apex/APEX-User-Manual.rst146
1 files changed, 58 insertions, 88 deletions
diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst
index 50468a22..106e1e81 100644
--- a/docs/apex/APEX-User-Manual.rst
+++ b/docs/apex/APEX-User-Manual.rst
@@ -28,11 +28,11 @@ Installation Requirements
.. container:: ulist
- Downloaded distribution: JAVA runtime environment
- (JRE, Java 8 or later, APEX is tested with the
- Oracle Java)
+ (JRE, Java 11 or later, APEX is tested with the
+ OpenJDK Java)
- Building from source: JAVA development kit (JDK,
- Java 8 or later, APEX is tested with the Oracle
+ Java 11 or later, APEX is tested with the OpenJDK
Java)
- A web archive capable webserver, for instance for
@@ -65,12 +65,6 @@ Installation Requirements
- 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
@@ -172,11 +166,6 @@ Build APEX
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.
@@ -305,7 +294,7 @@ Install APEX
.. container:: ulist
- - Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm`` or
+ - Unix: automatically using ``dpkg`` from
``.deb`` archive
- Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive
@@ -313,11 +302,14 @@ Install APEX
- Windows, Unix, Cygwin: build from source using Maven, then
install manually
-Install with RPM and DPKG
-#########################
+Install with DPKG
+#################
.. container:: paragraph
+ You can get the APEX debian package from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
The install distributions of APEX automatically install the
system. The installation directory is
``/opt/app/policy/apex-pdp``. Log files are located in
@@ -332,29 +324,6 @@ Install with RPM and DPKG
the standard APEX start scripts to run APEX with this user’s
permissions.
- +-----------------------------------------------------------------------+
- | RPM Installation |
- +=======================================================================+
- | .. container:: |
- | |
- | .. container:: listingblock |
- | |
- | .. container:: content |
- | |
- | .. code:: |
- | :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 |
+======================================================================================+
@@ -393,7 +362,10 @@ Install Manually from Archive (Unix, Cygwin)
.. container:: paragraph
- Download a ``tar.gz`` archive. Create a directory where APEX
+ You can download a ``tar.gz`` archive from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
+ 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.
@@ -417,7 +389,10 @@ Install Manually from Archive (Windows, 7Zip, GUI)
.. container:: paragraph
- Download a ``tar.gz`` archive and copy the file into the install
+ You can download a ``tar.gz`` archive from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
+ Copy the ``tar.gz`` 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.
@@ -455,7 +430,10 @@ Install Manually from Archive (Windows, 7Zip, CMD)
.. container:: paragraph
- Download a ``tar.gz`` archive and copy the file into the install
+ You can download a ``tar.gz`` archive from the
+ `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/packages/apex-pdp-package-full/>`__.
+
+ Copy the ``tar.gz`` 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
@@ -492,11 +470,6 @@ Build and Install Manually (Unix, Windows, Cygwin)
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,
@@ -1138,14 +1111,14 @@ Verify Installation - run an Example
Terminate APEX by simply using ``CTRL+C`` in the console.
-Verify a Full Installation - REST Editor
+Verify a Full Installation - REST Client
########################################
.. container:: paragraph
- APEX has a REST application for viewing policy models. The
+ APEX has a REST application for deploying, monitoring, and 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
+ the engine native policy language. Start the REST client as
follows.
.. container:: listingblock
@@ -1155,7 +1128,7 @@ Verify a Full Installation - REST Editor
.. code::
:number-lines:
- # $APEX_HOME/bin/apexApps.sh rest-editor
+ # $APEX_HOME/bin/apexApps.sh full-client
.. container:: listingblock
@@ -1164,13 +1137,13 @@ Verify a Full Installation - REST Editor
.. code::
:number-lines:
- >%APEX_HOME%\bin\apexApps.bat rest-editor
+ >%APEX_HOME%\bin\apexApps.bat full-client
.. 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
+ ``war`` web archive in it. Once the client is started, it will be
available on ``localhost:18989``. The last few line of the messages
should be:
@@ -1181,18 +1154,19 @@ Verify a Full Installation - REST Editor
.. code::
: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
+ Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
+ Jul 02, 2020 2:57:39 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
+ Jul 02, 2020 2:57:39 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/
+ Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: 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
+ browser to the started REST client. Click on the "Policy Editor" button and the Policy Editor start screen should be as
follows.
.. container:: imageblock
@@ -1230,20 +1204,20 @@ Verify a Full Installation - REST Editor
terminate your browser (or the tab), and then use ``CTRL+C`` in the
console where you started the REST editor.
-Installing WAR Applications
----------------------------
+Installing the WAR Application
+------------------------------
.. 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).
+ The three APEX clients are packaged in a WAR file. This is a complete
+ application that can be installed and run in an application
+ server. The application is realized as a servlet. You
+ can find the WAR application in the `ONAP Nexus Repository <https://nexus.onap.org/content/groups/public/org/onap/policy/apex-pdp/client/apex-client-full/>`__.
+
.. container:: paragraph
- Installing and using the WAR applications requires a web server
+ Installing and using the WAR application 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.
@@ -1257,7 +1231,7 @@ Installing WAR Applications
.. container:: paragraph
- There are multiple ways to install the APEX WAR applications:
+ There are multiple ways to install the APEX WAR application:
.. container:: ulist
@@ -1287,23 +1261,7 @@ Installing WAR Applications
.. 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
+ The WAR application file has a name similar to *apex-client-full-<VERSION>.war*.
Running APEX in Docker
----------------------
@@ -1559,7 +1517,8 @@ Engine Service Parameters
"id" : 45, (3)
"instanceCount" : 4, (4)
"deploymentPort" : 12345, (5)
- "policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6)
+ "policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6a)
+ "policy_type_impl" : {...}, (6b)
"periodicEventPeriod": 1000, (7)
"engineParameters":{ (8)
"executorParameters":{...}, (9)
@@ -1601,8 +1560,19 @@ Engine Service Parameters
| | Websocket connection to the |
| | engine |
+-----------------------------------+-----------------------------------+
- | **6** | the model file to load into the |
- | | engine on startup (optional) |
+ | **6a** | the APEX policy model file to |
+ | | load into the engine on startup |
+ | | when APEX is running native |
+ | | policies in standalone mode |
+ | | (optional) |
+ +-----------------------------------+-----------------------------------+
+ | **6b** | the APEX policy model as a JSON |
+ | | or YAML block to load into the |
+ | | engine on startup when |
+ | | APEX is running a policy that has |
+ | | its logic and parameters |
+ | | specified in TOSCA |
+ | | (optional) |
+-----------------------------------+-----------------------------------+
| **7** | an optional timer for periodic |
| | policies, in milliseconds (a |