Blame - docs/APEX-Install-Guide.rst - onap/policy/apex-pdp

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

475

476

.. container:: paragraph

477

478

APEX is now installed in the folder

479

``C:\apex\apex-full-2.0.0-SNAPSHOT``.

Build from Source

^^^^^^^^^^^^^^^^^

Build and Install Manually (Unix, Windows, Cygwin)

485

--------------------------------------------------

486

487

.. container:: paragraph

488

489

Clone the APEX GIT repositories into a directory. Go to that

490

directory. Use Maven to build APEX (all details on building

491

APEX from source can be found in *APEX HowTo: Build*).

492

Install from the created artifacts (``rpm``, ``deb``,

493

``tar.gz``, or copying manually).

494

495

.. important::

496

Building RPM distributions

497

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

498

then build APEX.

499

500

.. container:: paragraph

501

502

The following example shows how to build the APEX system,

503

without tests (``-DskipTests``) to safe some time. It

504

assumes that the APX GIT repositories are cloned to:

.. container:: ulist

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

509

510

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

511

512

+-------------------------------------------------------+--------------------------------------------------------+

513

| Unix, Cygwin | Windows |

514

+=======================================================+========================================================+

515

| .. container:: | .. container:: |

516

| | |

517

| .. container:: content | .. container:: content |

518

| | |

519

| .. code:: bash | .. code:: bash |

520

| :number-lines: | :number-lines: |

521

| | |

522

| >c: | # cd /usr/local/src/apex |

523

| >cd \dev\apex | # mvn clean install -DskipTests |

524

| >mvn clean install -DskipTests | |

525

+-------------------------------------------------------+--------------------------------------------------------+

526

527

.. container:: paragraph

528

529

The build takes about 2 minutes without test and about 4-5 minutes

530

with tests on a standard development laptop. It should run through

531

without errors, but with a lot of messages from the build process. If

532

build 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 successful.

535

536

.. container:: paragraph

537

538

When Maven is finished with the build, the final screen should look

539

similar to this (omitting some ``success`` lines):

540

541

.. container:: listingblock

542

543

.. container:: content

.. code:: bash

:number-lines:

[INFO] tools .............................................. SUCCESS [ 0.248 s]

549

[INFO] tools-common ....................................... SUCCESS [ 0.784 s]

550

[INFO] simple-wsclient .................................... SUCCESS [ 3.303 s]

551

[INFO] model-generator .................................... SUCCESS [ 0.644 s]

552

[INFO] packages ........................................... SUCCESS [ 0.336 s]

553

[INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]

554

[INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]

555

[INFO] ------------------------------------------------------------------------

556

[INFO] BUILD SUCCESS

557

[INFO] ------------------------------------------------------------------------

558

[INFO] Total time: 03:43 min

559

[INFO] Finished at: 2018-09-03T11:56:01+01:00

560

[INFO] ------------------------------------------------------------------------

561

562

.. container:: paragraph

563

564

The build will have created all artifacts required for an APEX

565

installation. The following example show how to change to the target

566

directory and how it should look like.

567

568

+-----------------------------------------------------------------------------------------------------------------------------+

569

| Unix, Cygwin |

570

+=============================================================================================================================+

571

| .. container:: |

572

| |

573

| .. container:: listingblock |

| |

| .. code:: bash |

| :number-lines: |

| |

| # cd packages/apex-pdp-package-full/target |

579

| # ls -l |

580

| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* |

581

| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* |

582

| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* |

583

| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |

584

| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ |

585

| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* |

586

| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* |

587

| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* |

588

| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* |

589

| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ |

590

| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ |

591

| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ |

592

| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ |

593

| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ |

594

| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ |

595

+-----------------------------------------------------------------------------------------------------------------------------+

596

597

+-----------------------------------------------------------------------------------------------------------------------------+

598

| Windows |

599

+=============================================================================================================================+

600

| .. container:: |

601

| |

602

| .. container:: listingblock |

| |

| .. code:: bash |

| :number-lines: |

| |

| >cd packages\apex-pdp-package-full\target |

608

| >dir |

609

| 03/09/2018 11:55 <DIR> . |

610

| 03/09/2018 11:55 <DIR> .. |

611

| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |

612

| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb |

613

| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar |

614

| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes |

615

| 03/09/2018 11:54 <DIR> archive-tmp |

616

| 03/09/2018 11:54 89 checkstyle-cachefile |

617

| 03/09/2018 11:54 10,621 checkstyle-checker.xml |

618

| 03/09/2018 11:54 584 checkstyle-header.txt |

619

| 03/09/2018 11:54 86 checkstyle-result.xml |

620

| 03/09/2018 11:54 <DIR> classes |

621

| 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers |

622

| 03/09/2018 11:54 <DIR> etc |

623

| 03/09/2018 11:54 <DIR> examples |

624

| 03/09/2018 11:55 <DIR> install_hierarchy |

625

| 03/09/2018 11:54 <DIR> maven-archiver |

626

| 8 File(s) 292,652,686 bytes |

627

| 9 Dir(s) 14,138,720,256 bytes free |

628

+-----------------------------------------------------------------------------------------------------------------------------+

629

630

.. container:: paragraph

631

632

Now, take the ``.deb`` or the ``.tar.gz`` file and install APEX.

633

Alternatively, copy the content of the folder ``install_hierarchy``

634

to your APEX directory.

Installation Layout

^^^^^^^^^^^^^^^^^^^

.. container:: paragraph

640

641

A full installation of APEX comes with the following layout.

642

643

.. container:: listingblock

644

645

.. 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)

665

└───war (12)

666

667

.. container:: colist arabic

668

669

+-----------------------------------+-----------------------------------+

670

| **1** | binaries, mainly scripts (bash |

671

| | and bat) to start the APEX engine |

672

| | and applications |

673

+-----------------------------------+-----------------------------------+

674

| **2** | configuration files, such as |

675

| | logback (logging) and third party |

676

| | library configurations |

677

+-----------------------------------+-----------------------------------+

678

| **3** | example policy models to get |

679

| | started |

680

+-----------------------------------+-----------------------------------+

681

| **4** | configurations for the examples |

682

| | (with sub directories for |

683

| | individual examples) |

684

+-----------------------------------+-----------------------------------+

685

| **5** | Docker files and additional |

686

| | Docker instructions for the |

687

| | exampples |

688

+-----------------------------------+-----------------------------------+

689

| **6** | example events for the examples |

690

| | (with sub directories for |

691

| | individual examples) |

692

+-----------------------------------+-----------------------------------+

693

| **7** | HTML files for some examples, |

694

| | e.g. the Decisionmaker example |

695

+-----------------------------------+-----------------------------------+

696

| **8** | the policy models, generated for |

697

| | each example (with sub |

698

| | directories for individual |

699

| | examples) |

700

+-----------------------------------+-----------------------------------+

701

| **9** | additional scripts for the |

702

| | examples (with sub directories |

703

| | for individual examples) |

704

+-----------------------------------+-----------------------------------+

705

| **10** | the library folder with all Java |

706

| | JAR files |

707

+-----------------------------------+-----------------------------------+

708

| **11** | applications, also known as jar |

709

| | with dependencies (or fat jars), |

710

| | individually deployable |

711

+-----------------------------------+-----------------------------------+

712

| **12** | WAR files for web applications |

713

+-----------------------------------+-----------------------------------+

System Configuration

^^^^^^^^^^^^^^^^^^^^

.. container:: paragraph

719

720

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

.. container:: ulist

- Create an APEX user and an APEX group (optional, if not

725

installed using RPM and DPKG)

726

727

- Create environment settings for ``APEX_HOME`` and

728

``APEX_USER``, required by the start scripts

729

730

- Change settings of the logging framework (optional)

731

732

- Create directories for logging, required (execution might

733

fail if directories do not exist or cannot be created)

APEX User and Group

-------------------

.. container:: paragraph

739

740

On smaller installations and test systems, APEX can run as

741

any user or group.

742

743

.. container:: paragraph

744

745

However, if APEX is installed in production, we strongly

746

recommend you set up a dedicated user for running APEX. This

747

will isolate the execution of APEX to that user. We

748

recommend you use the userid ``apexuser`` but you may use

749

any user you choose.

750

751

.. container:: paragraph

752

753

The following example, for UNIX, creates a group called

754

``apexuser``, an APEX user called ``apexuser``, adds the

755

group to the user, and changes ownership of the APEX

756

installation to the user. Substitute ``<apex-dir>`` with the

757

directory where APEX is installed.

758

759

.. container:: listingblock

760

761

.. container:: content

.. code:: bash

:number-lines:

# sudo groupadd apexuser

767

# sudo useradd -g apexuser apexuser

768

# sudo chown -R apexuser:apexuser <apex-dir>

769

770

.. container:: paragraph

771

772

For other operating systems please consult your manual or system

773

administrator.

774

775

Environment Settings: APEX_HOME and APEX_USER

776

---------------------------------------------

777

778

.. container:: paragraph

779

780

The provided start scripts for APEX require two environment

variables being set:

.. container:: ulist

- ``APEX_USER`` with the user under whos name and permission APEX

786

should be started (Unix only)

787

788

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

789

Windows, Cygwin)

790

791

.. container:: paragraph

792

793

The first row in the following table shows how to set these

794

environment variables temporary (assuming the user is

795

``apexuser``). The second row shows how to verify the settings.

796

The last row explains how to set those variables permanently.

797

798

+------------------------------------------------+---------------------------------------------------------+

799

| Unix, Cygwin (bash/tcsh) | Windows |

800

+================================================+=========================================================+

801

| .. container:: | .. container:: |

802

| | |

803

| .. container:: content | .. container:: content |

804

| | |

805

| .. code:: bash | .. code:: bash |

806

| :number-lines: | :number-lines: |

807

| | |

808

| # export APEX_USER=apexuser | >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT |

809

| # cd /opt/app/policy/apex-pdp | |

810

| # export APEX_HOME=`pwd` | |

811

| | |

812

+------------------------------------------------+ |

813

| .. container:: | |

814

| | |

815

| .. container:: content | |

| | |

| .. code:: tcsh | |

| :number-lines: | |

| | |

| # setenv APEX_USER apexuser | |

821

| # cd /opt/app/policy/apex-pdp | |

822

| # setenv APEX_HOME `pwd` | |

823

| | |

824

+------------------------------------------------+---------------------------------------------------------+

825

| .. container:: | .. container:: |

826

| | |

827

| .. container:: content | .. container:: content |

828

| | |

829

| .. code:: bash | .. code:: bash |

830

| :number-lines: | :number-lines: |

831

| | |

832

| # env | grep APEX | >set APEX_HOME |

833

| # APEX_USER=apexuser | APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT |

834

| # APEX_HOME=/opt/app/policy/apex-pdp | |

835

| | |

836

+------------------------------------------------+---------------------------------------------------------+

837

838

839

Making Environment Settings Permanent (Unix, Cygwin)

840

####################################################

841

842

.. container:: paragraph

843

844

For a per-user setting, edit the a user’s ``bash`` or ``tcsh``

845

settings in ``~/.bashrc`` or ``~/.tcshrc``. For system-wide

846

settings, edit ``/etc/profiles`` (requires permissions).

847

848

849

Making Environment Settings Permanent (Windows)

850

###############################################

851

852

.. container:: paragraph

On Windows 7 do

.. container:: ulist

- Click on the **Start** Menu

859

860

- Right click on **Computer**

861

862

- Select **Properties**

863

864

.. container:: paragraph

On Windows 8/10 do

.. container:: ulist

- Click on the **Start** Menu

- Select **System**

.. container:: paragraph

875

876

Then do the following

.. container:: ulist

- Select **Advanced System Settings**

881

882

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

883

button

884

885

- Edit an existing variable, or create a new System variable:

886

'Variable name'="APEX_HOME", 'Variable

887

value'="C:\apex\apex-full-2.0.0-SNAPSHOT"

888

889

.. container:: paragraph

890

891

For the settings to take effect, an application needs to be

892

restarted (e.g. any open ``cmd`` window).

893

894

Edit the APEX Logging Settings

895

------------------------------

896

897

.. container:: paragraph

898

899

Configure the APEX logging settings to your requirements, for

instance:

.. container:: ulist

- change the directory where logs are written to, or

905

906

- change the log levels

907

908

.. container:: paragraph

909

910

Edit the file ``$APEX_HOME/etc/logback.xml`` for any required

911

changes. To change the log directory change the line

912

913

.. container:: paragraph

914

915

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

916

917

.. container:: paragraph

to

.. container:: paragraph

922

923

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

924

925

.. container:: paragraph

926

927

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

928

929

.. container:: paragraph

930

931

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

932

933

.. container:: paragraph

934

935

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

936

separator!

937

938

Create Directories for Logging

939

------------------------------

940

941

.. container:: paragraph

942

943

Make sure that the log directory exists. This is important when

944

APEX was installed manually or when the log directory was changed

945

in the settings (see above).

946

947

+------------------------------------------------------------------+-------------------------------------------------------+

948

| Unix, Cygwin | Windows |

949

+==================================================================+=======================================================+

950

| .. container:: | .. container:: |

951

| | |

952

| .. container:: content | .. container:: content |

953

| | |

954

| .. code:: bash | .. code:: bash |

955

| :number-lines: | :number-lines: |

956

| | |

957

| mkdir -p /var/log/onap/policy/apex-pdp | >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs |

958

| chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp | |

959

+------------------------------------------------------------------+-------------------------------------------------------+

960

961

Verify the APEX Installation

962

############################

963

964

.. container:: sectionbody

965

966

.. container:: paragraph

967

968

When APEX is installed and all settings are realized, the

969

installation can be verified.

970

971

Verify Installation - run Engine

972

--------------------------------

973

974

.. container:: paragraph

975

976

A simple verification of an APEX installation can be done by

977

simply starting the APEX engine without any configuration.

978

On Unix (or Cygwin) start the engine using

979

``$APEX_HOME/bin/apexEngine.sh``. On Windows start the

980

engine using ``%APEX_HOME%\bin\apexEngine.bat``. The engine

981

will fail to fully start. However, if the output looks

982

similar to the following line, the APEX installation is

983

realized.

984

985

.. container:: listingblock

986

987

.. container:: content

.. code:: bash

:number-lines:

Starting Apex service with parameters [] . . .

993

start of Apex service failed: Apex configuration file was not specified as an argument

994

2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed

995

org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument

996

at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267)

997

at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161)

998

at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68)

999

at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165)

1000

usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]

1001

options

1002

-c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file

1003

containing the Apex configuration parameters

1004

-h,--help outputs the usage of this command

1005

-m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the

1006

configuration file

1007

-v,--version outputs the version of Apex

1008

1009

Verify Installation - run an Example

1010

------------------------------------

1011

1012

.. container:: paragraph

1013

1014

A full APEX installation comes with several examples. Here, we can

1015

fully verify the installation by running one of the examples.

1016

1017

.. container:: paragraph

1018

1019

We use the example called *SampleDomain* and configure the engine

1020

to use standard in and standard out for events. Run the engine

1021

with the provided configuration. Note: Cygwin executes scripts as

1022

Unix scripts but runs Java as a Windows application, thus the

1023

configuration file must be given as a Windows path.

1024

1025

.. container:: listingblock

1026

1027

.. container:: content

.. code:: bash

:number-lines:

# $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1)

1033

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

1034

>%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3)

1035

1036

.. container:: colist arabic

+-------+---------+

| **1** | UNIX |

+-------+---------+

| **2** | Cygwin |

+-------+---------+

| **3** | Windows |

+-------+---------+

.. container:: paragraph

1047

1048

The engine should start successfully. Assuming the logging levels are

1049

not change (default level is ``info``), the output should look

1050

similar to this (last few lines)

1051

1052

.. container:: listingblock

1053

1054

.. 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] . . .

1060

2018-09-05 15:16:42,800 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-0:0.0.1 .

1061

2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-1:0.0.1 .

1062

2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-2:0.0.1 .

1063

2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-3:0.0.1 .

1064

2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created.

1065

2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . .

1066

2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started

1067

2018-09-05 15:16:44,987 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-0:0.0.1

1068

2018-09-05 15:16:45,112 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-1:0.0.1

1069

2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-2:0.0.1

1070

2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-3:0.0.1

1071

2018-09-05 15:16:45,120 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine

1072

Started Apex service

1073

1074

.. container:: paragraph

1075

1076

Important are the last two line, stating that APEX has added the

1077

final action listener to the engine and that the engine is started.

1078

1079

.. container:: paragraph

1080

1081

The engine is configured to read events from standard input and write

1082

produced events to standard output. The policy model is a very simple

1083

policy.

1084

1085

.. container:: paragraph

1086

1087

The following table shows an input event in the left column and an

1088

output event in the right column. Past the input event into the

1089

console where APEX is running, and the output event should appear in

1090

the console. Pasting the input event multiple times will produce

1091

output events with different values.

1092

1093

+-------------------------------------------------------------+-------------------------------------------------------------+

1094

| Input Event | Example Output Event |

1095

+=============================================================+=============================================================+

1096

| .. container:: | .. container:: |

1097

| | |

1098

| .. container:: content | .. container:: content |

1099

| | |

1100

| .. code:: bash | .. code:: bash |

1101

| :number-lines: | :number-lines: |

1102

| | |

1103

| { | { |

1104

| "nameSpace": "org.onap.policy.apex.sample.events", | "name": "Event0004", |

1105

| "name": "Event0000", | "version": "0.0.1", |

1106

| "version": "0.0.1", | "nameSpace": "org.onap.policy.apex.sample.events", |

1107

| "source": "test", | "source": "Act", |

1108

| "target": "apex", | "target": "Outside", |

1109

| "TestSlogan": "Test slogan for External Event0", | "TestActCaseSelected": 2, |

1110

| "TestMatchCase": 0, | "TestActStateTime": 1536157104627, |

1111

| "TestTimestamp": 1469781869269, | "TestDecideCaseSelected": 0, |

1112

| "TestTemperature": 9080.866 | "TestDecideStateTime": 1536157104625, |

1113

| } | "TestEstablishCaseSelected": 0, |

1114

| | "TestEstablishStateTime": 1536157104623, |

1115

| | "TestMatchCase": 0, |

1116

| | "TestMatchCaseSelected": 1, |

1117

| | "TestMatchStateTime": 1536157104620, |

1118

| | "TestSlogan": "Test slogan for External Event0", |

1119

| | "TestTemperature": 9080.866, |

1120

| | "TestTimestamp": 1469781869269 |

1121

| | } |

1122

+-------------------------------------------------------------+-------------------------------------------------------------+

1123

1124

.. container:: paragraph

1125

1126

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

1127

1128

Verify a Full Installation - REST Editor

1129

----------------------------------------

1130

1131

.. container:: paragraph

1132

1133

APEX has a REST application for viewing policy models. The

1134

application can also be used to create new policy models close to

1135

the engine native policy language. Start the REST editor as

1136

follows.

1137

1138

.. container:: listingblock

1139

1140

.. container:: content

.. code:: bash

:number-lines:

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

1146

1147

.. container:: listingblock

1148

1149

.. container:: content

.. code:: bash

:number-lines:

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

1155

1156

.. container:: paragraph

1157

1158

The script will start a simple web server

1159

(`Grizzly <https://javaee.github.io/grizzly/>`__) and deploy a

1160

``war`` web archive in it. Once the editor is started, it will be

1161

available on ``localhost:18989``. The last few line of the messages

1162

should be:

1163

1164

.. container:: listingblock

1165

1166

.. container:: content

.. 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/ . . .

1172

Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start

1173

INFO: Started listener bound to [localhost:18989]

1174

Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start

1175

INFO: [HttpServer] Started.

1176

Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/

1177

1178

.. container:: paragraph

1179

1180

Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and

1181

use the URL ``http://localhost:18989/``. This will connect the

1182

browser to the started REST editor. The start screen should be as

1183

follows.

1184

1185

.. container:: imageblock

1186

1187

.. container:: content

1188

1189

|REST Editor Start Screen|

.. container:: title

Figure 1. REST Editor Start Screen

1194

1195

.. container:: paragraph

1196

1197

Now load a policy model by clicking the menu ``File`` and then

1198

``Open``. In the opened dialog, go to the directory where APEX is

1199

installed, then ``examples``, ``models``, ``SampleDomain``, and there

1200

select the file ``SamplePolicyModelJAVA.json``. This will load the

1201

policy model used to verify the policy engine (see above). Once

1202

loaded, the screen should look as follows.

1203

1204

.. container:: imageblock

1205

1206

.. container:: content

1207

1208

|REST Editor with loaded SampleDomain Policy Model|

.. container:: title

Figure 2. REST Editor with loaded SampleDomain Policy Model

1213

1214

.. container:: paragraph

1215

1216

Now you can use the REST editor. To finish this verification, simply

1217

terminate your browser (or the tab), and then use ``CTRL+C`` in the

1218

console where you started the REST editor.

1219

1220

Installing WAR Applications

1221

^^^^^^^^^^^^^^^^^^^^^^^^^^^

1222

1223

.. container:: sectionbody

1224

1225

.. container:: paragraph

1226

1227

APEX comes with a set of WAR files. These are complete

1228

applications that can be installed and run in an application

1229

server. All of these applications are realized as servlets. You

1230

can find the WAR applications in ``$APEX_HOME/war`` (UNIX,

1231

Cygwin) or ``%APEX_HOME%\war`` (Windows).

1232

1233

.. container:: paragraph

1234

1235

Installing and using the WAR applications requires a web server

1236

that can execute ``war`` web archives. We recommend to use

1237

`Apache Tomcat <https://tomcat.apache.org/>`__, however other

1238

web servers can be used as well.

1239

1240

.. container:: paragraph

1241

1242

Install Apache Tomcat including the ``Manager App``, see `V9.0

1243

Docs <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access>`__

1244

for details. Start the Tomcat service, or make sure that Tomcat

1245

is running.

1246

1247

.. container:: paragraph

1248

1249

There are multiple ways to install the APEX WAR applications:

.. container:: ulist

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

1254

1255

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

1256

interface

1257

1258

- deploy using a REST call to Tomcat

1259

1260

.. container:: paragraph

1261

1262

For details on how to install ``war`` files please consult the

1263

`Tomcat

1264

Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__

1265

or the `Manager App

1266

HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html>`__.

1267

Once you installed an APEX WAR application (and wait for

1268

sufficient time for Tomcat to finalize the installation), open

1269

the ``Manager App`` in Tomcat. You should see the APEX WAR

1270

application being installed and running.

1271

1272

.. container:: paragraph

1273

1274

In case of errors, examine the log files in the Tomcat log

1275

directory. In a conventional install, those log files are in

1276

the logs directory where Tomcat is installed.

1277

1278

.. container:: paragraph

1279

1280

The current APEX version provides the following WAR

applications:

.. container:: ulist

- client-deployment-2.0.0-SNAPSHOT.war - a client to deploy

1286

new policy models to a running engine

1287

1288

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

1289

editor GUI

1290

1291

- client-monitoring-2.0.0-SNAPSHOT.war - a client for

1292

monitoring a running APEX engine

1293

1294

- client-full-2.0.0-SNAPSHOT.war - a full client with a

1295

one-stop-access to deployment, monitoring, and REST editor

1296

1297

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

1298

servlet

1299

1300

Running APEX in Docker

1301

^^^^^^^^^^^^^^^^^^^^^^

1302

1303

.. container:: sectionbody

1304

1305

.. container:: paragraph

1306

1307

Since APEX is in ONAP, we provide a full virtualization

1308

environment for the engine.

Run in ONAP

-----------

.. container:: paragraph

1314

1315

Running APEX from the ONAP docker repository only requires 2

1316

commands:

1317

1318

.. container:: olist arabic

1319

1320

#. Log into the ONAP docker repo

1321

1322

.. container:: listingblock

1323

1324

.. container:: content

::

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

1329

1330

.. container:: olist arabic

1331

1332

#. Run the APEX docker image

1333

1334

.. container:: listingblock

1335

1336

.. container:: content

::

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

Build a Docker Image

--------------------

.. container:: paragraph

1347

1348

Alternatively, one can use the Dockerfile defined in the

1349

Docker package to build an image.

1350

1351

.. 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 && \

1368

apt-get upgrade -y && \

1369

apt-get install -y software-properties-common && \

1370

add-apt-repository ppa:openjdk-r/ppa -y && \

1371

apt-get update && \

1372

apt-get install -y openjdk-8-jdk

1373

1374

# Create apex user and group

1375

RUN groupadd apexuser

1376

RUN useradd --create-home -g apexuser apexuser

1377

1378

# Add Apex-specific directories and set ownership as the Apex admin user

1379

RUN mkdir -p /opt/app/policy/apex-pdp

1380

RUN mkdir -p /var/log/onap/policy/apex-pdp

1381

RUN chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp

# Unpack the tarball

RUN mkdir /packages

COPY apex-pdp-package-full.tar.gz /packages

1386

RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory /opt/app/policy/apex-pdp

1387

RUN rm /packages/apex-pdp-package-full.tar.gz

1388

1389

# Ensure everything has the correct permissions

1390

RUN find /opt/app -type d -perm 755

1391

RUN find /opt/app -type f -perm 644

1392

RUN chmod a+x /opt/app/policy/apex-pdp/bin/*

1393

1394

# Copy examples to Apex user area

1395

RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser

RUN apt-get clean

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

1400

1401

USER apexuser

1402

ENV PATH /opt/app/policy/apex-pdp/bin:$PATH

1403

WORKDIR /home/apexuser

.. container::

:name: footer

.. container::

:name: footer-text

2.0.0-SNAPSHOT

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

1413

1414

.. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png

1415

.. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png

1416

.. |REST Editor Start Screen| image:: images/install-guide/rest-start.png

1417

.. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png

1418