1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
5 APEX Installation Guide
6 ***********************
14 .. container:: sectionbody
16 .. container:: paragraph
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
24 Installation Requirements
25 -------------------------
29 - Downloaded distribution: JAVA runtime environment
30 (JRE, Java 8 or later, APEX is tested with the Oracle
33 - Building from source: JAVA development kit (JDK, Java
34 8 or later, APEX is tested with the Oracle Java)
36 - A web archive capable webserver, for instance for the
37 monitoring application
41 - for instance `Apache
42 Tomcat <https://tomcat.apache.org/>`__
44 - Sufficient rights to install APEX on the system
46 - Installation tools depending on the installation
51 - ZIP to extract from a ZIP distribution
55 - Windows for instance
56 `7Zip <http://www.7-zip.org/>`__
58 - TAR and GZ to extract from that TAR.GZ
63 - Windows for instance
64 `7Zip <http://www.7-zip.org/>`__
66 - RPM to install from the RPM distribution
70 - Install: ``sudo apt-get install rpm``
72 - DPKG to install from the DEB distribution
76 - Install: ``sudo apt-get install dpkg``
81 .. container:: paragraph
83 APEX supports a number of features that require extra
84 software being installed.
88 - `Apache Kafka <https://kafka.apache.org/>`__ to
89 connect APEX to a Kafka message bus
91 - `Hazelcast <https://hazelcast.com/>`__ to use
92 distributed hash maps for context
94 - `Infinispan <http://infinispan.org/>`__ for
95 distributed context and persistence
97 - `Docker <https://www.docker.com/>`__ to run APEX
98 inside a Docker container
100 Build (Install from Source) Requirements
101 ----------------------------------------
103 .. container:: paragraph
105 Installation from source requires a few development tools
109 - GIT to retrieve the source code
111 - Java SDK, Java version 8 or later
113 - Apache Maven 3 (the APEX build environment)
115 Get the APEX Source Code
116 ^^^^^^^^^^^^^^^^^^^^^^^^
118 .. container:: sectionbody
120 .. container:: paragraph
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
127 .. container:: paragraph
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.
133 .. container:: listingblock
135 .. container:: content
140 git clone https://gerrit.onap.org/r/policy/apex-pdp
145 .. container:: sectionbody
147 .. container:: paragraph
149 The examples in this document assume that the APEX source
150 repositories are cloned to:
154 - Unix, Cygwin: ``/usr/local/src/apex-pdp``
156 - Windows: ``C:\dev\apex-pdp``
158 - Cygwin: ``/cygdrive/c/dev/apex-pdp``
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>`__.
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
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.
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``,
180 .. container:: paragraph
182 Use Maven for a standard build without any tests.
184 +-------------------------------------------------------+--------------------------------------------------------+
185 | Unix, Cygwin | Windows |
186 +=======================================================+========================================================+
187 | .. container:: | .. container:: |
189 | .. container:: content | .. container:: content |
191 | .. code:: bash | .. code:: bash |
192 | :number-lines: | :number-lines: |
194 | >c: | # cd /usr/local/src/apex-pdp |
195 | >cd \dev\apex | # mvn clean install -Pdocker -DskipTests |
196 | >mvn clean install -Pdocker -DskipTests | |
197 +-------------------------------------------------------+--------------------------------------------------------+
199 .. container:: paragraph
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
205 .. container:: paragraph
207 When Maven is finished with the build, the final screen should look
208 similar to this (omitting some ``success`` lines):
210 .. container:: listingblock
212 .. container:: content
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] ------------------------------------------------------------------------
226 [INFO] ------------------------------------------------------------------------
227 [INFO] Total time: 03:43 min
228 [INFO] Finished at: 2018-09-03T11:56:01+01:00
229 [INFO] ------------------------------------------------------------------------
231 .. container:: paragraph
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.
237 +----------------------------------------------------------------------------------------------------------------------------+
239 +============================================================================================================================+
242 | .. container:: listingblock |
244 | .. container:: content |
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 +----------------------------------------------------------------------------------------------------------------------------+
266 +--------------------------------------------------------------------------------------------------------+
268 +========================================================================================================+
271 | .. container:: listingblock |
273 | .. container:: content |
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 +--------------------------------------------------------------------------------------------------------+
302 .. container:: paragraph
304 APEX can be installed in different ways:
308 - Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm``
311 - Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive
313 - Windows, Unix, Cygwin: build from source using Maven, then
316 Install with RPM and DPKG
317 -------------------------
319 .. container:: paragraph
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``.
327 .. container:: paragraph
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.
335 +-----------------------------------------------------------------------+
337 +=======================================================================+
340 | .. container:: listingblock |
342 | .. container:: content |
347 | # sudo rpm -i apex-pdp-package-full-2.0.0-SNAPSHOT.rpm |
348 | ********************preinst******************* |
350 | ********************************************** |
351 | creating group apexuser . . . |
352 | creating user apexuser . . . |
353 | ********************postinst**************** |
355 | *********************************************** |
356 +-----------------------------------------------------------------------+
358 +--------------------------------------------------------------------------------------+
359 | DPKG Installation |
360 +======================================================================================+
363 | .. container:: listingblock |
365 | .. container:: content |
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 +--------------------------------------------------------------------------------------+
386 .. container:: paragraph
388 Once the installation is finished, APEX is fully installed and ready
391 Install Manually from Archive (Unix, Cygwin)
392 --------------------------------------------
394 .. container:: paragraph
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.
401 .. container:: listingblock
403 .. container:: content
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
415 Install Manually from Archive (Windows, 7Zip, GUI)
416 --------------------------------------------------
418 .. container:: paragraph
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.
425 .. container:: imageblock
427 .. container:: content
429 |Extract the TAR archive|
431 .. container:: paragraph
433 The right-click on the new created TAR file and extract the actual
436 .. container:: imageblock
438 .. container:: content
440 |Extract the APEX distribution|
442 .. container:: paragraph
444 Inside the new APEX folder you see the main directories: ``bin``,
445 ``etc``, ``examples``, ``lib``, and ``war``
447 .. container:: paragraph
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.
453 Install Manually from Archive (Windows, 7Zip, CMD)
454 --------------------------------------------------
456 .. container:: paragraph
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
465 .. container:: listingblock
467 .. container:: content
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"
476 .. container:: paragraph
478 APEX is now installed in the folder
479 ``C:\apex\apex-full-2.0.0-SNAPSHOT``.
484 Build and Install Manually (Unix, Windows, Cygwin)
485 --------------------------------------------------
487 .. container:: paragraph
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).
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``,
500 .. container:: paragraph
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:
508 - Unix, Cygwin: ``/usr/local/src/apex``
510 - Windows: ``C:\dev\apex``
512 +-------------------------------------------------------+--------------------------------------------------------+
513 | Unix, Cygwin | Windows |
514 +=======================================================+========================================================+
515 | .. container:: | .. container:: |
517 | .. container:: content | .. container:: content |
519 | .. code:: bash | .. code:: bash |
520 | :number-lines: | :number-lines: |
522 | >c: | # cd /usr/local/src/apex |
523 | >cd \dev\apex | # mvn clean install -Pdocker -DskipTests |
524 | >mvn clean install -Pdocker -DskipTests | |
525 +-------------------------------------------------------+--------------------------------------------------------+
527 .. container:: paragraph
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.
536 .. container:: paragraph
538 When Maven is finished with the build, the final screen should look
539 similar to this (omitting some ``success`` lines):
541 .. container:: listingblock
543 .. container:: content
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] ------------------------------------------------------------------------
557 [INFO] ------------------------------------------------------------------------
558 [INFO] Total time: 03:43 min
559 [INFO] Finished at: 2018-09-03T11:56:01+01:00
560 [INFO] ------------------------------------------------------------------------
562 .. container:: paragraph
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.
568 +-----------------------------------------------------------------------------------------------------------------------------+
570 +=============================================================================================================================+
573 | .. container:: listingblock |
578 | # cd packages/apex-pdp-package-full/target |
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 +-----------------------------------------------------------------------------------------------------------------------------+
597 +-----------------------------------------------------------------------------------------------------------------------------+
599 +=============================================================================================================================+
602 | .. container:: listingblock |
607 | >cd packages\apex-pdp-package-full\target |
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 +-----------------------------------------------------------------------------------------------------------------------------+
630 .. container:: paragraph
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.
639 .. container:: paragraph
641 A full installation of APEX comes with the following layout.
643 .. container:: listingblock
645 .. container:: content
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)
664 │ └───applications (11)
667 .. container:: colist arabic
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 |
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 |
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 |
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 |
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 +-----------------------------------+-----------------------------------+
718 .. container:: paragraph
720 Once APEX is installed, a few configurations need to be done:
724 - Create an APEX user and an APEX group (optional, if not
725 installed using RPM and DPKG)
727 - Create environment settings for ``APEX_HOME`` and
728 ``APEX_USER``, required by the start scripts
730 - Change settings of the logging framework (optional)
732 - Create directories for logging, required (execution might
733 fail if directories do not exist or cannot be created)
738 .. container:: paragraph
740 On smaller installations and test systems, APEX can run as
743 .. container:: paragraph
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
751 .. container:: paragraph
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.
759 .. container:: listingblock
761 .. container:: content
766 # sudo groupadd apexuser
767 # sudo useradd -g apexuser apexuser
768 # sudo chown -R apexuser:apexuser <apex-dir>
770 .. container:: paragraph
772 For other operating systems please consult your manual or system
775 Environment Settings: APEX_HOME and APEX_USER
776 ---------------------------------------------
778 .. container:: paragraph
780 The provided start scripts for APEX require two environment
785 - ``APEX_USER`` with the user under whose name and permission APEX
786 should be started (Unix only)
788 - ``APEX_HOME`` with the directory where APEX is installed (Unix,
791 .. container:: paragraph
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.
798 +------------------------------------------------+---------------------------------------------------------+
799 | Unix, Cygwin (bash/tcsh) | Windows |
800 +================================================+=========================================================+
801 | .. container:: | .. container:: |
803 | .. container:: content | .. container:: content |
805 | .. code:: bash | .. code:: bash |
806 | :number-lines: | :number-lines: |
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` | |
812 +------------------------------------------------+ |
815 | .. container:: content | |
820 | # setenv APEX_USER apexuser | |
821 | # cd /opt/app/policy/apex-pdp | |
822 | # setenv APEX_HOME `pwd` | |
824 +------------------------------------------------+---------------------------------------------------------+
825 | .. container:: | .. container:: |
827 | .. container:: content | .. container:: content |
829 | .. code:: bash | .. code:: bash |
830 | :number-lines: | :number-lines: |
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 | |
836 +------------------------------------------------+---------------------------------------------------------+
839 Making Environment Settings Permanent (Unix, Cygwin)
840 ####################################################
842 .. container:: paragraph
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).
849 Making Environment Settings Permanent (Windows)
850 ###############################################
852 .. container:: paragraph
858 - Click on the **Start** Menu
860 - Right click on **Computer**
862 - Select **Properties**
864 .. container:: paragraph
870 - Click on the **Start** Menu
874 .. container:: paragraph
876 Then do the following
880 - Select **Advanced System Settings**
882 - On the **Advanced** tab, click the **Environment Variables**
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"
889 .. container:: paragraph
891 For the settings to take effect, an application needs to be
892 restarted (e.g. any open ``cmd`` window).
894 Edit the APEX Logging Settings
895 ------------------------------
897 .. container:: paragraph
899 Configure the APEX logging settings to your requirements, for
904 - change the directory where logs are written to, or
906 - change the log levels
908 .. container:: paragraph
910 Edit the file ``$APEX_HOME/etc/logback.xml`` for any required
911 changes. To change the log directory change the line
913 .. container:: paragraph
915 ``<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />``
917 .. container:: paragraph
921 .. container:: paragraph
923 ``<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />``
925 .. container:: paragraph
927 On Windows, it is recommended to change the log directory to:
929 .. container:: paragraph
931 ``<property name="VAR_LOG" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``
933 .. container:: paragraph
935 Note: Be careful about when to use ``\`` vs. ``/`` as the path
938 Create Directories for Logging
939 ------------------------------
941 .. container:: paragraph
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).
947 +------------------------------------------------------------------+-------------------------------------------------------+
948 | Unix, Cygwin | Windows |
949 +==================================================================+=======================================================+
950 | .. container:: | .. container:: |
952 | .. container:: content | .. container:: content |
954 | .. code:: bash | .. code:: bash |
955 | :number-lines: | :number-lines: |
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 +------------------------------------------------------------------+-------------------------------------------------------+
961 Verify the APEX Installation
962 ############################
964 .. container:: sectionbody
966 .. container:: paragraph
968 When APEX is installed and all settings are realized, the
969 installation can be verified.
971 Verify Installation - run Engine
972 --------------------------------
974 .. container:: paragraph
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
985 .. container:: listingblock
987 .. container:: content
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...]
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
1007 -v,--version outputs the version of Apex
1009 Verify Installation - run an Example
1010 ------------------------------------
1012 .. container:: paragraph
1014 A full APEX installation comes with several examples. Here, we can
1015 fully verify the installation by running one of the examples.
1017 .. container:: paragraph
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.
1025 .. container:: listingblock
1027 .. container:: content
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)
1036 .. container:: colist arabic
1046 .. container:: paragraph
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)
1052 .. container:: listingblock
1054 .. container:: content
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
1074 .. container:: paragraph
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.
1079 .. container:: paragraph
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
1085 .. container:: paragraph
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.
1093 +-------------------------------------------------------------+-------------------------------------------------------------+
1094 | Input Event | Example Output Event |
1095 +=============================================================+=============================================================+
1096 | .. container:: | .. container:: |
1098 | .. container:: content | .. container:: content |
1100 | .. code:: bash | .. code:: bash |
1101 | :number-lines: | :number-lines: |
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 |
1122 +-------------------------------------------------------------+-------------------------------------------------------------+
1124 .. container:: paragraph
1126 Terminate APEX by simply using ``CTRL+C`` in the console.
1128 Verify a Full Installation - REST Editor
1129 ----------------------------------------
1131 .. container:: paragraph
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
1138 .. container:: listingblock
1140 .. container:: content
1145 # $APEX_HOME/bin/apexApps.sh rest-editor
1147 .. container:: listingblock
1149 .. container:: content
1154 >%APEX_HOME%\bin\apexApps.bat rest-editor
1156 .. container:: paragraph
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
1164 .. container:: listingblock
1166 .. container:: content
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/
1178 .. container:: paragraph
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
1185 .. container:: imageblock
1187 .. container:: content
1189 |REST Editor Start Screen|
1191 .. container:: title
1193 Figure 1. REST Editor Start Screen
1195 .. container:: paragraph
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.
1204 .. container:: imageblock
1206 .. container:: content
1208 |REST Editor with loaded SampleDomain Policy Model|
1210 .. container:: title
1212 Figure 2. REST Editor with loaded SampleDomain Policy Model
1214 .. container:: paragraph
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.
1220 Installing WAR Applications
1221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1223 .. container:: sectionbody
1225 .. container:: paragraph
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).
1233 .. container:: paragraph
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.
1240 .. container:: paragraph
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
1247 .. container:: paragraph
1249 There are multiple ways to install the APEX WAR applications:
1251 .. container:: ulist
1253 - copy the ``.war`` file into the Tomcat ``webapps`` folder
1255 - use the Tomcat ``Manager App`` to deploy via the web
1258 - deploy using a REST call to Tomcat
1260 .. container:: paragraph
1262 For details on how to install ``war`` files please consult the
1264 Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__
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.
1272 .. container:: paragraph
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.
1278 .. container:: paragraph
1280 The current APEX version provides the following WAR
1283 .. container:: ulist
1285 - client-deployment-2.0.0-SNAPSHOT.war - a client to deploy
1286 new policy models to a running engine
1288 - client-editor-2.0.0-SNAPSHOT.war - the standard policy REST
1291 - client-monitoring-2.0.0-SNAPSHOT.war - a client for
1292 monitoring a running APEX engine
1294 - client-full-2.0.0-SNAPSHOT.war - a full client with a
1295 one-stop-access to deployment, monitoring, and REST editor
1297 - examples-servlet-2.0.0-SNAPSHOT.war - an example APEX
1300 Running APEX in Docker
1301 ^^^^^^^^^^^^^^^^^^^^^^
1303 .. container:: sectionbody
1305 .. container:: paragraph
1307 Since APEX is in ONAP, we provide a full virtualization
1308 environment for the engine.
1313 .. container:: paragraph
1315 Running APEX from the ONAP docker repository only requires 2
1318 .. container:: olist arabic
1320 #. Log into the ONAP docker repo
1322 .. container:: listingblock
1324 .. container:: content
1328 docker login -u docker -p docker nexus3.onap.org:10003
1330 .. container:: olist arabic
1332 #. Run the APEX docker image
1334 .. container:: listingblock
1336 .. container:: content
1340 docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest
1343 Build a Docker Image
1344 --------------------
1346 .. container:: paragraph
1348 Alternatively, one can use the Dockerfile defined in the
1349 Docker package to build an image.
1351 .. container:: listingblock
1353 .. container:: title
1357 .. container:: content
1363 # Docker file to build an image that runs APEX on Java 8 in Ubuntu
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 && \
1372 apt-get install -y openjdk-8-jdk
1374 # Create apex user and group
1375 RUN groupadd apexuser
1376 RUN useradd --create-home -g apexuser apexuser
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
1383 # Unpack the tarball
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
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/*
1394 # Copy examples to Apex user area
1395 RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser
1399 RUN chown -R apexuser:apexuser /home/apexuser/*
1402 ENV PATH /opt/app/policy/apex-pdp/bin:$PATH
1403 WORKDIR /home/apexuser
1412 Last updated 2018-09-10 15:38:16 IST
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