diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/install-guide')
10 files changed, 1223 insertions, 0 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 new file mode 100644 index 000000000..b773d97bd --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/build-apex.adoc @@ -0,0 +1,112 @@ +// +// ============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) +// + +== Build APEX + +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` + +[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. +==== + +Use Maven to for a standard build without any tests. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DskipTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DskipTests +---- +|==================== + +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. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, no tests] +---- + + +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. + +[width="100%",options="header",cols="a"] +|==================== +| Unix, Cygwin +| +[source%nowrap,sh,numbered] +---- +# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# ls -l +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[successful build, ls, unix] +---- + +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| Windows +| +[source%nowrap,bat,numbered] +---- +>cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>dir +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-win.txt[successful build, ls, windows] +---- + +|==================== + diff --git a/src/site-docs/adoc/fragments/install-guide/configure.adoc b/src/site-docs/adoc/fragments/install-guide/configure.adoc new file mode 100644 index 000000000..77c63a29a --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/configure.adoc @@ -0,0 +1,160 @@ +// +// ============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) +// + +== System Configuration +Once APEX is installed, a few configurations need to be done: + +- 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 +On smaller installations and test systems, APEX can run as any user or group. + +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. + +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. + +[source%nowrap,sh,numbered] +---- +# sudo groupadd apexuser +# sudo useradd -g apexuser apexuser +# sudo chwon -R apexuser:apexuser <apex-dir> +---- + +For other operating systems please consult your manual or system administrator. + + +=== Environment Settings: APEX_HOME and APEX_USER +The provided start scripts for APEX require two environment variables being set: + +- `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) + +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. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin (bash/tcsh) | Windows +| +[source%nowrap,bash,numbered] +---- +# export APEX_USER=apexuser +# cd /opt/ericsson/apex/apex +# export APEX_HOME=`pwd` +---- + +[source%nowrap,tcsh,numbered] +---- +# setenv APEX_USER apexuser +# cd /opt/ericsson/apex/apex +# setenv APEX_HOME `pwd` +---- +| +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>set APEX_HOME=C:\apex\apex-full-{release-version} +---- + +| +[source%nowrap,sh,numbered] +---- +# env \| grep APEX +APEX_USER=apexuser +APEX_HOME=/opt/ericsson/apex/apex +---- +| +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>set APEX_HOME +APEX_HOME=\apex\apex-full-{release-version} +---- + +|==================== + + +==== Making Environment Settings Permanent (Unix, Cygwin) +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) +On Windows 7 do + +- Click on the *Start* Menu +- Right click on *Computer* +- Select *Properties* + +On Windows 8/10 do + +- Click on the *Start* Menu +- Select *System* + +Then do the following + +- 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-{release-version}" + +For the settings to take effect, an application needs to be restarted (e.g. any open `cmd` window). + + + +=== Edit the APEX Logging Settings +Configure the APEX logging settings to your requirements, for instance: + +- change the directory where logs are written to, or +- change the log levels + +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/" />` + +to + +`<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />` + +On Windows, it is recommended to change the log directory to: + +`<property name="VAR_LOG" value="C:/apex/apex-full-{release-version}/logs" />` + +Note: Be careful about when to use `\` vs. `/` as the path separator! + + +=== Create Directories for Logging +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). + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +mkdir -p /var/log/ericsson/apex +chown -R apexuser:apexuser /var/log/ericsson/apex +---- +| +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>mkdir C:\apex\apex-full-{release-version}\logs +---- +|==================== + diff --git a/src/site-docs/adoc/fragments/install-guide/docker.adoc b/src/site-docs/adoc/fragments/install-guide/docker.adoc new file mode 100644 index 000000000..be5273a48 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/docker.adoc @@ -0,0 +1,260 @@ +// +// ============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) +// + +== 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. + +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. + + +=== Create the APEX Base Docker Image + +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 +---- ++ +. 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 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 + +---- ++ +. 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 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 + +ENV PATH /opt/ericsson/apex/apex/bin:$PATH + +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] +---- +> 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 +---- ++ +. 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 new file mode 100644 index 000000000..11786da4e --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/get-source.adoc @@ -0,0 +1,27 @@ +// +// ============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) +// + +== 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 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). + +[source%nowrap,sh,numbered] +---- +git clone https://github.com/Ericsson/apex.git +---- + +[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 new file mode 100644 index 000000000..a8bf3d4f1 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/install-monitoring.adoc @@ -0,0 +1,99 @@ +// +// ============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 new file mode 100644 index 000000000..721ede0a9 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/install-resteditor.adoc @@ -0,0 +1,60 @@ +// +// ============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.adoc b/src/site-docs/adoc/fragments/install-guide/install.adoc new file mode 100644 index 000000000..a1e95347a --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/install.adoc @@ -0,0 +1,226 @@ +// +// ============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) +// + +== Install APEX +APEX can be installed in different ways: + +- 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 +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`. + +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. + +[width="100%",options="header",cols="a"] +|==================== +| RPM Installation +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# sudo rpm -i apex-apps.uservice-packages-{release-version}-full.rpm +********************preinst******************* +arguments 1 +********************************************** +creating group apexuser . . . +creating user apexuser . . . +********************postinst**************** +arguments 1 +*********************************************** +---- +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| DPKG Installation +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# sudo dpkg -i apex-apps.uservice-packages-{release-version}-full.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 ... +********************preinst******************* +arguments install +********************************************** +creating group apexuser . . . +creating user apexuser . . . +Unpacking apex-uservice ({release-version}) ... +Setting up apex-uservice ({release-version}) ... +********************postinst**************** +arguments configure +*********************************************** +---- +|==================== + +Once the installation is finished, APEX is fully installed and ready to run. + + +=== Install Manually from Archive (Unix, Cygwin) +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. + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# cd /opt +# 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} +---- + + +=== Install Manually from Archive (Windows, 7Zip, GUI) +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. + +image::install-guide/win-extract-tar-gz.png[Extract the TAR archive] + +The right-click on the new created TAR file and extract the actual APEX distribution. + +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. + + +=== Install Manually from Archive (Windows, 7Zip, CMD) +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 {release-version} full distribution) + +[source%nowrap,bat,numbered,subs="attributes+"] +---- +>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}" +---- + +APEX is now installed in the folder `C:\apex\apex-full-{release-version}`. + + + +== Build from Source + +=== Build and Install Manually (Unix, Windows, Cygwin) +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. +==== + +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: + +- Unix, Cygwin: `/usr/local/src/apex` +- Windows: `C:\dev\apex` + + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Unix, Cygwin | Windows +| +[source%nowrap,sh,numbered] +---- +# cd /usr/local/src/apex +# mvn clean install -DskipTests +---- +| +[source%nowrap,bat,numbered] +---- +>c: +>cd \dev\apex +>mvn clean install -DskipTests +---- +|==================== + +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. + +When Maven is finished with the build, the final screen should look similar to this (omitting some `success` lines): + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/mvn-install-skiptests.txt[mvn build, no tests] +---- + + +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. + +[width="100%",options="header",cols="a"] +|==================== +| Unix, Cygwin +| +[source%nowrap,sh,numbered] +---- +# cd modules/apex-apps/apex-apps.uservice/apex-apps.uservice-packaging/apex-apps.uservice-package-full/target +# ls -l +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-unix.txt[successful build, ls, unix] +---- + + +|==================== + + +[width="100%",options="header",cols="a"] +|==================== +| Windows +| +[source%nowrap,bat,numbered] +---- +>cd modules\apex-apps\apex-apps.uservice\apex-apps.uservice-packaging\apex-apps.uservice-package-full\target +>dir +---- + +| +[source%nowrap,sh,numbered,subs="attributes+"] +---- +include::{adsite-main-dir}/site-docs/adoc/fragments/screens/target-ls-win.txt[successful build, ls, windows] +---- + + +|==================== + +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. + diff --git a/src/site-docs/adoc/fragments/install-guide/layout.adoc b/src/site-docs/adoc/fragments/install-guide/layout.adoc new file mode 100644 index 000000000..ef3d1cf5b --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/layout.adoc @@ -0,0 +1,47 @@ +// +// ============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) +// + +== Installation Layout + +A full installation of APEX comes with the following layout. + +---- +$APEX_HOME + ├───bin <1> + ├───etc <2> + │ ├───editor + │ ├───hazelcast + │ ├───infinispan + │ └───META-INF + ├───examples <3> + │ ├───config <4> + │ ├───docker <5> + │ ├───events <6> + │ ├───models <7> + │ └───scripts <8> + ├───lib <9> + │ └───applications <10> + └───war <11> +---- +<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> 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 + diff --git a/src/site-docs/adoc/fragments/install-guide/requirements.adoc b/src/site-docs/adoc/fragments/install-guide/requirements.adoc new file mode 100644 index 000000000..6376a53e6 --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/requirements.adoc @@ -0,0 +1,52 @@ +// +// ============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) +// + +== Requirements +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 + +- 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 + ** for instance link:https://tomcat.apache.org/[Apache Tomcat] +- Sufficient rights to install APEX on the system +- Installation tools depending on the installation method used: + ** ZIP to extract from a ZIP distribution + *** Windows for instance link:http://www.7-zip.org/[7Zip] + ** TAR and GZ to extract from that TAR.GZ distribution + *** Windows for instance link:http://www.7-zip.org/[7Zip] + ** RPM to install from the RPM distribution + *** Install: `sudo apt-get install rpm` + ** DPKG to install from the DEB distribution + *** Install: `sudo apt-get install dpkg` + + +=== Feature Requirements +APEX supports a number of features that require extra software being installed. + +- link:https://kafka.apache.org/[Apache Kafka] to connect APEX to a Kafka message bus +- link:https://hazelcast.com/[Hazelcast] to use distributed hash maps for context +- link:http://infinispan.org/[Infinispan] for distributed context and persistence +- link:https://www.docker.com/[Docker] to run APEX inside a Docker container + + +=== Build (Install from Source) Requirements +Installation from source requires a few development tools + +- GIT to retrieve the source code +- Java SDK, Java version 8 or later +- Apache Maven 3 (the APEX build environment) + diff --git a/src/site-docs/adoc/fragments/install-guide/verify.adoc b/src/site-docs/adoc/fragments/install-guide/verify.adoc new file mode 100644 index 000000000..782c2723e --- /dev/null +++ b/src/site-docs/adoc/fragments/install-guide/verify.adoc @@ -0,0 +1,180 @@ +// +// ============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) +// + +== 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. + +On Unix (or Cygwin) start the engine using `$APEX_HOME/bin/apexEngine.sh`. +The engine will fail to fully start. +However, if the output looks similar to the following line, the APEX installation is realized. + +[source%nowrap,sh,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: +---- + +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 +A full APEX installation comes with several examples. +Here, we can fully verify the installation by running one of the examples. + +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. + +[source%nowrap,sh,numbered,subs="attributes+"] +---- +# $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> +---- +<1> UNIX +<2> Cygwin +<3> Windows + + +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) + +[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 +Started Apex service +---- + +Important are the last two line, stating that APEX has added the final action listener to the engine and that the engine is started. + +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. + +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. + +[width="100%",options="header",cols="5a,5a"] +|==================== +| Input Event | Example Output 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 +} +---- +| +[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 +} +---- +|==================== + +Terminate APEX by simply using `CTRL+C` in the console. + + +=== Verify a Full Installation - REST Editor +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. + +[source%nowrap,sh,numbered] +---- +# $APEX_HOME/bin/apexApps.sh rest-editor +---- + +[source%nowrap,bat,numbered] +---- +>%APEX_HOME%\bin\apexApps.bat rest-editor +---- + +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`. +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 +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/ +---- + +Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and use the URL `http://localhost:18988/`. +This will connect the browser to the started REST editor. +The start screen should be as follows. + +.REST Editor Start Screen +image::install-guide/rest-start.png[REST Editor Start Screen] + +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. + +.REST Editor with loaded SampleDomain Policy Model +image::install-guide/rest-loaded.png[REST Editor with loaded SampleDomain Policy Model] + +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. + |