diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/install-guide')
9 files changed, 0 insertions, 911 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 deleted file mode 100644 index 8676d8f29..000000000 --- a/src/site-docs/adoc/fragments/install-guide/build-apex.adoc +++ /dev/null @@ -1,120 +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) -// - -== Build APEX - -The examples in this document assume that the APEX source repositories are cloned to: - -- 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 -==== -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-pdp -# mvn clean install -DskipTests ----- -| -[source%nowrap,bat,numbered] ----- ->c: ->cd \dev\apex-pdp ->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 packages/apex-pdp-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 packages\apex-pdp-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 deleted file mode 100644 index 97388f8f7..000000000 --- a/src/site-docs/adoc/fragments/install-guide/configure.adoc +++ /dev/null @@ -1,160 +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) -// - -== 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/app/policy/apex-pdp/apex-pdp -# export APEX_HOME=`pwd` ----- - -[source%nowrap,tcsh,numbered] ----- -# setenv APEX_USER apexuser -# cd /opt/app/policy/apex-pdp/apex-pdp -# 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/app/policy/apex-pdp/apex-pdp ----- -| -[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/onap/policy/apex-pdp/" />` - -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/onap/policy/apex-pdp -chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp ----- -| -[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 deleted file mode 100644 index 6f63956aa..000000000 --- a/src/site-docs/adoc/fragments/install-guide/docker.adoc +++ /dev/null @@ -1,44 +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) -// - -== Running APEX in Docker - -Since APEX is in ONAP, we provide a full virtualization environment for the engine. - - -=== Run in ONAP - -Running APEX from the ONAP docker repository only requires 2 commands: - -. Log into the ONAP docker repo -[source%nowrap,sh,numbered] ----- -docker login -u docker -p docker nexus3.onap.org:10003 ----- -. Run the APEX docker image -[source%nowrap,sh,numbered] ----- -docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest ----- - - -=== Build a Docker Image - -Alternatively, one can use the Dockerfile defined in the Docker package to build an image. - -.APEX Dockerfile -[source%nowrap,sh,numbered,subs="attributes+"] ----- -include::{adsite-packages-docker-dir}/main/docker/Dockerfile[APEX Dockerfile] ----- - diff --git a/src/site-docs/adoc/fragments/install-guide/get-source.adoc b/src/site-docs/adoc/fragments/install-guide/get-source.adoc deleted file mode 100644 index 0aa97db1e..000000000 --- a/src/site-docs/adoc/fragments/install-guide/get-source.adoc +++ /dev/null @@ -1,27 +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) -// - -== Get the APEX Source Code - -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 ONAP using HTTPS. - -[source%nowrap,sh,numbered] ----- -git clone https://gerrit.onap.org/r/policy/apex-pdp ----- - diff --git a/src/site-docs/adoc/fragments/install-guide/install-wars.adoc b/src/site-docs/adoc/fragments/install-guide/install-wars.adoc deleted file mode 100755 index 2de1e0b89..000000000 --- a/src/site-docs/adoc/fragments/install-guide/install-wars.adoc +++ /dev/null @@ -1,46 +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 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 deleted file mode 100644 index 57d78739e..000000000 --- a/src/site-docs/adoc/fragments/install-guide/install.adoc +++ /dev/null @@ -1,224 +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) -// - -== 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/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. -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-pdp-package-full-{release-version}.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-pdp-package-full-{release-version}.deb -Selecting previously unselected package apex-uservice. -(Reading database ... 288458 files and directories currently installed.) -Preparing to unpack apex-pdp-package-full-{release-version}.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-pdp-package-full-{release-version}.tar.gz -C apex-full-{release-version} -# ln -s apex apex-pdp-package-full-{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` - -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-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}`. - - - -== 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 packages/apex-pdp-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 packages\apex-pdp-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 deleted file mode 100644 index bbb21021f..000000000 --- a/src/site-docs/adoc/fragments/install-guide/layout.adoc +++ /dev/null @@ -1,50 +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) -// - -== 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> - │ ├───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 -<3> example policy models to get started -<4> configurations for the examples (with sub directories for individual examples) -<5> Docker files and additional Docker instructions for the exampples -<6> example events for the examples (with sub directories for individual examples) -<7> HTML files for some examples, e.g. the Decisionmaker example -<8> the policy models, generated for each example (with sub directories for individual examples) -<9> additional scripts for the examples (with sub directories for individual examples) -<10> the library folder with all Java JAR files -<11> applications, also known as jar with dependencies (or fat jars), individually deployable -<12> WAR files for web applications - diff --git a/src/site-docs/adoc/fragments/install-guide/requirements.adoc b/src/site-docs/adoc/fragments/install-guide/requirements.adoc deleted file mode 100644 index 6376a53e6..000000000 --- a/src/site-docs/adoc/fragments/install-guide/requirements.adoc +++ /dev/null @@ -1,52 +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) -// - -== 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 deleted file mode 100644 index 6774a8489..000000000 --- a/src/site-docs/adoc/fragments/install-guide/verify.adoc +++ /dev/null @@ -1,188 +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) -// - -== Verify the APEX Installation -When APEX is installed and all settings are realized, the installation can be verified. - -=== 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. - -[source%nowrap,sh,numbered] ----- -Starting Apex service with parameters [] . . . -start of Apex service failed: Apex configuration file was not specified as an argument -2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed -org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument - at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267) - at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161) - at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68) - at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165) -usage: org.onap.policy.apex.service.engine.main.ApexMain [options...] -options --c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file - containing the Apex configuration parameters --h,--help outputs the usage of this command --m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the - configuration file --v,--version outputs the version of Apex - ----- - - - -=== Verify Installation - run an Example -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] ----- -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 ----- - -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] ----- -{ - "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 -} ----- -|==================== - -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:18989`. -The last few line of the messages should be: - -[source%nowrap,sh,numbered] ----- -Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . . -Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start -INFO: Started listener bound to [localhost:18989] -Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start -INFO: [HttpServer] Started. -Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/ ----- - -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. - -.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. - |