aboutsummaryrefslogtreecommitdiffstats
path: root/docs/apex/APEX-Install-Guide.rst
blob: 3ac1eb2385cd183cf507fa76d2d8b4c0863ce0f5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0


APEX Installation Guide
***********************

.. contents::
    :depth: 3

Requirements
^^^^^^^^^^^^

      .. container:: sectionbody

         .. container:: paragraph

            APEX is 100% written in Java and runs on any platform that
            supports a JVM, e.g. Windows, Unix, Cygwin. Some APEX
            applications (such as the monitoring application) come as
            web archives, they do require a war-capable web server
            installed.

Installation Requirements
-------------------------

            .. container:: ulist

               -  Downloaded distribution: JAVA runtime environment
                  (JRE, Java 8 or later, APEX is tested with the Oracle
                  Java)

               -  Building from source: JAVA development kit (JDK, Java
                  8 or later, APEX is tested with the Oracle Java)

               -  A web archive capable webserver, for instance for the
                  monitoring application

                  .. container:: ulist

                     -  for instance `Apache
                        Tomcat <https://tomcat.apache.org/>`__

               -  Sufficient rights to install APEX on the system

               -  Installation tools depending on the installation
                  method used:

                  .. container:: ulist

                     -  ZIP to extract from a ZIP distribution

                        .. container:: ulist

                           -  Windows for instance
                              `7Zip <http://www.7-zip.org/>`__

                     -  TAR and GZ to extract from that TAR.GZ
                        distribution

                        .. container:: ulist

                           -  Windows for instance
                              `7Zip <http://www.7-zip.org/>`__

                     -  RPM to install from the RPM distribution

                        .. container:: ulist

                           -  Install: ``sudo apt-get install rpm``

                     -  DPKG to install from the DEB distribution

                        .. container:: ulist

                           -  Install: ``sudo apt-get install dpkg``

Feature Requirements
--------------------

            .. container:: paragraph

               APEX supports a number of features that require extra
               software being installed.

            .. container:: ulist

               -  `Apache Kafka <https://kafka.apache.org/>`__ to
                  connect APEX to a Kafka message bus

               -  `Hazelcast <https://hazelcast.com/>`__ to use
                  distributed hash maps for context

               -  `Infinispan <http://infinispan.org/>`__ for
                  distributed context and persistence

               -  `Docker <https://www.docker.com/>`__ to run APEX
                  inside a Docker container

Build (Install from Source) Requirements
----------------------------------------

            .. container:: paragraph

               Installation from source requires a few development tools

            .. container:: ulist

               -  GIT to retrieve the source code

               -  Java SDK, Java version 8 or later

               -  Apache Maven 3 (the APEX build environment)

Get the APEX Source Code
^^^^^^^^^^^^^^^^^^^^^^^^

      .. container:: sectionbody

         .. container:: paragraph

            The first APEX source code was hosted on Github in January
            2018. By the end of 2018, APEX was added as a project in the
            ONAP Policy Framework, released later in the ONAP Casablanca
            release.

         .. container:: paragraph

            The APEX source code is hosted in ONAP as project APEX. The
            current stable version is in the master branch. Simply clone
            the master branch from ONAP using HTTPS.

         .. container:: listingblock

            .. container:: content

               .. code:: bash
                  :number-lines:

                  git clone https://gerrit.onap.org/r/policy/apex-pdp

Build APEX
^^^^^^^^^^

   .. container:: sectionbody

      .. container:: paragraph

         The examples in this document assume that the APEX source
         repositories are cloned to:

      .. container:: ulist

         -  Unix, Cygwin: ``/usr/local/src/apex-pdp``

         -  Windows: ``C:\dev\apex-pdp``

         -  Cygwin: ``/cygdrive/c/dev/apex-pdp``

      .. important::
	     A Build requires ONAP Nexus
		 APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current
		 settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__.

      .. important::
	     A Build needs Space
		 Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full distribution and 1-2 GB for
		 the downloaded dependencies

      .. important::
	     A Build requires Internet (for first build)
		 During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven
		 repository. The first standard build (and any first specific build) requires Internet access to download those dependencies.

      .. important::
	     Building RPM distributions
		 RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``, 
		 then build APEX.

      .. container:: paragraph

         Use Maven to for a standard build without any tests.

      +-------------------------------------------------------+--------------------------------------------------------+
      | Unix, Cygwin                                          | Windows                                                |
      +=======================================================+========================================================+
      | .. container::                                        | .. container::                                         |
      |                                                       |                                                        |
      |    .. container:: content                             |    .. container:: content                              |
      |                                                       |                                                        |
      |       .. code:: bash                                  |       .. code:: bash                                   |
      |         :number-lines:                                |         :number-lines:                                 |
      |                                                       |                                                        |
      |         >c:                                           |         # cd /usr/local/src/apex-pdp                   |
      |         >cd \dev\apex                                 |         # mvn clean install -DskipTest                 |
      |         >mvn clean install -DskipTests                |                                                        |
      +-------------------------------------------------------+--------------------------------------------------------+

.. container:: paragraph

   The build takes 2-3 minutes on a standard development laptop. It
   should run through without errors, but with a lot of messages from
   the build process.

.. container:: paragraph

   When Maven is finished with the build, the final screen should look
   similar to this (omitting some ``success`` lines):

.. container:: listingblock

   .. container:: content

      .. code:: bash
        :number-lines:

        [INFO] tools .............................................. SUCCESS [  0.248 s]
        [INFO] tools-common ....................................... SUCCESS [  0.784 s]
        [INFO] simple-wsclient .................................... SUCCESS [  3.303 s]
        [INFO] model-generator .................................... SUCCESS [  0.644 s]
        [INFO] packages ........................................... SUCCESS [  0.336 s]
        [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
        [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
        [INFO] ------------------------------------------------------------------------
        [INFO] BUILD SUCCESS
        [INFO] ------------------------------------------------------------------------
        [INFO] Total time: 03:43 min
        [INFO] Finished at: 2018-09-03T11:56:01+01:00
        [INFO] ------------------------------------------------------------------------

.. container:: paragraph

   The build will have created all artifacts required for an APEX
   installation. The following example show how to change to the target
   directory and how it should look like.

+----------------------------------------------------------------------------------------------------------------------------+
| Unix, Cygwin                                                                                                               |
+============================================================================================================================+
| .. container::                                                                                                             |
|                                                                                                                            |
|    .. container:: listingblock                                                                                             |
|                                                                                                                            |
|       .. container:: content                                                                                               |
|                                                                                                                            |
|          .. code:: bash                                                                                                    |
|             :number-lines:                                                                                                 |
|                                                                                                                            |
|             -rwxrwx---+ 1 esvevan Domain Users       772 Sep  3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes*    |
|             -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb*            |
|             -rwxrwx---+ 1 esvevan Domain Users     15633 Sep  3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar*            |
|             -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |
|             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 archive-tmp/                                         |
|             -rwxrwx---+ 1 esvevan Domain Users        89 Sep  3 11:54 checkstyle-cachefile*                                |
|             -rwxrwx---+ 1 esvevan Domain Users     10621 Sep  3 11:54 checkstyle-checker.xml*                              |
|             -rwxrwx---+ 1 esvevan Domain Users       584 Sep  3 11:54 checkstyle-header.txt*                               |
|             -rwxrwx---+ 1 esvevan Domain Users        86 Sep  3 11:54 checkstyle-result.xml*                               |
|             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 classes/                                             |
|             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 dependency-maven-plugin-markers/                     |
|             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 etc/                                                 |
|             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 examples/                                            |
|             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:55 install_hierarchy/                                   |
|             drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 maven-archiver/                                      |
+----------------------------------------------------------------------------------------------------------------------------+

+--------------------------------------------------------------------------------------------------------+
| Windows                                                                                                |
+========================================================================================================+
| .. container::                                                                                         |
|                                                                                                        |
|    .. container:: listingblock                                                                         |
|                                                                                                        |
|       .. container:: content                                                                           |
|                                                                                                        |
|          .. code:: bash                                                                                |
|             :number-lines:                                                                             |
|                                                                                                        |
|                03/09/2018  11:55    <DIR>          .                                                   |
|                03/09/2018  11:55    <DIR>          ..                                                  |
|                03/09/2018  11:55       146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |
|                03/09/2018  11:55       146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb            |
|                03/09/2018  11:54            15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar            |
|                03/09/2018  11:55               772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes    |
|                03/09/2018  11:54    <DIR>          archive-tmp                                         |
|                03/09/2018  11:54                89 checkstyle-cachefile                                |
|                03/09/2018  11:54            10,621 checkstyle-checker.xml                              |
|                03/09/2018  11:54               584 checkstyle-header.txt                               |
|                03/09/2018  11:54                86 checkstyle-result.xml                               |
|                03/09/2018  11:54    <DIR>          classes                                             |
|                03/09/2018  11:54    <DIR>          dependency-maven-plugin-markers                     |
|                03/09/2018  11:54    <DIR>          etc                                                 |
|                03/09/2018  11:54    <DIR>          examples                                            |
|                03/09/2018  11:55    <DIR>          install_hierarchy                                   |
|                03/09/2018  11:54    <DIR>          maven-archiver                                      |
|                               8 File(s)    292,652,686 bytes                                           |
|                               9 Dir(s)  14,138,720,256 bytes free                                      |
+--------------------------------------------------------------------------------------------------------+

Install APEX
^^^^^^^^^^^^

      .. container:: paragraph

         APEX can be installed in different ways:

      .. container:: ulist

         -  Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm``
            or ``.deb`` archive

         -  Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive

         -  Windows, Unix, Cygwin: build from source using Maven, then
            install manually

Install with RPM and DPKG
-------------------------

         .. container:: paragraph

            The install distributions of APEX automatically install the
            system. The installation directory is
            ``/opt/app/policy/apex-pdp``. Log files are located in
            ``/var/log/onap/policy/apex-pdp``. The latest APEX version
            will be available as ``/opt/app/policy/apex-pdp/apex-pdp``.

         .. container:: paragraph

            For the installation, a new user ``apexuser`` and a new
            group ``apexuser`` will be created. This user owns the
            installation directories and the log file location. The user
            is also used by the standard APEX start scripts to run APEX
            with this user’s permissions.

         +-----------------------------------------------------------------------+
         | RPM Installation                                                      |
         +=======================================================================+
         | .. container::                                                        |
         |                                                                       |
         |    .. container:: listingblock                                        |
         |                                                                       |
         |       .. container:: content                                          |
         |                                                                       |
         |          .. code:: bash                                               |
         |             :number-lines:                                            |
         |                                                                       |
         |             # sudo rpm -i apex-pdp-package-full-2.0.0-SNAPSHOT.rpm    |
         |             ********************preinst*******************            |
         |             arguments 1                                               |
         |             **********************************************            |
         |             creating group apexuser . . .                             |
         |             creating user apexuser . . .                              |
         |             ********************postinst****************              |
         |             arguments 1                                               |
         |             ***********************************************           |
         +-----------------------------------------------------------------------+

+--------------------------------------------------------------------------------------+
| DPKG Installation                                                                    |
+======================================================================================+
| .. container::                                                                       |
|                                                                                      |
|    .. container:: listingblock                                                       |
|                                                                                      |
|       .. container:: content                                                         |
|                                                                                      |
|          .. code:: bash                                                              |
|             :number-lines:                                                           | 
|                                                                                      |
|             # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb                  |            
|             Selecting previously unselected package apex-uservice.                   |
|             (Reading database ... 288458 files and directories currently installed.) |
|             Preparing to unpack apex-pdp-package-full-2.0.0-SNAPSHOT.deb ...         |
|             ********************preinst*******************                           |
|             arguments install                                                        |
|             **********************************************                           |
|             creating group apexuser . . .                                            |
|             creating user apexuser . . .                                             |
|             Unpacking apex-uservice (2.0.0-SNAPSHOT) ...                             |
|             Setting up apex-uservice (2.0.0-SNAPSHOT) ...                            |
|             ********************postinst****************                             |
|             arguments configure                                                      |
|             ***********************************************                          |
+--------------------------------------------------------------------------------------+

.. container:: paragraph

   Once the installation is finished, APEX is fully installed and ready
   to run.

Install Manually from Archive (Unix, Cygwin)
--------------------------------------------

   .. container:: paragraph

      Download a ``tar.gz`` archive. Create a directory where APEX
      should be installed. Extract the ``tar`` archive. The following
      example shows how to install APEX in ``/opt/apex`` and create a
      link to ``/opt/apex/apex`` for the most recent installation.

   .. container:: listingblock

      .. container:: content

         .. code:: bash
            :number-lines:

            # cd /opt
            # mkdir apex
            # cd apex
            # mkdir apex-full-2.0.0-SNAPSHOT
            # tar xvfz ~/Downloads/apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -C apex-full-2.0.0-SNAPSHOT
            # ln -s apex apex-pdp-package-full-2.0.0-SNAPSHOT

Install Manually from Archive (Windows, 7Zip, GUI)
--------------------------------------------------

   .. container:: paragraph

      Download a ``tar.gz`` archive and copy the file into the install
      folder (in this example ``C:\apex``). Assuming you are using 7Zip,
      right click on the file and extract the ``tar`` archive. Note: the
      screenshots might show an older version than you have.

   .. container:: imageblock

      .. container:: content

         |Extract the TAR archive|
	  
   .. container:: paragraph

      The right-click on the new created TAR file and extract the actual
      APEX distribution.

   .. container:: imageblock

      .. container:: content

         |Extract the APEX distribution|

   .. container:: paragraph

      Inside the new APEX folder you see the main directories: ``bin``,
      ``etc``, ``examples``, ``lib``, and ``war``

   .. container:: paragraph

      Once extracted, please rename the created folder to
      ``apex-full-2.0.0-SNAPSHOT``. This will keep the directory name in
      line with the rest of this documentation.

Install Manually from Archive (Windows, 7Zip, CMD)
--------------------------------------------------

   .. container:: paragraph

      Download a ``tar.gz`` archive and copy the file into the install
      folder (in this example ``C:\apex``). Start ``cmd``, for instance
      typing ``Windows+R`` and then ``cmd`` in the dialog. Assuming
      ``7Zip`` is installed in the standard folder, simply run the
      following commands (for APEX version 2.0.0-SNAPSHOT full
      distribution)

   .. container:: listingblock

      .. container:: content

         .. code:: bash
           :number-lines:

            >c:
            >cd \apex
            >"\Program Files\7-Zip\7z.exe" x apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -so | "\Program Files\7-Zip\7z.exe" x -aoa -si -ttar -o"apex-full-2.0.0-SNAPSHOT"

.. container:: paragraph

   APEX is now installed in the folder
   ``C:\apex\apex-full-2.0.0-SNAPSHOT``.

Build from Source
^^^^^^^^^^^^^^^^^

Build and Install Manually (Unix, Windows, Cygwin)
--------------------------------------------------

         .. container:: paragraph

            Clone the APEX GIT repositories into a directory. Go to that
            directory. Use Maven to build APEX (all details on building
            APEX from source can be found in *APEX HowTo: Build*).
            Install from the created artifacts (``rpm``, ``deb``,
            ``tar.gz``, or copying manually).

         .. important:: 
		    Building RPM distributions
			RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``, 
			then build APEX.

         .. container:: paragraph

            The following example shows how to build the APEX system,
            without tests (``-DskipTests``) to safe some time. It
            assumes that the APX GIT repositories are cloned to:

         .. container:: ulist

            -  Unix, Cygwin: ``/usr/local/src/apex``

            -  Windows: ``C:\dev\apex``

    	 +-------------------------------------------------------+--------------------------------------------------------+
         | Unix, Cygwin                                          | Windows                                                |
         +=======================================================+========================================================+
         | .. container::                                        | .. container::                                         |
         |                                                       |                                                        |
         |    .. container:: content                             |    .. container:: content                              |
         |                                                       |                                                        |
         |       .. code:: bash                                  |       .. code:: bash                                   |
         |         :number-lines:                                |         :number-lines:                                 |
         |                                                       |                                                        |
         |         >c:                                           |         # cd /usr/local/src/apex                       |
         |         >cd \dev\apex                                 |         # mvn clean install -DskipTests                |
         |         >mvn clean install -DskipTests                |                                                        |
         +-------------------------------------------------------+--------------------------------------------------------+

.. container:: paragraph

   The build takes about 2 minutes without test and about 4-5 minutes
   with tests on a standard development laptop. It should run through
   without errors, but with a lot of messages from the build process. If
   build with tests (i.e. without ``-DskipTests``), there will be error
   messages and stack trace prints from some tests. This is normal, as
   long as the build finishes successful.

.. container:: paragraph

   When Maven is finished with the build, the final screen should look
   similar to this (omitting some ``success`` lines):

.. container:: listingblock

   .. container:: content

      .. code:: bash
         :number-lines:

         [INFO] tools .............................................. SUCCESS [  0.248 s]
         [INFO] tools-common ....................................... SUCCESS [  0.784 s]
         [INFO] simple-wsclient .................................... SUCCESS [  3.303 s]
         [INFO] model-generator .................................... SUCCESS [  0.644 s]
         [INFO] packages ........................................... SUCCESS [  0.336 s]
         [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
         [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
         [INFO] ------------------------------------------------------------------------
         [INFO] BUILD SUCCESS
         [INFO] ------------------------------------------------------------------------
         [INFO] Total time: 03:43 min
         [INFO] Finished at: 2018-09-03T11:56:01+01:00
         [INFO] ------------------------------------------------------------------------

.. container:: paragraph

   The build will have created all artifacts required for an APEX
   installation. The following example show how to change to the target
   directory and how it should look like.

+-----------------------------------------------------------------------------------------------------------------------------+
| Unix, Cygwin                                                                                                                |
+=============================================================================================================================+
| .. container::                                                                                                              |
|                                                                                                                             |
|    .. container:: listingblock                                                                                              |
|                                                                                                                             |
|          .. code:: bash                                                                                                     |
|            :number-lines:                                                                                                   |
|                                                                                                                             |
|            # cd packages/apex-pdp-package-full/target                                                                       |
|            # ls -l                                                                                                          |
|            -rwxrwx---+ 1 esvevan Domain Users       772 Sep  3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes*      |
|            -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb*              |
|            -rwxrwx---+ 1 esvevan Domain Users     15633 Sep  3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar*              |
|            -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz*   |
|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 archive-tmp/                                           |
|            -rwxrwx---+ 1 esvevan Domain Users        89 Sep  3 11:54 checkstyle-cachefile*                                  |
|            -rwxrwx---+ 1 esvevan Domain Users     10621 Sep  3 11:54 checkstyle-checker.xml*                                |
|            -rwxrwx---+ 1 esvevan Domain Users       584 Sep  3 11:54 checkstyle-header.txt*                                 |
|            -rwxrwx---+ 1 esvevan Domain Users        86 Sep  3 11:54 checkstyle-result.xml*                                 |
|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 classes/                                               |
|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 dependency-maven-plugin-markers/                       |
|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 etc/                                                   |
|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 examples/                                              |
|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:55 install_hierarchy/                                     |
|            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 maven-archiver/                                        |
+-----------------------------------------------------------------------------------------------------------------------------+

+-----------------------------------------------------------------------------------------------------------------------------+
| Windows                                                                                                                     |
+=============================================================================================================================+
| .. container::                                                                                                              |
|                                                                                                                             |
|    .. container:: listingblock                                                                                              |
|                                                                                                                             |
|          .. code:: bash                                                                                                     |
|            :number-lines:                                                                                                   |
|                                                                                                                             |
|            >cd packages\apex-pdp-package-full\target                                                                        |
|            >dir                                                                                                             |
|            03/09/2018  11:55    <DIR>          .                                                                            |
|            03/09/2018  11:55    <DIR>          ..                                                                           |
|            03/09/2018  11:55       146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz                          |
|            03/09/2018  11:55       146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb                                     |
|            03/09/2018  11:54            15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar                                     |
|            03/09/2018  11:55               772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes                             |
|            03/09/2018  11:54    <DIR>          archive-tmp                                                                  |
|            03/09/2018  11:54                89 checkstyle-cachefile                                                         |
|            03/09/2018  11:54            10,621 checkstyle-checker.xml                                                       |
|            03/09/2018  11:54               584 checkstyle-header.txt                                                        |
|            03/09/2018  11:54                86 checkstyle-result.xml                                                        |
|            03/09/2018  11:54    <DIR>          classes                                                                      |
|            03/09/2018  11:54    <DIR>          dependency-maven-plugin-markers                                              |
|            03/09/2018  11:54    <DIR>          etc                                                                          |
|            03/09/2018  11:54    <DIR>          examples                                                                     |
|            03/09/2018  11:55    <DIR>          install_hierarchy                                                            |
|            03/09/2018  11:54    <DIR>          maven-archiver                                                               |
|                           8 File(s)    292,652,686 bytes                                                                    |
|                           9 Dir(s)  14,138,720,256 bytes free                                                               |
+-----------------------------------------------------------------------------------------------------------------------------+

.. container:: paragraph

   Now, take the ``.deb`` or the ``.tar.gz`` file and install APEX.
   Alternatively, copy the content of the folder ``install_hierarchy``
   to your APEX directory.

Installation Layout
^^^^^^^^^^^^^^^^^^^

      .. container:: paragraph

         A full installation of APEX comes with the following layout.

      .. container:: listingblock

         .. container:: content

            ::

               $APEX_HOME
                   ├───bin             (1)
                   ├───etc             (2)
                   │   ├───editor
                   │   ├───hazelcast
                   │   ├───infinispan
                   │   └───META-INF
                   ├───examples            (3)
                   │   ├───config          (4)
                   │   ├───docker          (5)
                   │   ├───events          (6)
                   │   ├───html            (7)
                   │   ├───models          (8)
                   │   └───scripts         (9)
                   ├───lib             (10)
                   │   └───applications        (11)
                   └───war             (12)

      .. container:: colist arabic

         +-----------------------------------+-----------------------------------+
         | **1**                             | binaries, mainly scripts (bash    |
         |                                   | and bat) to start the APEX engine |
         |                                   | and applications                  |
         +-----------------------------------+-----------------------------------+
         | **2**                             | configuration files, such as      |
         |                                   | logback (logging) and third party |
         |                                   | library configurations            |
         +-----------------------------------+-----------------------------------+
         | **3**                             | example policy models to get      |
         |                                   | started                           |
         +-----------------------------------+-----------------------------------+
         | **4**                             | configurations for the examples   |
         |                                   | (with sub directories for         |
         |                                   | individual examples)              |
         +-----------------------------------+-----------------------------------+
         | **5**                             | Docker files and additional       |
         |                                   | Docker instructions for the       |
         |                                   | exampples                         |
         +-----------------------------------+-----------------------------------+
         | **6**                             | example events for the examples   |
         |                                   | (with sub directories for         |
         |                                   | individual examples)              |
         +-----------------------------------+-----------------------------------+
         | **7**                             | HTML files for some examples,     |
         |                                   | e.g. the Decisionmaker example    |
         +-----------------------------------+-----------------------------------+
         | **8**                             | the policy models, generated for  |
         |                                   | each example (with sub            |
         |                                   | directories for individual        |
         |                                   | examples)                         |
         +-----------------------------------+-----------------------------------+
         | **9**                             | additional scripts for the        |
         |                                   | examples (with sub directories    |
         |                                   | for individual examples)          |
         +-----------------------------------+-----------------------------------+
         | **10**                            | the library folder with all Java  |
         |                                   | JAR files                         |
         +-----------------------------------+-----------------------------------+
         | **11**                            | applications, also known as jar   |
         |                                   | with dependencies (or fat jars),  |
         |                                   | individually deployable           |
         +-----------------------------------+-----------------------------------+
         | **12**                            | WAR files for web applications    |
         +-----------------------------------+-----------------------------------+

System Configuration
^^^^^^^^^^^^^^^^^^^^

      .. container:: paragraph

         Once APEX is installed, a few configurations need to be done:

      .. container:: ulist

         -  Create an APEX user and an APEX group (optional, if not
            installed using RPM and DPKG)

         -  Create environment settings for ``APEX_HOME`` and
            ``APEX_USER``, required by the start scripts

         -  Change settings of the logging framework (optional)

         -  Create directories for logging, required (execution might
            fail if directories do not exist or cannot be created)

APEX User and Group
-------------------

         .. container:: paragraph

            On smaller installations and test systems, APEX can run as
            any user or group.

         .. container:: paragraph

            However, if APEX is installed in production, we strongly
            recommend you set up a dedicated user for running APEX. This
            will isolate the execution of APEX to that user. We
            recommend you use the userid ``apexuser`` but you may use
            any user you choose.

         .. container:: paragraph

            The following example, for UNIX, creates a group called
            ``apexuser``, an APEX user called ``apexuser``, adds the
            group to the user, and changes ownership of the APEX
            installation to the user. Substitute ``<apex-dir>`` with the
            directory where APEX is installed.

         .. container:: listingblock

            .. container:: content

               .. code:: bash
                  :number-lines:

                  # sudo groupadd apexuser
                  # sudo useradd -g apexuser apexuser
                  # sudo chown -R apexuser:apexuser <apex-dir>

.. container:: paragraph

   For other operating systems please consult your manual or system
   administrator.

Environment Settings: APEX_HOME and APEX_USER
---------------------------------------------

   .. container:: paragraph

      The provided start scripts for APEX require two environment
      variables being set:

   .. container:: ulist

      -  ``APEX_USER`` with the user under whos name and permission APEX
         should be started (Unix only)

      -  ``APEX_HOME`` with the directory where APEX is installed (Unix,
         Windows, Cygwin)

   .. container:: paragraph

      The first row in the following table shows how to set these
      environment variables temporary (assuming the user is
      ``apexuser``). The second row shows how to verify the settings.
      The last row explains how to set those variables permanently.

   +------------------------------------------------+---------------------------------------------------------+
   | Unix, Cygwin (bash/tcsh)                       | Windows                                                 |
   +================================================+=========================================================+
   | .. container::                                 | .. container::                                          |
   |                                                |                                                         |
   |    .. container:: content                      |    .. container:: content                               |
   |                                                |                                                         |
   |       .. code:: bash                           |       .. code:: bash                                    |
   |          :number-lines:                        |         :number-lines:                                  |
   |                                                |                                                         |
   |          # export APEX_USER=apexuser           |         >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT |
   |          # cd /opt/app/policy/apex-pdp         |                                                         |
   |          # export APEX_HOME=`pwd`              |                                                         | 
   |                                                |                                                         |
   +------------------------------------------------+                                                         |
   | .. container::                                 |                                                         |
   |                                                |                                                         |
   |    .. container:: content                      |                                                         |
   |                                                |                                                         |
   |       .. code:: tcsh                           |                                                         |
   |          :number-lines:                        |                                                         |
   |                                                |                                                         |
   |          # setenv APEX_USER apexuser           |                                                         |
   |          # cd /opt/app/policy/apex-pdp         |                                                         |
   |          # setenv APEX_HOME `pwd`              |                                                         | 
   |                                                |                                                         |
   +------------------------------------------------+---------------------------------------------------------+
   | .. container::                                 | .. container::                                          |
   |                                                |                                                         |
   |    .. container:: content                      |    .. container:: content                               |
   |                                                |                                                         |
   |       .. code:: bash                           |       .. code:: bash                                    |
   |          :number-lines:                        |          :number-lines:                                 |
   |                                                |                                                         |
   |          # env | grep APEX                     |          >set APEX_HOME                                 |
   |          # APEX_USER=apexuser                  |          APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT       |
   |          # APEX_HOME=/opt/app/policy/apex-pdp  |                                                         | 
   |                                                |                                                         |
   +------------------------------------------------+---------------------------------------------------------+


Making Environment Settings Permanent (Unix, Cygwin)
####################################################

   .. container:: paragraph

      For a per-user setting, edit the a user’s ``bash`` or ``tcsh``
      settings in ``~/.bashrc`` or ``~/.tcshrc``. For system-wide
      settings, edit ``/etc/profiles`` (requires permissions).


Making Environment Settings Permanent (Windows)
###############################################

   .. container:: paragraph

      On Windows 7 do

   .. container:: ulist

      -  Click on the **Start** Menu

      -  Right click on **Computer**

      -  Select **Properties**

   .. container:: paragraph

      On Windows 8/10 do

   .. container:: ulist

      -  Click on the **Start** Menu

      -  Select **System**

   .. container:: paragraph

      Then do the following

   .. container:: ulist

      -  Select **Advanced System Settings**

      -  On the **Advanced** tab, click the **Environment Variables**
         button

      -  Edit an existing variable, or create a new System variable:
         'Variable name'="APEX_HOME", 'Variable
         value'="C:\apex\apex-full-2.0.0-SNAPSHOT"

   .. container:: paragraph

      For the settings to take effect, an application needs to be
      restarted (e.g. any open ``cmd`` window).

Edit the APEX Logging Settings
------------------------------

   .. container:: paragraph

      Configure the APEX logging settings to your requirements, for
      instance:

   .. container:: ulist

      -  change the directory where logs are written to, or

      -  change the log levels

   .. container:: paragraph

      Edit the file ``$APEX_HOME/etc/logback.xml`` for any required
      changes. To change the log directory change the line

   .. container:: paragraph

      ``<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />``

   .. container:: paragraph

      to

   .. container:: paragraph

      ``<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />``

   .. container:: paragraph

      On Windows, it is recommended to change the log directory to:

   .. container:: paragraph

      ``<property name="VAR_LOG" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``

   .. container:: paragraph

      Note: Be careful about when to use ``\`` vs. ``/`` as the path
      separator!

Create Directories for Logging
------------------------------

   .. container:: paragraph

      Make sure that the log directory exists. This is important when
      APEX was installed manually or when the log directory was changed
      in the settings (see above).
	  
   +------------------------------------------------------------------+-------------------------------------------------------+
   | Unix, Cygwin                                                     | Windows                                               |
   +==================================================================+=======================================================+
   | .. container::                                                   | .. container::                                        |
   |                                                                  |                                                       |
   |    .. container:: content                                        |    .. container:: content                             |
   |                                                                  |                                                       |
   |       .. code:: bash                                             |       .. code:: bash                                  |
   |         :number-lines:                                           |         :number-lines:                                |
   |                                                                  |                                                       |
   |         mkdir -p /var/log/onap/policy/apex-pdp                   |         >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs  |
   |         chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp |                                                       |
   +------------------------------------------------------------------+-------------------------------------------------------+

Verify the APEX Installation
############################

   .. container:: sectionbody

      .. container:: paragraph

         When APEX is installed and all settings are realized, the
         installation can be verified.

Verify Installation - run Engine
--------------------------------

         .. container:: paragraph

            A simple verification of an APEX installation can be done by
            simply starting the APEX engine without any configuration.
            On Unix (or Cygwin) start the engine using
            ``$APEX_HOME/bin/apexEngine.sh``. On Windows start the
            engine using ``%APEX_HOME%\bin\apexEngine.bat``. The engine
            will fail to fully start. However, if the output looks
            similar to the following line, the APEX installation is
            realized.

         .. container:: listingblock

            .. container:: content

               .. code:: bash
                  :number-lines:

                  Starting Apex service with parameters [] . . .
                  start of Apex service failed: Apex configuration file was not specified as an argument
                  2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed
                  org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument
                          at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267)
                          at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161)
                          at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68)
                          at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165)
                  usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
                  options
                  -c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file
                                                containing the Apex configuration parameters
                  -h,--help                     outputs the usage of this command
                  -m,--model-file <MODEL_FILE>  the full path to the model file to use, if set it overrides the model file set in the
                                                configuration file
                  -v,--version                  outputs the version of Apex

Verify Installation - run an Example
------------------------------------

   .. container:: paragraph

      A full APEX installation comes with several examples. Here, we can
      fully verify the installation by running one of the examples.

   .. container:: paragraph

      We use the example called *SampleDomain* and configure the engine
      to use standard in and standard out for events. Run the engine
      with the provided configuration. Note: Cygwin executes scripts as
      Unix scripts but runs Java as a Windows application, thus the
      configuration file must be given as a Windows path.

   .. container:: listingblock

      .. container:: content

         .. code:: bash
                :number-lines:

 	        # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1)
 	        # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2)
 	        >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3)

.. container:: colist arabic

   +-------+---------+
   | **1** | UNIX    |
   +-------+---------+
   | **2** | Cygwin  |
   +-------+---------+
   | **3** | Windows |
   +-------+---------+

.. container:: paragraph

   The engine should start successfully. Assuming the logging levels are
   not change (default level is ``info``), the output should look
   similar to this (last few lines)

.. container:: listingblock

   .. container:: content

      .. code:: bash
         :number-lines:

         Starting Apex service with parameters [-c, v:/dev/ericsson/apex/onap/apex-pdp/packages/apex-pdp-package-full/target/install_hierarchy/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json] . . .
         2018-09-05 15:16:42,800 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-0:0.0.1 .
         2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-1:0.0.1 .
         2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-2:0.0.1 .
         2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-3:0.0.1 .
         2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created.
         2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . .
         2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started
         2018-09-05 15:16:44,987 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-0:0.0.1
         2018-09-05 15:16:45,112 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-1:0.0.1
         2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-2:0.0.1
         2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-3:0.0.1
         2018-09-05 15:16:45,120 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine
         Started Apex service

.. container:: paragraph

   Important are the last two line, stating that APEX has added the
   final action listener to the engine and that the engine is started.

.. container:: paragraph

   The engine is configured to read events from standard input and write
   produced events to standard output. The policy model is a very simple
   policy.

.. container:: paragraph

   The following table shows an input event in the left column and an
   output event in the right column. Past the input event into the
   console where APEX is running, and the output event should appear in
   the console. Pasting the input event multiple times will produce
   output events with different values.

+-------------------------------------------------------------+-------------------------------------------------------------+
| Input Event                                                 | Example Output Event                                        |
+=============================================================+=============================================================+
| .. container::                                              | .. container::                                              |
|                                                             |                                                             |
|    .. container:: content                                   |    .. container:: content                                   |
|                                                             |                                                             |
|       .. code:: bash                                        |       .. code:: bash                                        |
|         :number-lines:                                      |         :number-lines:                                      |
|                                                             |                                                             |
|         {                                                   |         {                                                   |
|          "nameSpace": "org.onap.policy.apex.sample.events", |          "name": "Event0004",                               |
|          "name": "Event0000",                               |          "version": "0.0.1",                                |
|          "version": "0.0.1",                                |          "nameSpace": "org.onap.policy.apex.sample.events", |
|          "source": "test",                                  |          "source": "Act",                                   |
|          "target": "apex",                                  |          "target": "Outside",                               |
|          "TestSlogan": "Test slogan for External Event0",   |          "TestActCaseSelected": 2,                          |
|          "TestMatchCase": 0,                                |          "TestActStateTime": 1536157104627,                 |
|          "TestTimestamp": 1469781869269,                    |          "TestDecideCaseSelected": 0,                       |
|          "TestTemperature": 9080.866                        |          "TestDecideStateTime": 1536157104625,              |
|         }                                                   |          "TestEstablishCaseSelected": 0,                    |
|                                                             |          "TestEstablishStateTime": 1536157104623,           |
|                                                             |          "TestMatchCase": 0,                                |
|                                                             |          "TestMatchCaseSelected": 1,                        |
|                                                             |          "TestMatchStateTime": 1536157104620,               |
|                                                             |          "TestSlogan": "Test slogan for External Event0",   |
|                                                             |          "TestTemperature": 9080.866,                       |
|                                                             |          "TestTimestamp": 1469781869269                     |
|                                                             |          }                                                  |
+-------------------------------------------------------------+-------------------------------------------------------------+

.. container:: paragraph

   Terminate APEX by simply using ``CTRL+C`` in the console.

Verify a Full Installation - REST Editor
----------------------------------------

   .. container:: paragraph

      APEX has a REST application for viewing policy models. The
      application can also be used to create new policy models close to
      the engine native policy language. Start the REST editor as
      follows.

   .. container:: listingblock

      .. container:: content

         .. code:: bash
            :number-lines:

            # $APEX_HOME/bin/apexApps.sh rest-editor

.. container:: listingblock

   .. container:: content

      .. code:: bash
            :number-lines:

            >%APEX_HOME%\bin\apexApps.bat rest-editor

.. container:: paragraph

   The script will start a simple web server
   (`Grizzly <https://javaee.github.io/grizzly/>`__) and deploy a
   ``war`` web archive in it. Once the editor is started, it will be
   available on ``localhost:18989``. The last few line of the messages
   should be:

.. container:: listingblock

   .. container:: content

      .. code:: bash
         :number-lines:

         Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
         Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start
         INFO: Started listener bound to [localhost:18989]
         Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start
         INFO: [HttpServer] Started.
         Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/

.. container:: paragraph

   Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and
   use the URL ``http://localhost:18989/``. This will connect the
   browser to the started REST editor. The start screen should be as
   follows.

.. container:: imageblock

   .. container:: content

      |REST Editor Start Screen|

   .. container:: title

      Figure 1. REST Editor Start Screen

.. container:: paragraph

   Now load a policy model by clicking the menu ``File`` and then
   ``Open``. In the opened dialog, go to the directory where APEX is
   installed, then ``examples``, ``models``, ``SampleDomain``, and there
   select the file ``SamplePolicyModelJAVA.json``. This will load the
   policy model used to verify the policy engine (see above). Once
   loaded, the screen should look as follows.

.. container:: imageblock

   .. container:: content

      |REST Editor with loaded SampleDomain Policy Model|

   .. container:: title

      Figure 2. REST Editor with loaded SampleDomain Policy Model

.. container:: paragraph

   Now you can use the REST editor. To finish this verification, simply
   terminate your browser (or the tab), and then use ``CTRL+C`` in the
   console where you started the REST editor.

Installing WAR Applications
^^^^^^^^^^^^^^^^^^^^^^^^^^^

   .. container:: sectionbody

      .. container:: paragraph

         APEX comes with a set of WAR files. These are complete
         applications that can be installed and run in an application
         server. All of these applications are realized as servlets. You
         can find the WAR applications in ``$APEX_HOME/war`` (UNIX,
         Cygwin) or ``%APEX_HOME%\war`` (Windows).

      .. container:: paragraph

         Installing and using the WAR applications requires a web server
         that can execute ``war`` web archives. We recommend to use
         `Apache Tomcat <https://tomcat.apache.org/>`__, however other
         web servers can be used as well.

      .. container:: paragraph

         Install Apache Tomcat including the ``Manager App``, see `V9.0
         Docs <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access>`__
         for details. Start the Tomcat service, or make sure that Tomcat
         is running.

      .. container:: paragraph

         There are multiple ways to install the APEX WAR applications:

      .. container:: ulist

         -  copy the ``.war`` file into the Tomcat ``webapps`` folder

         -  use the Tomcat ``Manager App`` to deploy via the web
            interface

         -  deploy using a REST call to Tomcat

      .. container:: paragraph

         For details on how to install ``war`` files please consult the
         `Tomcat
         Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__
         or the `Manager App
         HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html>`__.
         Once you installed an APEX WAR application (and wait for
         sufficient time for Tomcat to finalize the installation), open
         the ``Manager App`` in Tomcat. You should see the APEX WAR
         application being installed and running.

      .. container:: paragraph

         In case of errors, examine the log files in the Tomcat log
         directory. In a conventional install, those log files are in
         the logs directory where Tomcat is installed.

      .. container:: paragraph

         The current APEX version provides the following WAR
         applications:

      .. container:: ulist

         -  client-deployment-2.0.0-SNAPSHOT.war - a client to deploy
            new policy models to a running engine

         -  client-editor-2.0.0-SNAPSHOT.war - the standard policy REST
            editor GUI

         -  client-monitoring-2.0.0-SNAPSHOT.war - a client for
            monitoring a running APEX engine

         -  client-full-2.0.0-SNAPSHOT.war - a full client with a
            one-stop-access to deployment, monitoring, and REST editor

         -  examples-servlet-2.0.0-SNAPSHOT.war - an example APEX
            servlet

Running APEX in Docker
^^^^^^^^^^^^^^^^^^^^^^

   .. container:: sectionbody

      .. container:: paragraph

         Since APEX is in ONAP, we provide a full virtualization
         environment for the engine.

Run in ONAP
-----------

         .. container:: paragraph

            Running APEX from the ONAP docker repository only requires 2
            commands:

         .. container:: olist arabic

            #. Log into the ONAP docker repo

         .. container:: listingblock

            .. container:: content

               ::

                  docker login -u docker -p docker nexus3.onap.org:10003

         .. container:: olist arabic

            #. Run the APEX docker image

         .. container:: listingblock

            .. container:: content

               ::

                  docker run -it --rm  nexus3.onap.org:10003/onap/policy-apex-pdp:latest


Build a Docker Image
--------------------

         .. container:: paragraph

            Alternatively, one can use the Dockerfile defined in the
            Docker package to build an image.

         .. container:: listingblock

            .. container:: title

               APEX Dockerfile

            .. container:: content

               .. code:: bash
                  :number-lines:

                  #
                  # Docker file to build an image that runs APEX on Java 8 in Ubuntu
                  #
                  FROM ubuntu:16.04

                  RUN apt-get update && \
                          apt-get upgrade -y && \
                          apt-get install -y software-properties-common && \
                          add-apt-repository ppa:openjdk-r/ppa -y && \
                          apt-get update && \
                          apt-get install -y openjdk-8-jdk

                  # Create apex user and group
                  RUN groupadd apexuser
                  RUN useradd --create-home -g apexuser apexuser

                  # Add Apex-specific directories and set ownership as the Apex admin user
                  RUN mkdir -p /opt/app/policy/apex-pdp
                  RUN mkdir -p /var/log/onap/policy/apex-pdp
                  RUN chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp

                  # Unpack the tarball
                  RUN mkdir /packages
                  COPY apex-pdp-package-full.tar.gz /packages
                  RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory /opt/app/policy/apex-pdp
                  RUN rm /packages/apex-pdp-package-full.tar.gz

                  # Ensure everything has the correct permissions
                  RUN find /opt/app -type d -perm 755
                  RUN find /opt/app -type f -perm 644
                  RUN chmod a+x /opt/app/policy/apex-pdp/bin/*

                  # Copy examples to Apex user area
                  RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser

                  RUN apt-get clean

                  RUN chown -R apexuser:apexuser /home/apexuser/*

                  USER apexuser
                  ENV PATH /opt/app/policy/apex-pdp/bin:$PATH
                  WORKDIR /home/apexuser

.. container::
   :name: footer

   .. container::
      :name: footer-text

      2.0.0-SNAPSHOT
      Last updated 2018-09-10 15:38:16 IST

.. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png
.. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png
.. |REST Editor Start Screen| image:: images/install-guide/rest-start.png
.. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png