1 files changed, 226 insertions, 0 deletions
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.
+