diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/install-guide')
10 files changed, 171 insertions, 483 deletions
diff --git a/src/site-docs/adoc/fragments/install-guide/build-apex.adoc b/src/site-docs/adoc/fragments/install-guide/build-apex.adoc index b773d97bd..8676d8f29 100644 --- a/src/site-docs/adoc/fragments/install-guide/build-apex.adoc +++ b/src/site-docs/adoc/fragments/install-guide/build-apex.adoc @@ -15,9 +15,17 @@ The examples in this document assume that the APEX source repositories are cloned to: -- Unix, Cygwin: `/usr/local/src/apex` -- Windows: `C:\dev\apex` -- Cygwin: `/cygdrive/c/dev/apex` +- 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: link:https://git.onap.org/oparent/plain/settings.xml[Settings]. +==== [IMPORTANT] .A Build needs Space @@ -47,14 +55,14 @@ Use Maven to for a standard build without any tests. | [source%nowrap,sh,numbered] ---- -# cd /usr/local/src/apex +# cd /usr/local/src/apex-pdp # mvn clean install -DskipTests ---- | [source%nowrap,bat,numbered] ---- >c: ->cd \dev\apex +>cd \dev\apex-pdp >mvn clean install -DskipTests ---- |==================== @@ -79,7 +87,7 @@ The following example show how to change to the target directory and how it shou | [source%nowrap,sh,numbered] ---- -# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# cd packages/apex-pdp-package-full/target # ls -l ---- @@ -98,7 +106,7 @@ include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[s | [source%nowrap,bat,numbered] ---- ->cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>cd packages\apex-pdp-package-full\target >dir ---- diff --git a/src/site-docs/adoc/fragments/install-guide/configure.adoc b/src/site-docs/adoc/fragments/install-guide/configure.adoc index 77c63a29a..97388f8f7 100644 --- a/src/site-docs/adoc/fragments/install-guide/configure.adoc +++ b/src/site-docs/adoc/fragments/install-guide/configure.adoc @@ -56,14 +56,14 @@ The last row explains how to set those variables permanently. [source%nowrap,bash,numbered] ---- # export APEX_USER=apexuser -# cd /opt/ericsson/apex/apex +# cd /opt/app/policy/apex-pdp/apex-pdp # export APEX_HOME=`pwd` ---- [source%nowrap,tcsh,numbered] ---- # setenv APEX_USER apexuser -# cd /opt/ericsson/apex/apex +# cd /opt/app/policy/apex-pdp/apex-pdp # setenv APEX_HOME `pwd` ---- | @@ -77,7 +77,7 @@ The last row explains how to set those variables permanently. ---- # env \| grep APEX APEX_USER=apexuser -APEX_HOME=/opt/ericsson/apex/apex +APEX_HOME=/opt/app/policy/apex-pdp/apex-pdp ---- | [source%nowrap,bat,numbered,subs="attributes+"] @@ -125,7 +125,7 @@ Configure the APEX logging settings to your requirements, for instance: Edit the file `$APEX_HOME/etc/logback.xml` for any required changes. To change the log directory change the line -`<property name="VAR_LOG" value="/var/log/ericsson/apex/" />` +`<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />` to @@ -148,8 +148,8 @@ This is important when APEX was installed manually or when the log directory was | [source%nowrap,sh,numbered] ---- -mkdir -p /var/log/ericsson/apex -chown -R apexuser:apexuser /var/log/ericsson/apex +mkdir -p /var/log/onap/policy/apex-pdp +chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp ---- | [source%nowrap,bat,numbered,subs="attributes+"] diff --git a/src/site-docs/adoc/fragments/install-guide/docker.adoc b/src/site-docs/adoc/fragments/install-guide/docker.adoc index be5273a48..6f63956aa 100644 --- a/src/site-docs/adoc/fragments/install-guide/docker.adoc +++ b/src/site-docs/adoc/fragments/install-guide/docker.adoc @@ -13,248 +13,32 @@ == Running APEX in Docker -This section explains how to create a Docker image that contains the base APEX package and shows how to run APEX in Docker. -It also explains how to use the base APEX Docker image to create application docker images that contain both APEX and your application policies. +Since APEX is in ONAP, we provide a full virtualization environment for the engine. -We assume you have already installed Docker on your host. -For instructions on how to install Docker, see the link:https://www.docker.com/community-edition[Get Started with Docker] page on the Docker web site. +=== Run in ONAP -=== Create the APEX Base Docker Image +Running APEX from the ONAP docker repository only requires 2 commands: -You need only perform this task once to create an APEX base image that you can use as a base for your applications from then on. -This task sets up an Ubuntu Docker image and then installs Java and APEX on Ubuntu running in the Docker image. - -. Create an empty directory, here the directory is called `apex`, and change into that directory -+ -[source%nowrap,bash,numbered] ----- -# mkdir apex -# cd apex +. Log into the ONAP docker repo +[source%nowrap,sh,numbered] ---- -+ -. Copy the APEX Debian package from the APEX download site into the directory -. Open a text editor and create a file called `Dockerfile` in your directory -. Paste the following text into the editor that is editing `Dockerfile` -+ -[source%nowrap,bash,numbered,subs="attributes+"] +docker login -u docker -p docker nexus3.onap.org:10003 ---- -# -# Docker file to build an image that runs APEX on Java 8 in Ubuntu -# -FROM ubuntu:16.04 -MAINTAINER <YOUR> <NAME> <YOUR>.<NAME>@ericsson.com - -RUN apt-get update && \ - apt-get upgrade -y && \ - apt-get install -y software-properties-common && \ - add-apt-repository ppa:webupd8team/java -y && \ - apt-get update && \ - echo oracle-javax8-installer shared/accepted-oracle-license-v1-1 select true | /usr/bin/debconf-set-selections && \ - apt-get install -y oracle-java8-installer - -RUN mkdir /packages -COPY apex-apps.uservice-packages-{release-version}-full.deb /packages -RUN dpkg -i packages/apex-apps.uservice-packages-{release-version}-full.deb -RUN rm /packages/apex-apps.uservice-packages-{release-version}-full.deb - -ENV PATH /opt/ericsson/apex/apex/bin:$PATH - -RUN apt-get clean - -RUN chown -R apexuser:apexuser /home/apexuser/* -WORKDIR /home/apexuser - +. Run the APEX docker image +[source%nowrap,sh,numbered] ---- -+ -. Replace the fields <YOUR> and <NAME> above with your name and email address -. Save the `Dockerfile` -. An example working base `Dockerfile` appears below -+ -[source%nowrap,bash,numbered,subs="attributes+"] +docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest ---- -# -# Docker file to build an image that runs APEX on Java 8 in Ubuntu -# -FROM ubuntu:16.04 -MAINTAINER Sean Citizen sean.citizen@ericsson.com -RUN apt-get update && \ - apt-get upgrade -y && \ - apt-get install -y software-properties-common && \ - add-apt-repository ppa:webupd8team/java -y && \ - apt-get update && \ - echo oracle-javax8-installer shared/accepted-oracle-license-v1-1 select true | /usr/bin/debconf-set-selections && \ - apt-get install -y oracle-java8-installer -RUN mkdir /packages -COPY apex-apps.uservice-packages-{release-version}-full.deb /packages -RUN dpkg -i packages/apex-apps.uservice-packages-{release-version}-full.deb -RUN rm /packages/apex-apps.uservice-packages-{release-version}-full.deb +=== Build a Docker Image -ENV PATH /opt/ericsson/apex/apex/bin:$PATH +Alternatively, one can use the Dockerfile defined in the Docker package to build an image. -RUN apt-get clean - -RUN chown -R apexuser:apexuser /home/apexuser/* -WORKDIR /home/apexuser ----- -+ -. Create and tag the base Docker image for APEX using this command -+ -[source%nowrap,bash,numbered] ----- -docker build -t apex/base . -docker tag apex/base apex/base:latest -docker tag apex/base apex/base:{release-version} ----- -+ -. Test the APEX Docker base image with the following command, APEX will start a sample policy: -+ -[source%nowrap,bash,numbered] ----- -docker run --name apex --user=apexuser:apexuser -it --rm -p 12345:12345 apex/base apexEngine.sh -c examples/config/SampleDomain/Stdin2StdoutJsonEventJavascript.json ----- -+ -. Paste the following event into the shell and the APEX Policy will process the event -+ -[source%nowrap,json,numbered] ----- -{ - "nameSpace": "org.onap.policy.apex.sample.events", - "name": "Event0000", - "version": "0.0.1", - "source": "test", - "target": "apex", - "TestSlogan": "Test slogan for External Event0", - "TestMatchCase": 0, - "TestTimestamp": 1469781869269, - "TestTemperature": 9080.866 -} ----- -+ -. APEX returns the following event -+ -[source%nowrap,json,numbered] ----- -{ - "nameSpace" : "org.onap.policy.apex..sample.events", - "name" : "Event0004", - "version" : "0.0.1", - "source" : "", - "target" : "", - "TestActCaseSelected" : 3, - "TestActStateTime" : 1481215910429, - "TestTemperature" : 9080.866, - "TestDecideCaseSelected" : 1, - "TestMatchCaseSelected" : 2, - "TestTimestamp" : 1469781869269, - "TestDecideStateTime" : 1481215910425, - "TestMatchCase" : 0, - "TestSlogan" : "Test slogan for External Event0", - "TestEstablishCaseSelected" : 0, - "TestEstablishStateTime" : 1481215910421, - "TestMatchStateTime" : 1481215910415 -} ----- -+ -. You now have built and tested an APEX base Docker image. - You can connect the APEX Deployment and Monitoring servlet to this APEX engine instance. For example, assuming the APEX Deployment and Monitoring servlet is deploying on the localhost computer on port 8080 you can use the following URL: -+ ----- -http://localhost:8080/apex-services.client-{release-version}/?hostname=0.0.0.0&port=12345 ----- - -=== Create an APEX Application Docker Image using the APEX Base Docker Image - -We assume you have created an APEX application, that you wish to use static deployment, and that you have APEX metadata to add to the base APEX Docker image. - -. 1.Create an empty directory for your application, here the directory is called `myApplication`, and change into that directory -+ -[source%nowrap,bash,numbered] ----- -mkdir myApplication -cd myApplication ----- -+ -. Copy the directories containing your application metadata into that directory, for example, if you have three directories called `myappDirectory0`, `myappDirectory1`, and `myappDirectoryn`, you will have the following directory structure -+ -[source%nowrap,bash,numbered] ----- -ls | cat -myappDirectory0 -myappDirectory1 -myappDirectoryn ----- -+ -. Open a text editor and create a file called `Dockerfile` in your application directory -. Paste the following text into the editor that is editing `Dockerfile` -+ -[source%nowrap,bash,numbered] ----- -# -# Docker file to build an image that runs APEX Applications on Java 8 in Ubuntu -# -FROM apex/base:{release-version} -MAINTAINER <YOUR> <NAME> <YOUR>.<NAME>@ericsson.com - -# Copy your application metadata -COPY <MY_APP_DIRECTORY_0> /home/apexuser/<MY_APP_DIRECTORY_0> -COPY <MY_APP_DIRECTORY_1> /home/apexuser/<MY_APP_DIRECTORY_1> -COPY <MY_APP_DIRECTORY_N> /home/apexuser/<MY_APP_DIRECTORY_N> - -run chown -R apexuser:apexuser /home/apexuser/* ----- -+ -. Edit the template fields - .. Replace the fields <YOUR> and <NAME> with your name and email address - .. Replace the <MY_APP_DIRECTORY_x> fields with the names of your actual application directory names, myappDirectoryx in our example here. Do this for all application directories you have. -. Save the `Dockerfile` -. An example working application `Dockerfile` appears below -+ -[source%nowrap,bash,numbered] ----- -# -# Docker file to build an image that runs APEX Applications on Java 8 in Ubuntu -# -FROM apex/base:{release-version} -MAINTAINER Sean Citizen sean.citizen@ericsson.com - -# Copy your application metadata -COPY myappDirectory0 /home/apexuser/myappDirectory0 -COPY myappDirectory1 /home/apexuser/myappDirectory1 -COPY myappDirectoryn /home/apexuser/myappDirectoryn - -run chown -R apexuser:apexuser /home/apexuser/* ----- -+ -. Create the Docker image for your APEX application using this command -+ -[source%nowrap,bash,numbered] ----- -docker build -t apex/myapplication . ----- -+ -. Test the APEX Docker base image with the following command, APEX will start to a bash shell in the `apexuser` home directory: -+ -[source%nowrap,bash,numbered] ----- -docker run --name myapplication -it --rm -p 12345:12345 apex/myapplication apexBash.sh ----- -+ -. Check that your application directories have been created, the command returns the directory list: -+ -[source%nowrap,bash,numbered] +.APEX Dockerfile +[source%nowrap,sh,numbered,subs="attributes+"] ---- -> pwd -/opt/ericsson -> ls -l -total 16 -drwxr-xr-x 8 apexuser apexuser 4096 Dec 9 13:28 examples -drwxr-xr-x 2 apexuser apexuser 4096 Dec 9 13:28 myappDirectory0 -drwxr-xr-x 2 apexuser apexuser 4096 Dec 9 13:28 myappDirectory1 -drwxr-xr-x 2 apexuser apexuser 4096 Dec 9 13:28 myappDirectoryn +include::{adsite-packages-docker-dir}/main/docker/Dockerfile[APEX Dockerfile] ---- -+ -. You now have built an APEX Application docker image and you can use the `apexEngine.sh` command to run your application using the appropriate configuration file for your application. diff --git a/src/site-docs/adoc/fragments/install-guide/get-source.adoc b/src/site-docs/adoc/fragments/install-guide/get-source.adoc index 11786da4e..0aa97db1e 100644 --- a/src/site-docs/adoc/fragments/install-guide/get-source.adoc +++ b/src/site-docs/adoc/fragments/install-guide/get-source.adoc @@ -12,16 +12,16 @@ // == Get the APEX Source Code -The APEX source code is hosted in as project on Github link:https://github.com/Ericsson/apex[Ericsson:apex]. + +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. + +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 Github using either HTTPS (first example below) or SSH (second example below). +Simply clone the master branch from ONAP using HTTPS. [source%nowrap,sh,numbered] ---- -git clone https://github.com/Ericsson/apex.git +git clone https://gerrit.onap.org/r/policy/apex-pdp ---- -[source%nowrap,sh,numbered] ----- -git clone git@github.com:Ericsson/apex.git ----- diff --git a/src/site-docs/adoc/fragments/install-guide/install-monitoring.adoc b/src/site-docs/adoc/fragments/install-guide/install-monitoring.adoc deleted file mode 100644 index a8bf3d4f1..000000000 --- a/src/site-docs/adoc/fragments/install-guide/install-monitoring.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// -// ============LICENSE_START======================================================= -// Copyright (C) 2016-2018 Ericsson. All rights reserved. -// ================================================================================ -// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE -// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode -// -// SPDX-License-Identifier: CC-BY-4.0 -// ============LICENSE_END========================================================= -// -// @author Sven van der Meer (sven.van.der.meer@ericsson.com) -// - -== Installing the Web Monitoring Application - -APEX comes with a deployment and monitoring application realized as a servlet. -This requires a _full_ installation of APEX. -This requires a web server that can execute `war` web archives. -We recommend to use link:https://tomcat.apache.org/[Apache Tomcat], however other web servers can be used as well. - -Install Apache Tomcat including the `Manager App`, see link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access[V9.0 Docs] for details. -Start the Tomcat service, or make sure that Tomcat is running. -Locate the APEX monitoring application. - -[source%nowrap,sh,numbered,subs="attributes+"] ----- -$APEX_HOME/war/apex-services.client.monitoring-{release-version}.war ----- - -[source%nowrap,bat,numbered,subs="attributes+"] ----- -%APEX_HOME%\war\apex-services.client.monitoring-{release-version}.war ----- - -There are multiple ways to install the APEX monitoring application: - -- 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 - -For details on how to install `war` files please consult the link:https://tomcat.apache.org/tomcat-9.0-doc/index.html[Tomcat Documentation] or the link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html[Manager App HOW-TO]. -Once you installed the APEX monitoring application (and wait for sufficient time for Tomcat to finalize the installation), open the `Manager App` in Tomcat. -You should see the APEX monitoring application being installed and running. - -image::install-guide/tomcat-installed.png[Tomcat Application Manager with APEX Monitoring Application] - -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. - -Once the APEX monitoring application is installed, start an APEX engine with the `SampleDomain` configuration as described above. -Wait until the engine is fully started. -Then open a browser (or a new tab) and use the following URL to connect to the APEX monitoring application. -Change the values for the Tomcat port (`10080` in the example), the APEX application version (`{release-version}` in the example), and the APEX management port (`12345` in the example, taken from the example configuration) to your local settings. -If your browser is not opened on the same host as the APEX engine runs, change `localhost` to the host name with the APEX engine. - -[source%nowrap,url,subs="attributes+"] ----- -http://localhost:10080/apex-services.client-{release-version}/?hostname=localhost&port=12345 ----- - -The browser will now show the APEX monitoring application. - -image::install-guide/monitoring-app.png[APEX Monitoring and Deployment Application] - -Now send some events to the APEX engine. -The configuration is for standard input, so simply paste the following event into the APEX engine console. - -[source%nowrap,json,numbered] ----- -{ - "nameSpace": "org.onap.policy.apex.sample.events", - "name": "Event0000", - "version": "0.0.1", - "source": "test", - "target": "apex", - "TestSlogan": "Test slogan for External Event0", - "TestMatchCase": 0, - "TestTimestamp": 1469781869269, - "TestTemperature": 9080.866 -} ----- - -When events are sent to APEX, the monitoring application will show all engine status changes. -The following screen shot show the engine status after passing several events into the engine. - -image::install-guide/monitoring-app-status.png[APEX Monitoring: status] - -To terminate this setting, first use `CTRL+C` in the engine console to terminate the engine. -Within a few seconds, the APEX monitoring application will terminate as well with a connection error: - ----- -Error connecting to Apex Engine Service at localhost:12345 -cound not handshake with server localhost:12345 -See detailed message in log ----- - -Terminate the browser now (or the tab with the application). -Finally, if you do not want to use Tomcat for any other applications, terminate the Tomcat server as well. - diff --git a/src/site-docs/adoc/fragments/install-guide/install-resteditor.adoc b/src/site-docs/adoc/fragments/install-guide/install-resteditor.adoc deleted file mode 100644 index 721ede0a9..000000000 --- a/src/site-docs/adoc/fragments/install-guide/install-resteditor.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// -// ============LICENSE_START======================================================= -// Copyright (C) 2016-2018 Ericsson. All rights reserved. -// ================================================================================ -// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE -// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode -// -// SPDX-License-Identifier: CC-BY-4.0 -// ============LICENSE_END========================================================= -// -// @author Sven van der Meer (sven.van.der.meer@ericsson.com) -// - -== Installing the REST Editor - -APEX comes with a RESR Editor application realized as a servlett. -This requires a _full_ installation of APEX. -This requires a web server that can execute `war` web archives. -We recommend to use link:https://tomcat.apache.org/[Apache Tomcat], however other web servers can be used as well. - -Install Apache Tomcat including the `Manager App`, see link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access[V9.0 Docs] for details. -Start the Tomcat service, or make sure that Tomcat is running. -Locate the APEX monitoring application in your local APEX installation. - -[source%nowrap,sh,numbered,subs="attributes+"] ----- -$APEX_HOME/war/apex-services.client-editor-{release-version}.war ----- - -[source%nowrap,bat,numbered,subs="attributes+"] ----- -%APEX_HOME%\war\apex-services.client-editor-{release-version}.war ----- - -There are multiple ways to install the APEX monitoring application: - -- 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 - -For details on how to install `war` files please consult the link:https://tomcat.apache.org/tomcat-9.0-doc/index.html[Tomcat Documentation] or the link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html[Manager App HOW-TO]. -Once you installed the APEX monitoring application (and wait for sufficient time for Tomcat to finalize the installation), open the `Manager App` in Tomcat. -You should see the APEX REST Editor application being installed and running. - -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. - -Once the APEX REST Editor is installed, open a browser (or a new tab) and use the following URL to connect to the APEX monitoring application. -Change the values for the Tomcat port (`10080` in the example), the APEX REST EDITOR version (`{release-version}` in the example), and the APEX management port (`12345` in the example, taken from the example configuration) to your local settings. -If your browser is not opened on the same host as the APEX engine runs, change `localhost` to the host name with the APEX engine. - -[source%nowrap,url,subs="attributes+"] ----- -http://localhost:10080/apex%2Dauth.rest%2D{release-version}/ ----- - -The browser will now show the APEX REST Editor. - -Terminate the browser now (or the tab with the application). -Finally, if you do not want to use Tomcat for any other applications, terminate the Tomcat server as well. diff --git a/src/site-docs/adoc/fragments/install-guide/install-wars.adoc b/src/site-docs/adoc/fragments/install-guide/install-wars.adoc new file mode 100755 index 000000000..2de1e0b89 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/install-wars.adoc @@ -0,0 +1,46 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Installing WAR Applications +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). + +Installing and using the WAR applications requires a web server that can execute `war` web archives. +We recommend to use link:https://tomcat.apache.org/[Apache Tomcat], however other web servers can be used as well. + +Install Apache Tomcat including the `Manager App`, see link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access[V9.0 Docs] for details. +Start the Tomcat service, or make sure that Tomcat is running. + +There are multiple ways to install the APEX WAR applications: + +- 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 + +For details on how to install `war` files please consult the link:https://tomcat.apache.org/tomcat-9.0-doc/index.html[Tomcat Documentation] or the link:https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html[Manager App HOW-TO]. +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. + +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. + +The current APEX version provides the following WAR applications: + +* client-deployment-{release-version}.war - a client to deploy new policy models to a running engine +* client-editor-{release-version}.war - the standard policy REST editor GUI +* client-monitoring-{release-version}.war - a client for monitoring a running APEX engine +* client-full-{release-version}.war - a full client with a one-stop-access to deployment, monitoring, and REST editor +* examples-servlet-{release-version}.war - an example APEX servlet + diff --git a/src/site-docs/adoc/fragments/install-guide/install.adoc b/src/site-docs/adoc/fragments/install-guide/install.adoc index a1e95347a..57d78739e 100644 --- a/src/site-docs/adoc/fragments/install-guide/install.adoc +++ b/src/site-docs/adoc/fragments/install-guide/install.adoc @@ -21,9 +21,9 @@ APEX can be installed in different ways: === Install with RPM and DPKG The install distributions of APEX automatically install the system. -The installation directory is `/opt/ericsson/apex`. -Log files are located in `/var/log/ericsson/apex`. -The latest APEX version will be available as `/opt/ericsson/apex/apex`. +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`. 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. @@ -35,7 +35,7 @@ The user is also used by the standard APEX start scripts to run APEX with this u | [source%nowrap,sh,numbered,subs="attributes+"] ---- -# sudo rpm -i apex-apps.uservice-packages-{release-version}-full.rpm +# sudo rpm -i apex-pdp-package-full-{release-version}.rpm ********************preinst******************* arguments 1 ********************************************** @@ -54,10 +54,10 @@ arguments 1 | [source%nowrap,sh,numbered,subs="attributes+"] ---- -# sudo dpkg -i apex-apps.uservice-packages-{release-version}-full.deb +# sudo dpkg -i apex-pdp-package-full-{release-version}.deb Selecting previously unselected package apex-uservice. (Reading database ... 288458 files and directories currently installed.) -Preparing to unpack apex-apps.uservice-packages-{release-version}-full.deb ... +Preparing to unpack apex-pdp-package-full-{release-version}.deb ... ********************preinst******************* arguments install ********************************************** @@ -86,8 +86,8 @@ The following example shows how to install APEX in `/opt/apex` and create a link # mkdir apex # cd apex # mkdir apex-full-{release-version} -# tar xvfz ~/Downloads/apex-apps.uservice-packages-{release-version}-full.tar.gz -C apex-full-{release-version} -# ln -s apex apex-apps.uservice-packages-{release-version} +# tar xvfz ~/Downloads/apex-pdp-package-full-{release-version}.tar.gz -C apex-full-{release-version} +# ln -s apex apex-pdp-package-full-{release-version} ---- @@ -104,8 +104,6 @@ image::install-guide/win-extract-tar.png[Extract the APEX distribution] Inside the new APEX folder you see the main directories: `bin`, `etc`, `examples`, `lib`, and `war` -image::install-guide/win-extracted.png[Extracted APEX distribution] - Once extracted, please rename the created folder to `apex-full-{release-version}`. This will keep the directory name in line with the rest of this documentation. @@ -119,7 +117,7 @@ Assuming `7Zip` is installed in the standard folder, simply run the following co ---- >c: >cd \apex ->"\Program Files\7-Zip\7z.exe" x apex-apps.uservice-packages-{release-version}-full.tar.gz -so | "\Program Files\7-Zip\7z.exe" x -aoa -si -ttar -o"apex-full-{release-version}" +>"\Program Files\7-Zip\7z.exe" x apex-pdp-package-full-{release-version}.tar.gz -so | "\Program Files\7-Zip\7z.exe" x -aoa -si -ttar -o"apex-full-{release-version}" ---- APEX is now installed in the folder `C:\apex\apex-full-{release-version}`. @@ -188,7 +186,7 @@ The following example show how to change to the target directory and how it shou | [source%nowrap,sh,numbered] ---- -# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# cd packages/apex-pdp-package-full/target # ls -l ---- @@ -208,7 +206,7 @@ include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[s | [source%nowrap,bat,numbered] ---- ->cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>cd packages\apex-pdp-package-full\target >dir ---- diff --git a/src/site-docs/adoc/fragments/install-guide/layout.adoc b/src/site-docs/adoc/fragments/install-guide/layout.adoc index ef3d1cf5b..bbb21021f 100644 --- a/src/site-docs/adoc/fragments/install-guide/layout.adoc +++ b/src/site-docs/adoc/fragments/install-guide/layout.adoc @@ -17,8 +17,8 @@ A full installation of APEX comes with the following layout. ---- $APEX_HOME - ├───bin <1> - ├───etc <2> + ├───bin <1> + ├───etc <2> │ ├───editor │ ├───hazelcast │ ├───infinispan @@ -27,11 +27,13 @@ $APEX_HOME │ ├───config <4> │ ├───docker <5> │ ├───events <6> - │ ├───models <7> - │ └───scripts <8> - ├───lib <9> - │ └───applications <10> - └───war <11> + │ ├───html <7> + │ ├───models <8> + │ └───scripts <9> + ├───lib <10> + │ └───applications <11> + └───war <12> + ---- <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 @@ -39,9 +41,10 @@ $APEX_HOME <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> the policy models, generated for each example (with sub directories for individual examples) -<8> additional scripts for the examples (with sub directories for individual examples) -<9> the library folder with all Java JAR files -<10> applications, also known as jar with dependencies (or fat jars), individually deployable -<11> WAR files for web applications +<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 diff --git a/src/site-docs/adoc/fragments/install-guide/verify.adoc b/src/site-docs/adoc/fragments/install-guide/verify.adoc index 782c2723e..6774a8489 100644 --- a/src/site-docs/adoc/fragments/install-guide/verify.adoc +++ b/src/site-docs/adoc/fragments/install-guide/verify.adoc @@ -14,13 +14,10 @@ == Verify the APEX Installation When APEX is installed and all settings are realized, the installation can be verified. -=== Verify a Minimal Installation -The minimal installation does not come with any configuration or policy model. -It is therefore not possible to test all APEX features, or an engine running with policies. - -However, one can verify that the engine starts up to the point where it tries to load a configuration. - +=== Verify Installation - run Engine +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. @@ -28,22 +25,26 @@ However, if the output looks similar to the following line, the APEX installatio ---- Starting Apex service with parameters [] . . . start of Apex service failed: Apex configuration file was not specified as an argument -2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed: ----- +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 -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. - -[source%nowrap,bat,numbered] ----- -Starting Apex service with parameters [] . . . -start of Apex service failed: Apex configuration file was not specified as an argument -2017-07-28 13:18:44,266 Apex [main] ERROR c.e.a.service.engine.main.ApexMain - start of Apex service failed: ---- -=== Verify a Full Installation - run an Example + +=== Verify Installation - run an Example A full APEX installation comes with several examples. Here, we can fully verify the installation by running one of the examples. @@ -55,7 +56,7 @@ Note: Cygwin executes scripts as Unix scripts but runs Java as a Windows applica ---- # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <1> # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-{release-version}/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json # <2> ->%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json @@ <3> +>%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: <3> ---- <1> UNIX <2> Cygwin @@ -67,12 +68,19 @@ Assuming the logging levels are not change (default level is `info`), the output [source%nowrap,sh,numbered] ---- -2017-07-28 13:20:54,673 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model SamplePolicyModelJAVA:0.0.1 added to the engine-AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) -2017-07-28 13:20:54,675 Apex [Apex-apex-engine-service-0:0] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-0,version=0.0.1) processing ... -2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:1] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-1,version=0.0.1) processing ... -2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:2] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-2,version=0.0.1) processing ... -2017-07-28 13:20:54,677 Apex [Apex-apex-engine-service-0:3] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=MyApexEngine-3,version=0.0.1) processing ... -2017-07-28 13:20:54,680 Apex [main] INFO c.e.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine +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 ---- @@ -107,23 +115,23 @@ Pasting the input event multiple times will produce output events with different [source%nowrap,json,numbered] ---- { - "nameSpace" : "org.onap.policy.apex.sample.events", - "name" : "Event0004", - "version" : "0.0.1", - "source" : "Act", - "target" : "Outside", - "TestActCaseSelected" : 1, - "TestActStateTime" : 1499280954832, - "TestTemperature" : 9080.866, - "TestDecideCaseSelected" : 2, - "TestMatchCaseSelected" : 2, - "TestTimestamp" : 1469781869269, - "TestDecideStateTime" : 1499280954831, - "TestMatchCase" : 0, - "TestSlogan" : "Test slogan for External Event0", - "TestEstablishCaseSelected" : 1, - "TestEstablishStateTime" : 1499280954831, - "TestMatchStateTime" : 1499280954828 + "name": "Event0004", + "version": "0.0.1", + "nameSpace": "org.onap.policy.apex.sample.events", + "source": "Act", + "target": "Outside", + "TestActCaseSelected": 2, + "TestActStateTime": 1536157104627, + "TestDecideCaseSelected": 0, + "TestDecideStateTime": 1536157104625, + "TestEstablishCaseSelected": 0, + "TestEstablishStateTime": 1536157104623, + "TestMatchCase": 0, + "TestMatchCaseSelected": 1, + "TestMatchStateTime": 1536157104620, + "TestSlogan": "Test slogan for External Event0", + "TestTemperature": 9080.866, + "TestTimestamp": 1469781869269 } ---- |==================== @@ -147,20 +155,20 @@ Start the REST editor as follows. ---- The script will start a simple web server (link:https://javaee.github.io/grizzly/[Grizzly]) and deploy a `war` web archive in it. -Once the editor is started, it will be available on `localhost:18988`. +Once the editor is started, it will be available on `localhost:18989`. The last few line of the messages should be: [source%nowrap,sh,numbered] ---- -Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18988/apex/, TTL=-1sec], State=READY) starting at http://localhost:18988/apex/ . . . -Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.NetworkListener start -INFO: Started listener bound to [localhost:18988] -Jul 28, 2017 1:22:15 PM org.glassfish.grizzly.http.server.HttpServer start +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:18988/apex/, TTL=-1sec], State=RUNNING) started at http://localhost:18988/apex/ +Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ ---- -Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and use the URL `http://localhost:18988/`. +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. |