docs/apex/APEX-Install-Guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4
   5 APEX Installation Guide
   6 ***********************
   7
   8 .. contents::
   9     :depth: 3
  10
  11 Requirements
  12 ^^^^^^^^^^^^
  13
  14       .. container:: sectionbody
  15
  16          .. container:: paragraph
  17
  18             APEX is 100% written in Java and runs on any platform that
  19             supports a JVM, e.g. Windows, Unix, Cygwin. Some APEX
  20             applications (such as the monitoring application) come as
  21             web archives, they do require a war-capable web server
  22             installed.
  23
  24 Installation Requirements
  25 -------------------------
  26
  27             .. container:: ulist
  28
  29                -  Downloaded distribution: JAVA runtime environment
  30                   (JRE, Java 8 or later, APEX is tested with the Oracle
  31                   Java)
  32
  33                -  Building from source: JAVA development kit (JDK, Java
  34                   8 or later, APEX is tested with the Oracle Java)
  35
  36                -  A web archive capable webserver, for instance for the
  37                   monitoring application
  38
  39                   .. container:: ulist
  40
  41                      -  for instance `Apache
  42                         Tomcat <https://tomcat.apache.org/>`__
  43
  44                -  Sufficient rights to install APEX on the system
  45
  46                -  Installation tools depending on the installation
  47                   method used:
  48
  49                   .. container:: ulist
  50
  51                      -  ZIP to extract from a ZIP distribution
  52
  53                         .. container:: ulist
  54
  55                            -  Windows for instance
  56                               `7Zip <http://www.7-zip.org/>`__
  57
  58                      -  TAR and GZ to extract from that TAR.GZ
  59                         distribution
  60
  61                         .. container:: ulist
  62
  63                            -  Windows for instance
  64                               `7Zip <http://www.7-zip.org/>`__
  65
  66                      -  RPM to install from the RPM distribution
  67
  68                         .. container:: ulist
  69
  70                            -  Install: ``sudo apt-get install rpm``
  71
  72                      -  DPKG to install from the DEB distribution
  73
  74                         .. container:: ulist
  75
  76                            -  Install: ``sudo apt-get install dpkg``
  77
  78 Feature Requirements
  79 --------------------
  80
  81             .. container:: paragraph
  82
  83                APEX supports a number of features that require extra
  84                software being installed.
  85
  86             .. container:: ulist
  87
  88                -  `Apache Kafka <https://kafka.apache.org/>`__ to
  89                   connect APEX to a Kafka message bus
  90
  91                -  `Hazelcast <https://hazelcast.com/>`__ to use
  92                   distributed hash maps for context
  93
  94                -  `Infinispan <http://infinispan.org/>`__ for
  95                   distributed context and persistence
  96
  97                -  `Docker <https://www.docker.com/>`__ to run APEX
  98                   inside a Docker container
  99
 100 Build (Install from Source) Requirements
 101 ----------------------------------------
 102
 103             .. container:: paragraph
 104
 105                Installation from source requires a few development tools
 106
 107             .. container:: ulist
 108
 109                -  GIT to retrieve the source code
 110
 111                -  Java SDK, Java version 8 or later
 112
 113                -  Apache Maven 3 (the APEX build environment)
 114
 115 Get the APEX Source Code
 116 ^^^^^^^^^^^^^^^^^^^^^^^^
 117
 118       .. container:: sectionbody
 119
 120          .. container:: paragraph
 121
 122             The first APEX source code was hosted on Github in January
 123             2018. By the end of 2018, APEX was added as a project in the
 124             ONAP Policy Framework, released later in the ONAP Casablanca
 125             release.
 126
 127          .. container:: paragraph
 128
 129             The APEX source code is hosted in ONAP as project APEX. The
 130             current stable version is in the master branch. Simply clone
 131             the master branch from ONAP using HTTPS.
 132
 133          .. container:: listingblock
 134
 135             .. container:: content
 136
 137                .. code:: bash
 138                   :number-lines:
 139
 140                   git clone https://gerrit.onap.org/r/policy/apex-pdp
 141
 142 Build APEX
 143 ^^^^^^^^^^
 144
 145    .. container:: sectionbody
 146
 147       .. container:: paragraph
 148
 149          The examples in this document assume that the APEX source
 150          repositories are cloned to:
 151
 152       .. container:: ulist
 153
 154          -  Unix, Cygwin: ``/usr/local/src/apex-pdp``
 155
 156          -  Windows: ``C:\dev\apex-pdp``
 157
 158          -  Cygwin: ``/cygdrive/c/dev/apex-pdp``
 159
 160       .. important::
 161          A Build requires ONAP Nexus
 162          APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current
 163          settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__.
 164
 165       .. important::
 166          A Build needs Space
 167          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
 168          the downloaded dependencies
 169
 170       .. important::
 171          A Build requires Internet (for first build)
 172          During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven
 173          repository. The first standard build (and any first specific build) requires Internet access to download those dependencies.
 174
 175       .. important::
 176          Building RPM distributions
 177          RPM images are only built if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``,
 178          then build APEX.
 179
 180       .. container:: paragraph
 181
 182          Use Maven for a standard build without any tests.
 183
 184       +-------------------------------------------------------+--------------------------------------------------------+
 185       | Unix, Cygwin                                          | Windows                                                |
 186       +=======================================================+========================================================+
 187       | .. container::                                        | .. container::                                         |
 188       |                                                       |                                                        |
 189       |    .. container:: content                             |    .. container:: content                              |
 190       |                                                       |                                                        |
 191       |       .. code:: bash                                  |       .. code:: bash                                   |
 192       |         :number-lines:                                |         :number-lines:                                 |
 193       |                                                       |                                                        |
 194       |         >c:                                           |         # cd /usr/local/src/apex-pdp                   |
 195       |         >cd \dev\apex                                 |         # mvn clean install -Pdocker -DskipTests       |
 196       |         >mvn clean install -Pdocker -DskipTests       |                                                        |
 197       +-------------------------------------------------------+--------------------------------------------------------+
 198
 199 .. container:: paragraph
 200
 201    The build takes 2-3 minutes on a standard development laptop. It
 202    should run through without errors, but with a lot of messages from
 203    the build process.
 204
 205 .. container:: paragraph
 206
 207    When Maven is finished with the build, the final screen should look
 208    similar to this (omitting some ``success`` lines):
 209
 210 .. container:: listingblock
 211
 212    .. container:: content
 213
 214       .. code:: bash
 215         :number-lines:
 216
 217         [INFO] tools .............................................. SUCCESS [  0.248 s]
 218         [INFO] tools-common ....................................... SUCCESS [  0.784 s]
 219         [INFO] simple-wsclient .................................... SUCCESS [  3.303 s]
 220         [INFO] model-generator .................................... SUCCESS [  0.644 s]
 221         [INFO] packages ........................................... SUCCESS [  0.336 s]
 222         [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
 223         [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
 224         [INFO] ------------------------------------------------------------------------
 225         [INFO] BUILD SUCCESS
 226         [INFO] ------------------------------------------------------------------------
 227         [INFO] Total time: 03:43 min
 228         [INFO] Finished at: 2018-09-03T11:56:01+01:00
 229         [INFO] ------------------------------------------------------------------------
 230
 231 .. container:: paragraph
 232
 233    The build will have created all artifacts required for an APEX
 234    installation. The following example show how to change to the target
 235    directory and how it should look.
 236
 237 +----------------------------------------------------------------------------------------------------------------------------+
 238 | Unix, Cygwin                                                                                                               |
 239 +============================================================================================================================+
 240 | .. container::                                                                                                             |
 241 |                                                                                                                            |
 242 |    .. container:: listingblock                                                                                             |
 243 |                                                                                                                            |
 244 |       .. container:: content                                                                                               |
 245 |                                                                                                                            |
 246 |          .. code:: bash                                                                                                    |
 247 |             :number-lines:                                                                                                 |
 248 |                                                                                                                            |
 249 |             -rwxrwx---+ 1 esvevan Domain Users       772 Sep  3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes*    |
 250 |             -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb*            |
 251 |             -rwxrwx---+ 1 esvevan Domain Users     15633 Sep  3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar*            |
 252 |             -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |
 253 |             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 archive-tmp/                                         |
 254 |             -rwxrwx---+ 1 esvevan Domain Users        89 Sep  3 11:54 checkstyle-cachefile*                                |
 255 |             -rwxrwx---+ 1 esvevan Domain Users     10621 Sep  3 11:54 checkstyle-checker.xml*                              |
 256 |             -rwxrwx---+ 1 esvevan Domain Users       584 Sep  3 11:54 checkstyle-header.txt*                               |
 257 |             -rwxrwx---+ 1 esvevan Domain Users        86 Sep  3 11:54 checkstyle-result.xml*                               |
 258 |             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 classes/                                             |
 259 |             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 dependency-maven-plugin-markers/                     |
 260 |             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 etc/                                                 |
 261 |             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 examples/                                            |
 262 |             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:55 install_hierarchy/                                   |
 263 |             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 maven-archiver/                                      |
 264 +----------------------------------------------------------------------------------------------------------------------------+
 265
 266 +--------------------------------------------------------------------------------------------------------+
 267 | Windows                                                                                                |
 268 +========================================================================================================+
 269 | .. container::                                                                                         |
 270 |                                                                                                        |
 271 |    .. container:: listingblock                                                                         |
 272 |                                                                                                        |
 273 |       .. container:: content                                                                           |
 274 |                                                                                                        |
 275 |          .. code:: bash                                                                                |
 276 |             :number-lines:                                                                             |
 277 |                                                                                                        |
 278 |                03/09/2018  11:55    <DIR>          .                                                   |
 279 |                03/09/2018  11:55    <DIR>          ..                                                  |
 280 |                03/09/2018  11:55       146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |
 281 |                03/09/2018  11:55       146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb            |
 282 |                03/09/2018  11:54            15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar            |
 283 |                03/09/2018  11:55               772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes    |
 284 |                03/09/2018  11:54    <DIR>          archive-tmp                                         |
 285 |                03/09/2018  11:54                89 checkstyle-cachefile                                |
 286 |                03/09/2018  11:54            10,621 checkstyle-checker.xml                              |
 287 |                03/09/2018  11:54               584 checkstyle-header.txt                               |
 288 |                03/09/2018  11:54                86 checkstyle-result.xml                               |
 289 |                03/09/2018  11:54    <DIR>          classes                                             |
 290 |                03/09/2018  11:54    <DIR>          dependency-maven-plugin-markers                     |
 291 |                03/09/2018  11:54    <DIR>          etc                                                 |
 292 |                03/09/2018  11:54    <DIR>          examples                                            |
 293 |                03/09/2018  11:55    <DIR>          install_hierarchy                                   |
 294 |                03/09/2018  11:54    <DIR>          maven-archiver                                      |
 295 |                               8 File(s)    292,652,686 bytes                                           |
 296 |                               9 Dir(s)  14,138,720,256 bytes free                                      |
 297 +--------------------------------------------------------------------------------------------------------+
 298
 299 Install APEX
 300 ^^^^^^^^^^^^
 301
 302       .. container:: paragraph
 303
 304          APEX can be installed in different ways:
 305
 306       .. container:: ulist
 307
 308          -  Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm``
 309             or ``.deb`` archive
 310
 311          -  Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive
 312
 313          -  Windows, Unix, Cygwin: build from source using Maven, then
 314             install manually
 315
 316 Install with RPM and DPKG
 317 -------------------------
 318
 319          .. container:: paragraph
 320
 321             The install distributions of APEX automatically install the
 322             system. The installation directory is
 323             ``/opt/app/policy/apex-pdp``. Log files are located in
 324             ``/var/log/onap/policy/apex-pdp``. The latest APEX version
 325             will be available as ``/opt/app/policy/apex-pdp/apex-pdp``.
 326
 327          .. container:: paragraph
 328
 329             For the installation, a new user ``apexuser`` and a new
 330             group ``apexuser`` will be created. This user owns the
 331             installation directories and the log file location. The user
 332             is also used by the standard APEX start scripts to run APEX
 333             with this user’s permissions.
 334
 335          +-----------------------------------------------------------------------+
 336          | RPM Installation                                                      |
 337          +=======================================================================+
 338          | .. container::                                                        |
 339          |                                                                       |
 340          |    .. container:: listingblock                                        |
 341          |                                                                       |
 342          |       .. container:: content                                          |
 343          |                                                                       |
 344          |          .. code:: bash                                               |
 345          |             :number-lines:                                            |
 346          |                                                                       |
 347          |             # sudo rpm -i apex-pdp-package-full-2.0.0-SNAPSHOT.rpm    |
 348          |             ********************preinst*******************            |
 349          |             arguments 1                                               |
 350          |             **********************************************            |
 351          |             creating group apexuser . . .                             |
 352          |             creating user apexuser . . .                              |
 353          |             ********************postinst****************              |
 354          |             arguments 1                                               |
 355          |             ***********************************************           |
 356          +-----------------------------------------------------------------------+
 357
 358 +--------------------------------------------------------------------------------------+
 359 | DPKG Installation                                                                    |
 360 +======================================================================================+
 361 | .. container::                                                                       |
 362 |                                                                                      |
 363 |    .. container:: listingblock                                                       |
 364 |                                                                                      |
 365 |       .. container:: content                                                         |
 366 |                                                                                      |
 367 |          .. code:: bash                                                              |
 368 |             :number-lines:                                                           |
 369 |                                                                                      |
 370 |             # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb                  |
 371 |             Selecting previously unselected package apex-uservice.                   |
 372 |             (Reading database ... 288458 files and directories currently installed.) |
 373 |             Preparing to unpack apex-pdp-package-full-2.0.0-SNAPSHOT.deb ...         |
 374 |             ********************preinst*******************                           |
 375 |             arguments install                                                        |
 376 |             **********************************************                           |
 377 |             creating group apexuser . . .                                            |
 378 |             creating user apexuser . . .                                             |
 379 |             Unpacking apex-uservice (2.0.0-SNAPSHOT) ...                             |
 380 |             Setting up apex-uservice (2.0.0-SNAPSHOT) ...                            |
 381 |             ********************postinst****************                             |
 382 |             arguments configure                                                      |
 383 |             ***********************************************                          |
 384 +--------------------------------------------------------------------------------------+
 385
 386 .. container:: paragraph
 387
 388    Once the installation is finished, APEX is fully installed and ready
 389    to run.
 390
 391 Install Manually from Archive (Unix, Cygwin)
 392 --------------------------------------------
 393
 394    .. container:: paragraph
 395
 396       Download a ``tar.gz`` archive. Create a directory where APEX
 397       should be installed. Extract the ``tar`` archive. The following
 398       example shows how to install APEX in ``/opt/apex`` and create a
 399       link to ``/opt/apex/apex`` for the most recent installation.
 400
 401    .. container:: listingblock
 402
 403       .. container:: content
 404
 405          .. code:: bash
 406             :number-lines:
 407
 408             # cd /opt
 409             # mkdir apex
 410             # cd apex
 411             # mkdir apex-full-2.0.0-SNAPSHOT
 412             # tar xvfz ~/Downloads/apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -C apex-full-2.0.0-SNAPSHOT
 413             # ln -s apex apex-pdp-package-full-2.0.0-SNAPSHOT
 414
 415 Install Manually from Archive (Windows, 7Zip, GUI)
 416 --------------------------------------------------
 417
 418    .. container:: paragraph
 419
 420       Download a ``tar.gz`` archive and copy the file into the install
 421       folder (in this example ``C:\apex``). Assuming you are using 7Zip,
 422       right click on the file and extract the ``tar`` archive. Note: the
 423       screenshots might show an older version than you have.
 424
 425    .. container:: imageblock
 426
 427       .. container:: content
 428
 429          |Extract the TAR archive|
 430
 431    .. container:: paragraph
 432
 433       The right-click on the new created TAR file and extract the actual
 434       APEX distribution.
 435
 436    .. container:: imageblock
 437
 438       .. container:: content
 439
 440          |Extract the APEX distribution|
 441
 442    .. container:: paragraph
 443
 444       Inside the new APEX folder you see the main directories: ``bin``,
 445       ``etc``, ``examples``, ``lib``, and ``war``
 446
 447    .. container:: paragraph
 448
 449       Once extracted, please rename the created folder to
 450       ``apex-full-2.0.0-SNAPSHOT``. This will keep the directory name in
 451       line with the rest of this documentation.
 452
 453 Install Manually from Archive (Windows, 7Zip, CMD)
 454 --------------------------------------------------
 455
 456    .. container:: paragraph
 457
 458       Download a ``tar.gz`` archive and copy the file into the install
 459       folder (in this example ``C:\apex``). Start ``cmd``, for instance
 460       typing ``Windows+R`` and then ``cmd`` in the dialog. Assuming
 461       ``7Zip`` is installed in the standard folder, simply run the
 462       following commands (for APEX version 2.0.0-SNAPSHOT full
 463       distribution)
 464
 465    .. container:: listingblock
 466
 467       .. container:: content
 468
 469          .. code:: bash
 470            :number-lines:
 471
 472             >c:
 473             >cd \apex
 474             >"\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"
 475
 476 .. container:: paragraph
 477
 478    APEX is now installed in the folder
 479    ``C:\apex\apex-full-2.0.0-SNAPSHOT``.
 480
 481 Build from Source
 482 ^^^^^^^^^^^^^^^^^
 483
 484 Build and Install Manually (Unix, Windows, Cygwin)
 485 --------------------------------------------------
 486
 487          .. container:: paragraph
 488
 489             Clone the APEX GIT repositories into a directory. Go to that
 490             directory. Use Maven to build APEX (all details on building
 491             APEX from source can be found in *APEX HowTo: Build*).
 492             Install from the created artifacts (``rpm``, ``deb``,
 493             ``tar.gz``, or copy manually).
 494
 495          .. important::
 496             Building RPM distributions
 497             RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``,
 498             then build APEX.
 499
 500          .. container:: paragraph
 501
 502             The following example shows how to build the APEX system,
 503             without tests (``-DskipTests``) to save some time. It
 504             assumes that the APEX GIT repositories are cloned to:
 505
 506          .. container:: ulist
 507
 508             -  Unix, Cygwin: ``/usr/local/src/apex``
 509
 510             -  Windows: ``C:\dev\apex``
 511
 512          +-------------------------------------------------------+--------------------------------------------------------+
 513          | Unix, Cygwin                                          | Windows                                                |
 514          +=======================================================+========================================================+
 515          | .. container::                                        | .. container::                                         |
 516          |                                                       |                                                        |
 517          |    .. container:: content                             |    .. container:: content                              |
 518          |                                                       |                                                        |
 519          |       .. code:: bash                                  |       .. code:: bash                                   |
 520          |         :number-lines:                                |         :number-lines:                                 |
 521          |                                                       |                                                        |
 522          |         >c:                                           |         # cd /usr/local/src/apex                       |
 523          |         >cd \dev\apex                                 |         # mvn clean install -Pdocker -DskipTests       |
 524          |         >mvn clean install -Pdocker -DskipTests       |                                                        |
 525          +-------------------------------------------------------+--------------------------------------------------------+
 526
 527 .. container:: paragraph
 528
 529    The build takes about 2 minutes without test and about 4-5 minutes
 530    with tests on a standard development laptop. It should run through
 531    without errors, but with a lot of messages from the build process. If
 532    built with tests (i.e. without ``-DskipTests``), there will be error
 533    messages and stack trace prints from some tests. This is normal, as
 534    long as the build finishes successfully.
 535
 536 .. container:: paragraph
 537
 538    When Maven is finished with the build, the final screen should look
 539    similar to this (omitting some ``success`` lines):
 540
 541 .. container:: listingblock
 542
 543    .. container:: content
 544
 545       .. code:: bash
 546          :number-lines:
 547
 548          [INFO] tools .............................................. SUCCESS [  0.248 s]
 549          [INFO] tools-common ....................................... SUCCESS [  0.784 s]
 550          [INFO] simple-wsclient .................................... SUCCESS [  3.303 s]
 551          [INFO] model-generator .................................... SUCCESS [  0.644 s]
 552          [INFO] packages ........................................... SUCCESS [  0.336 s]
 553          [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
 554          [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
 555          [INFO] ------------------------------------------------------------------------
 556          [INFO] BUILD SUCCESS
 557          [INFO] ------------------------------------------------------------------------
 558          [INFO] Total time: 03:43 min
 559          [INFO] Finished at: 2018-09-03T11:56:01+01:00
 560          [INFO] ------------------------------------------------------------------------
 561
 562 .. container:: paragraph
 563
 564    The build will have created all artifacts required for an APEX
 565    installation. The following example show how to change to the target
 566    directory and how it should look like.
 567
 568 +-----------------------------------------------------------------------------------------------------------------------------+
 569 | Unix, Cygwin                                                                                                                |
 570 +=============================================================================================================================+
 571 | .. container::                                                                                                              |
 572 |                                                                                                                             |
 573 |    .. container:: listingblock                                                                                              |
 574 |                                                                                                                             |
 575 |          .. code:: bash                                                                                                     |
 576 |            :number-lines:                                                                                                   |
 577 |                                                                                                                             |
 578 |            # cd packages/apex-pdp-package-full/target                                                                       |
 579 |            # ls -l                                                                                                          |
 580 |            -rwxrwx---+ 1 esvevan Domain Users       772 Sep  3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes*      |
 581 |            -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb*              |
 582 |            -rwxrwx---+ 1 esvevan Domain Users     15633 Sep  3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar*              |
 583 |            -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz*   |
 584 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 archive-tmp/                                           |
 585 |            -rwxrwx---+ 1 esvevan Domain Users        89 Sep  3 11:54 checkstyle-cachefile*                                  |
 586 |            -rwxrwx---+ 1 esvevan Domain Users     10621 Sep  3 11:54 checkstyle-checker.xml*                                |
 587 |            -rwxrwx---+ 1 esvevan Domain Users       584 Sep  3 11:54 checkstyle-header.txt*                                 |
 588 |            -rwxrwx---+ 1 esvevan Domain Users        86 Sep  3 11:54 checkstyle-result.xml*                                 |
 589 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 classes/                                               |
 590 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 dependency-maven-plugin-markers/                       |
 591 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 etc/                                                   |
 592 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 examples/                                              |
 593 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:55 install_hierarchy/                                     |
 594 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 maven-archiver/                                        |
 595 +-----------------------------------------------------------------------------------------------------------------------------+
 596
 597 +-----------------------------------------------------------------------------------------------------------------------------+
 598 | Windows                                                                                                                     |
 599 +=============================================================================================================================+
 600 | .. container::                                                                                                              |
 601 |                                                                                                                             |
 602 |    .. container:: listingblock                                                                                              |
 603 |                                                                                                                             |
 604 |          .. code:: bash                                                                                                     |
 605 |            :number-lines:                                                                                                   |
 606 |                                                                                                                             |
 607 |            >cd packages\apex-pdp-package-full\target                                                                        |
 608 |            >dir                                                                                                             |
 609 |            03/09/2018  11:55    <DIR>          .                                                                            |
 610 |            03/09/2018  11:55    <DIR>          ..                                                                           |
 611 |            03/09/2018  11:55       146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz                          |
 612 |            03/09/2018  11:55       146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb                                     |
 613 |            03/09/2018  11:54            15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar                                     |
 614 |            03/09/2018  11:55               772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes                             |
 615 |            03/09/2018  11:54    <DIR>          archive-tmp                                                                  |
 616 |            03/09/2018  11:54                89 checkstyle-cachefile                                                         |
 617 |            03/09/2018  11:54            10,621 checkstyle-checker.xml                                                       |
 618 |            03/09/2018  11:54               584 checkstyle-header.txt                                                        |
 619 |            03/09/2018  11:54                86 checkstyle-result.xml                                                        |
 620 |            03/09/2018  11:54    <DIR>          classes                                                                      |
 621 |            03/09/2018  11:54    <DIR>          dependency-maven-plugin-markers                                              |
 622 |            03/09/2018  11:54    <DIR>          etc                                                                          |
 623 |            03/09/2018  11:54    <DIR>          examples                                                                     |
 624 |            03/09/2018  11:55    <DIR>          install_hierarchy                                                            |
 625 |            03/09/2018  11:54    <DIR>          maven-archiver                                                               |
 626 |                           8 File(s)    292,652,686 bytes                                                                    |
 627 |                           9 Dir(s)  14,138,720,256 bytes free                                                               |
 628 +-----------------------------------------------------------------------------------------------------------------------------+
 629
 630 .. container:: paragraph
 631
 632    Now, take the ``.deb`` or the ``.tar.gz`` file and install APEX.
 633    Alternatively, copy the content of the folder ``install_hierarchy``
 634    to your APEX directory.
 635
 636 Installation Layout
 637 ^^^^^^^^^^^^^^^^^^^
 638
 639       .. container:: paragraph
 640
 641          A full installation of APEX comes with the following layout.
 642
 643       .. container:: listingblock
 644
 645          .. container:: content
 646
 647             ::
 648
 649                $APEX_HOME
 650                    ├───bin             (1)
 651                    ├───etc             (2)
 652                    │   ├───editor
 653                    │   ├───hazelcast
 654                    │   ├───infinispan
 655                    │   └───META-INF
 656                    ├───examples            (3)
 657                    │   ├───config          (4)
 658                    │   ├───docker          (5)
 659                    │   ├───events          (6)
 660                    │   ├───html            (7)
 661                    │   ├───models          (8)
 662                    │   └───scripts         (9)
 663                    ├───lib             (10)
 664                    │   └───applications        (11)
 665                    └───war             (12)
 666
 667       .. container:: colist arabic
 668
 669          +-----------------------------------+-----------------------------------+
 670          | **1**                             | binaries, mainly scripts (bash    |
 671          |                                   | and bat) to start the APEX engine |
 672          |                                   | and applications                  |
 673          +-----------------------------------+-----------------------------------+
 674          | **2**                             | configuration files, such as      |
 675          |                                   | logback (logging) and third party |
 676          |                                   | library configurations            |
 677          +-----------------------------------+-----------------------------------+
 678          | **3**                             | example policy models to get      |
 679          |                                   | started                           |
 680          +-----------------------------------+-----------------------------------+
 681          | **4**                             | configurations for the examples   |
 682          |                                   | (with sub directories for         |
 683          |                                   | individual examples)              |
 684          +-----------------------------------+-----------------------------------+
 685          | **5**                             | Docker files and additional       |
 686          |                                   | Docker instructions for the       |
 687          |                                   | exampples                         |
 688          +-----------------------------------+-----------------------------------+
 689          | **6**                             | example events for the examples   |
 690          |                                   | (with sub directories for         |
 691          |                                   | individual examples)              |
 692          +-----------------------------------+-----------------------------------+
 693          | **7**                             | HTML files for some examples,     |
 694          |                                   | e.g. the Decisionmaker example    |
 695          +-----------------------------------+-----------------------------------+
 696          | **8**                             | the policy models, generated for  |
 697          |                                   | each example (with sub            |
 698          |                                   | directories for individual        |
 699          |                                   | examples)                         |
 700          +-----------------------------------+-----------------------------------+
 701          | **9**                             | additional scripts for the        |
 702          |                                   | examples (with sub directories    |
 703          |                                   | for individual examples)          |
 704          +-----------------------------------+-----------------------------------+
 705          | **10**                            | the library folder with all Java  |
 706          |                                   | JAR files                         |
 707          +-----------------------------------+-----------------------------------+
 708          | **11**                            | applications, also known as jar   |
 709          |                                   | with dependencies (or fat jars),  |
 710          |                                   | individually deployable           |
 711          +-----------------------------------+-----------------------------------+
 712          | **12**                            | WAR files for web applications    |
 713          +-----------------------------------+-----------------------------------+
 714
 715 System Configuration
 716 ^^^^^^^^^^^^^^^^^^^^
 717
 718       .. container:: paragraph
 719
 720          Once APEX is installed, a few configurations need to be done:
 721
 722       .. container:: ulist
 723
 724          -  Create an APEX user and an APEX group (optional, if not
 725             installed using RPM and DPKG)
 726
 727          -  Create environment settings for ``APEX_HOME`` and
 728             ``APEX_USER``, required by the start scripts
 729
 730          -  Change settings of the logging framework (optional)
 731
 732          -  Create directories for logging, required (execution might
 733             fail if directories do not exist or cannot be created)
 734
 735 APEX User and Group
 736 -------------------
 737
 738          .. container:: paragraph
 739
 740             On smaller installations and test systems, APEX can run as
 741             any user or group.
 742
 743          .. container:: paragraph
 744
 745             However, if APEX is installed in production, we strongly
 746             recommend you set up a dedicated user for running APEX. This
 747             will isolate the execution of APEX to that user. We
 748             recommend you use the userid ``apexuser`` but you may use
 749             any user you choose.
 750
 751          .. container:: paragraph
 752
 753             The following example, for UNIX, creates a group called
 754             ``apexuser``, an APEX user called ``apexuser``, adds the
 755             group to the user, and changes ownership of the APEX
 756             installation to the user. Substitute ``<apex-dir>`` with the
 757             directory where APEX is installed.
 758
 759          .. container:: listingblock
 760
 761             .. container:: content
 762
 763                .. code:: bash
 764                   :number-lines:
 765
 766                   # sudo groupadd apexuser
 767                   # sudo useradd -g apexuser apexuser
 768                   # sudo chown -R apexuser:apexuser <apex-dir>
 769
 770 .. container:: paragraph
 771
 772    For other operating systems please consult your manual or system
 773    administrator.
 774
 775 Environment Settings: APEX_HOME and APEX_USER
 776 ---------------------------------------------
 777
 778    .. container:: paragraph
 779
 780       The provided start scripts for APEX require two environment
 781       variables being set:
 782
 783    .. container:: ulist
 784
 785       -  ``APEX_USER`` with the user under whose name and permission APEX
 786          should be started (Unix only)
 787
 788       -  ``APEX_HOME`` with the directory where APEX is installed (Unix,
 789          Windows, Cygwin)
 790
 791    .. container:: paragraph
 792
 793       The first row in the following table shows how to set these
 794       environment variables temporarily (assuming the user is
 795       ``apexuser``). The second row shows how to verify the settings.
 796       The last row explains how to set those variables permanently.
 797
 798    +------------------------------------------------+---------------------------------------------------------+
 799    | Unix, Cygwin (bash/tcsh)                       | Windows                                                 |
 800    +================================================+=========================================================+
 801    | .. container::                                 | .. container::                                          |
 802    |                                                |                                                         |
 803    |    .. container:: content                      |    .. container:: content                               |
 804    |                                                |                                                         |
 805    |       .. code:: bash                           |       .. code:: bash                                    |
 806    |          :number-lines:                        |         :number-lines:                                  |
 807    |                                                |                                                         |
 808    |          # export APEX_USER=apexuser           |         >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT |
 809    |          # cd /opt/app/policy/apex-pdp         |                                                         |
 810    |          # export APEX_HOME=`pwd`              |                                                         |
 811    |                                                |                                                         |
 812    +------------------------------------------------+                                                         |
 813    | .. container::                                 |                                                         |
 814    |                                                |                                                         |
 815    |    .. container:: content                      |                                                         |
 816    |                                                |                                                         |
 817    |       .. code:: tcsh                           |                                                         |
 818    |          :number-lines:                        |                                                         |
 819    |                                                |                                                         |
 820    |          # setenv APEX_USER apexuser           |                                                         |
 821    |          # cd /opt/app/policy/apex-pdp         |                                                         |
 822    |          # setenv APEX_HOME `pwd`              |                                                         |
 823    |                                                |                                                         |
 824    +------------------------------------------------+---------------------------------------------------------+
 825    | .. container::                                 | .. container::                                          |
 826    |                                                |                                                         |
 827    |    .. container:: content                      |    .. container:: content                               |
 828    |                                                |                                                         |
 829    |       .. code:: bash                           |       .. code:: bash                                    |
 830    |          :number-lines:                        |          :number-lines:                                 |
 831    |                                                |                                                         |
 832    |          # env | grep APEX                     |          >set APEX_HOME                                 |
 833    |          # APEX_USER=apexuser                  |          APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT       |
 834    |          # APEX_HOME=/opt/app/policy/apex-pdp  |                                                         |
 835    |                                                |                                                         |
 836    +------------------------------------------------+---------------------------------------------------------+
 837
 838
 839 Making Environment Settings Permanent (Unix, Cygwin)
 840 ####################################################
 841
 842    .. container:: paragraph
 843
 844       For a per-user setting, edit the user’s ``bash`` or ``tcsh``
 845       settings in ``~/.bashrc`` or ``~/.tcshrc``. For system-wide
 846       settings, edit ``/etc/profiles`` (requires permissions).
 847
 848
 849 Making Environment Settings Permanent (Windows)
 850 ###############################################
 851
 852    .. container:: paragraph
 853
 854       On Windows 7 do
 855
 856    .. container:: ulist
 857
 858       -  Click on the **Start** Menu
 859
 860       -  Right click on **Computer**
 861
 862       -  Select **Properties**
 863
 864    .. container:: paragraph
 865
 866       On Windows 8/10 do
 867
 868    .. container:: ulist
 869
 870       -  Click on the **Start** Menu
 871
 872       -  Select **System**
 873
 874    .. container:: paragraph
 875
 876       Then do the following
 877
 878    .. container:: ulist
 879
 880       -  Select **Advanced System Settings**
 881
 882       -  On the **Advanced** tab, click the **Environment Variables**
 883          button
 884
 885       -  Edit an existing variable, or create a new System variable:
 886          'Variable name'="APEX_HOME", 'Variable
 887          value'="C:\apex\apex-full-2.0.0-SNAPSHOT"
 888
 889    .. container:: paragraph
 890
 891       For the settings to take effect, an application needs to be
 892       restarted (e.g. any open ``cmd`` window).
 893
 894 Edit the APEX Logging Settings
 895 ------------------------------
 896
 897    .. container:: paragraph
 898
 899       Configure the APEX logging settings to your requirements, for
 900       instance:
 901
 902    .. container:: ulist
 903
 904       -  change the directory where logs are written to, or
 905
 906       -  change the log levels
 907
 908    .. container:: paragraph
 909
 910       Edit the file ``$APEX_HOME/etc/logback.xml`` for any required
 911       changes. To change the log directory change the line
 912
 913    .. container:: paragraph
 914
 915       ``<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />``
 916
 917    .. container:: paragraph
 918
 919       to
 920
 921    .. container:: paragraph
 922
 923       ``<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />``
 924
 925    .. container:: paragraph
 926
 927       On Windows, it is recommended to change the log directory to:
 928
 929    .. container:: paragraph
 930
 931       ``<property name="VAR_LOG" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``
 932
 933    .. container:: paragraph
 934
 935       Note: Be careful about when to use ``\`` vs. ``/`` as the path
 936       separator!
 937
 938 Create Directories for Logging
 939 ------------------------------
 940
 941    .. container:: paragraph
 942
 943       Make sure that the log directory exists. This is important when
 944       APEX is installed manually or when the log directory is changed
 945       in the settings (see above).
 946
 947    +------------------------------------------------------------------+-------------------------------------------------------+
 948    | Unix, Cygwin                                                     | Windows                                               |
 949    +==================================================================+=======================================================+
 950    | .. container::                                                   | .. container::                                        |
 951    |                                                                  |                                                       |
 952    |    .. container:: content                                        |    .. container:: content                             |
 953    |                                                                  |                                                       |
 954    |       .. code:: bash                                             |       .. code:: bash                                  |
 955    |         :number-lines:                                           |         :number-lines:                                |
 956    |                                                                  |                                                       |
 957    |         mkdir -p /var/log/onap/policy/apex-pdp                   |         >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs  |
 958    |         chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp |                                                       |
 959    +------------------------------------------------------------------+-------------------------------------------------------+
 960
 961 Verify the APEX Installation
 962 ############################
 963
 964    .. container:: sectionbody
 965
 966       .. container:: paragraph
 967
 968          When APEX is installed and all settings are realized, the
 969          installation can be verified.
 970
 971 Verify Installation - run Engine
 972 --------------------------------
 973
 974          .. container:: paragraph
 975
 976             A simple verification of an APEX installation can be done by
 977             simply starting the APEX engine without any configuration.
 978             On Unix (or Cygwin) start the engine using
 979             ``$APEX_HOME/bin/apexEngine.sh``. On Windows start the
 980             engine using ``%APEX_HOME%\bin\apexEngine.bat``. The engine
 981             will fail to fully start. However, if the output looks
 982             similar to the following line, the APEX installation is
 983             realized.
 984
 985          .. container:: listingblock
 986
 987             .. container:: content
 988
 989                .. code:: bash
 990                   :number-lines:
 991
 992                   Starting Apex service with parameters [] . . .
 993                   start of Apex service failed: Apex configuration file was not specified as an argument
 994                   2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed
 995                   org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument
 996                           at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267)
 997                           at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161)
 998                           at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68)
 999                           at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165)
1000                   usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
1001                   options
1002                   -c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file
1003                                                 containing the Apex configuration parameters
1004                   -h,--help                     outputs the usage of this command
1005                   -m,--model-file <MODEL_FILE>  the full path to the model file to use, if set it overrides the model file set in the
1006                                                 configuration file
1007                   -v,--version                  outputs the version of Apex
1008
1009 Verify Installation - run an Example
1010 ------------------------------------
1011
1012    .. container:: paragraph
1013
1014       A full APEX installation comes with several examples. Here, we can
1015       fully verify the installation by running one of the examples.
1016
1017    .. container:: paragraph
1018
1019       We use the example called *SampleDomain* and configure the engine
1020       to use standard in and standard out for events. Run the engine
1021       with the provided configuration. Note: Cygwin executes scripts as
1022       Unix scripts but runs Java as a Windows application, thus the
1023       configuration file must be given as a Windows path.
1024
1025    .. container:: listingblock
1026
1027       .. container:: content
1028
1029          .. code:: bash
1030              :number-lines:
1031
1032              # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1)
1033              # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2)
1034              >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3)
1035
1036 .. container:: colist arabic
1037
1038    +-------+---------+
1039    | **1** | UNIX    |
1040    +-------+---------+
1041    | **2** | Cygwin  |
1042    +-------+---------+
1043    | **3** | Windows |
1044    +-------+---------+
1045
1046 .. container:: paragraph
1047
1048    The engine should start successfully. Assuming the logging levels are
1049    not changed (default level is ``info``), the output should look
1050    similar to this (last few lines)
1051
1052 .. container:: listingblock
1053
1054    .. container:: content
1055
1056       .. code:: bash
1057          :number-lines:
1058
1059          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] . . .
1060          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 .
1061          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 .
1062          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 .
1063          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 .
1064          2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created.
1065          2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . .
1066          2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started
1067          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
1068          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
1069          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
1070          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
1071          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
1072          Started Apex service
1073
1074 .. container:: paragraph
1075
1076    Important are the last two lines, stating that APEX has added the
1077    final action listener to the engine and that the engine is started.
1078
1079 .. container:: paragraph
1080
1081    The engine is configured to read events from standard input and write
1082    produced events to standard output. The policy model is a very simple
1083    policy.
1084
1085 .. container:: paragraph
1086
1087    The following table shows an input event in the left column and an
1088    output event in the right column. Paste the input event into the
1089    console where APEX is running, and the output event should appear in
1090    the console. Pasting the input event multiple times will produce
1091    output events with different values.
1092
1093 +-------------------------------------------------------------+-------------------------------------------------------------+
1094 | Input Event                                                 | Example Output Event                                        |
1095 +=============================================================+=============================================================+
1096 | .. container::                                              | .. container::                                              |
1097 |                                                             |                                                             |
1098 |    .. container:: content                                   |    .. container:: content                                   |
1099 |                                                             |                                                             |
1100 |       .. code:: bash                                        |       .. code:: bash                                        |
1101 |         :number-lines:                                      |         :number-lines:                                      |
1102 |                                                             |                                                             |
1103 |         {                                                   |         {                                                   |
1104 |          "nameSpace": "org.onap.policy.apex.sample.events", |          "name": "Event0004",                               |
1105 |          "name": "Event0000",                               |          "version": "0.0.1",                                |
1106 |          "version": "0.0.1",                                |          "nameSpace": "org.onap.policy.apex.sample.events", |
1107 |          "source": "test",                                  |          "source": "Act",                                   |
1108 |          "target": "apex",                                  |          "target": "Outside",                               |
1109 |          "TestSlogan": "Test slogan for External Event0",   |          "TestActCaseSelected": 2,                          |
1110 |          "TestMatchCase": 0,                                |          "TestActStateTime": 1536157104627,                 |
1111 |          "TestTimestamp": 1469781869269,                    |          "TestDecideCaseSelected": 0,                       |
1112 |          "TestTemperature": 9080.866                        |          "TestDecideStateTime": 1536157104625,              |
1113 |         }                                                   |          "TestEstablishCaseSelected": 0,                    |
1114 |                                                             |          "TestEstablishStateTime": 1536157104623,           |
1115 |                                                             |          "TestMatchCase": 0,                                |
1116 |                                                             |          "TestMatchCaseSelected": 1,                        |
1117 |                                                             |          "TestMatchStateTime": 1536157104620,               |
1118 |                                                             |          "TestSlogan": "Test slogan for External Event0",   |
1119 |                                                             |          "TestTemperature": 9080.866,                       |
1120 |                                                             |          "TestTimestamp": 1469781869269                     |
1121 |                                                             |          }                                                  |
1122 +-------------------------------------------------------------+-------------------------------------------------------------+
1123
1124 .. container:: paragraph
1125
1126    Terminate APEX by simply using ``CTRL+C`` in the console.
1127
1128 Verify a Full Installation - REST Editor
1129 ----------------------------------------
1130
1131    .. container:: paragraph
1132
1133       APEX has a REST application for viewing policy models. The
1134       application can also be used to create new policy models close to
1135       the engine native policy language. Start the REST editor as
1136       follows.
1137
1138    .. container:: listingblock
1139
1140       .. container:: content
1141
1142          .. code:: bash
1143             :number-lines:
1144
1145             # $APEX_HOME/bin/apexApps.sh rest-editor
1146
1147 .. container:: listingblock
1148
1149    .. container:: content
1150
1151       .. code:: bash
1152             :number-lines:
1153
1154             >%APEX_HOME%\bin\apexApps.bat rest-editor
1155
1156 .. container:: paragraph
1157
1158    The script will start a simple web server
1159    (`Grizzly <https://javaee.github.io/grizzly/>`__) and deploy a
1160    ``war`` web archive in it. Once the editor is started, it will be
1161    available on ``localhost:18989``. The last few line of the messages
1162    should be:
1163
1164 .. container:: listingblock
1165
1166    .. container:: content
1167
1168       .. code:: bash
1169          :number-lines:
1170
1171          Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
1172          Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start
1173          INFO: Started listener bound to [localhost:18989]
1174          Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start
1175          INFO: [HttpServer] Started.
1176          Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
1177
1178 .. container:: paragraph
1179
1180    Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and
1181    use the URL ``http://localhost:18989/``. This will connect the
1182    browser to the started REST editor. The start screen should be as
1183    follows.
1184
1185 .. container:: imageblock
1186
1187    .. container:: content
1188
1189       |REST Editor Start Screen|
1190
1191    .. container:: title
1192
1193       Figure 1. REST Editor Start Screen
1194
1195 .. container:: paragraph
1196
1197    Now load a policy model by clicking the menu ``File`` and then
1198    ``Open``. In the opened dialog, go to the directory where APEX is
1199    installed, then ``examples``, ``models``, ``SampleDomain``, and there
1200    select the file ``SamplePolicyModelJAVA.json``. This will load the
1201    policy model used to verify the policy engine (see above). Once
1202    loaded, the screen should look as follows.
1203
1204 .. container:: imageblock
1205
1206    .. container:: content
1207
1208       |REST Editor with loaded SampleDomain Policy Model|
1209
1210    .. container:: title
1211
1212       Figure 2. REST Editor with loaded SampleDomain Policy Model
1213
1214 .. container:: paragraph
1215
1216    Now you can use the REST editor. To finish this verification, simply
1217    terminate your browser (or the tab), and then use ``CTRL+C`` in the
1218    console where you started the REST editor.
1219
1220 Installing WAR Applications
1221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1222
1223    .. container:: sectionbody
1224
1225       .. container:: paragraph
1226
1227          APEX comes with a set of WAR files. These are complete
1228          applications that can be installed and run in an application
1229          server. All of these applications are realized as servlets. You
1230          can find the WAR applications in ``$APEX_HOME/war`` (UNIX,
1231          Cygwin) or ``%APEX_HOME%\war`` (Windows).
1232
1233       .. container:: paragraph
1234
1235          Installing and using the WAR applications requires a web server
1236          that can execute ``war`` web archives. We recommend using
1237          `Apache Tomcat <https://tomcat.apache.org/>`__, however other
1238          web servers can be used as well.
1239
1240       .. container:: paragraph
1241
1242          Install Apache Tomcat including the ``Manager App``, see `V9.0
1243          Docs <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access>`__
1244          for details. Start the Tomcat service, or make sure that Tomcat
1245          is running.
1246
1247       .. container:: paragraph
1248
1249          There are multiple ways to install the APEX WAR applications:
1250
1251       .. container:: ulist
1252
1253          -  copy the ``.war`` file into the Tomcat ``webapps`` folder
1254
1255          -  use the Tomcat ``Manager App`` to deploy via the web
1256             interface
1257
1258          -  deploy using a REST call to Tomcat
1259
1260       .. container:: paragraph
1261
1262          For details on how to install ``war`` files please consult the
1263          `Tomcat
1264          Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__
1265          or the `Manager App
1266          HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html>`__.
1267          Once you have installed an APEX WAR application (and wait for
1268          sufficient time for Tomcat to finalize the installation), open
1269          the ``Manager App`` in Tomcat. You should see the APEX WAR
1270          application being installed and running.
1271
1272       .. container:: paragraph
1273
1274          In case of errors, examine the log files in the Tomcat log
1275          directory. In a conventional install, those log files are in
1276          the logs directory where Tomcat is installed.
1277
1278       .. container:: paragraph
1279
1280          The current APEX version provides the following WAR
1281          applications:
1282
1283       .. container:: ulist
1284
1285          -  client-deployment-2.0.0-SNAPSHOT.war - a client to deploy
1286             new policy models to a running engine
1287
1288          -  client-editor-2.0.0-SNAPSHOT.war - the standard policy REST
1289             editor GUI
1290
1291          -  client-monitoring-2.0.0-SNAPSHOT.war - a client for
1292             monitoring a running APEX engine
1293
1294          -  client-full-2.0.0-SNAPSHOT.war - a full client with a
1295             one-stop-access to deployment, monitoring, and REST editor
1296
1297          -  examples-servlet-2.0.0-SNAPSHOT.war - an example APEX
1298             servlet
1299
1300 Running APEX in Docker
1301 ^^^^^^^^^^^^^^^^^^^^^^
1302
1303    .. container:: sectionbody
1304
1305       .. container:: paragraph
1306
1307          Since APEX is in ONAP, we provide a full virtualization
1308          environment for the engine.
1309
1310 Run in ONAP
1311 -----------
1312
1313          .. container:: paragraph
1314
1315             Running APEX from the ONAP docker repository only requires 2
1316             commands:
1317
1318          .. container:: olist arabic
1319
1320             #. Log into the ONAP docker repo
1321
1322          .. container:: listingblock
1323
1324             .. container:: content
1325
1326                ::
1327
1328                   docker login -u docker -p docker nexus3.onap.org:10003
1329
1330          .. container:: olist arabic
1331
1332             #. Run the APEX docker image
1333
1334          .. container:: listingblock
1335
1336             .. container:: content
1337
1338                ::
1339
1340                   docker run -it --rm  nexus3.onap.org:10003/onap/policy-apex-pdp:latest
1341
1342
1343 Build a Docker Image
1344 --------------------
1345
1346          .. container:: paragraph
1347
1348             Alternatively, one can use the Dockerfile defined in the
1349             Docker package to build an image.
1350
1351          .. container:: listingblock
1352
1353             .. container:: title
1354
1355                APEX Dockerfile
1356
1357             .. container:: content
1358
1359                .. code:: bash
1360                   :number-lines:
1361
1362                   #
1363                   # Docker file to build an image that runs APEX on Java 8 in Ubuntu
1364                   #
1365                   FROM ubuntu:16.04
1366
1367                   RUN apt-get update && \
1368                           apt-get upgrade -y && \
1369                           apt-get install -y software-properties-common && \
1370                           add-apt-repository ppa:openjdk-r/ppa -y && \
1371                           apt-get update && \
1372                           apt-get install -y openjdk-8-jdk
1373
1374                   # Create apex user and group
1375                   RUN groupadd apexuser
1376                   RUN useradd --create-home -g apexuser apexuser
1377
1378                   # Add Apex-specific directories and set ownership as the Apex admin user
1379                   RUN mkdir -p /opt/app/policy/apex-pdp
1380                   RUN mkdir -p /var/log/onap/policy/apex-pdp
1381                   RUN chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp
1382
1383                   # Unpack the tarball
1384                   RUN mkdir /packages
1385                   COPY apex-pdp-package-full.tar.gz /packages
1386                   RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory /opt/app/policy/apex-pdp
1387                   RUN rm /packages/apex-pdp-package-full.tar.gz
1388
1389                   # Ensure everything has the correct permissions
1390                   RUN find /opt/app -type d -perm 755
1391                   RUN find /opt/app -type f -perm 644
1392                   RUN chmod a+x /opt/app/policy/apex-pdp/bin/*
1393
1394                   # Copy examples to Apex user area
1395                   RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser
1396
1397                   RUN apt-get clean
1398
1399                   RUN chown -R apexuser:apexuser /home/apexuser/*
1400
1401                   USER apexuser
1402                   ENV PATH /opt/app/policy/apex-pdp/bin:$PATH
1403                   WORKDIR /home/apexuser
1404
1405 .. container::
1406    :name: footer
1407
1408    .. container::
1409       :name: footer-text
1410
1411       2.0.0-SNAPSHOT
1412       Last updated 2018-09-10 15:38:16 IST
1413
1414 .. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png
1415 .. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png
1416 .. |REST Editor Start Screen| image:: images/install-guide/rest-start.png
1417 .. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png
1418