IKAN ALM Installation Guide

Purpose

This document explains how to install IKAN ALM using a graphical installer. If you want to install IKAN ALM using the console installer, please refer to the document HowToALM 5.8_Tomcat_Install.

IKAN ALM consists of 3 major components:

IKAN ALM Server
IKAN ALM Agent
IKAN ALM Commandline

An IKAN ALM installation needs exactly 1 Server and at least 1 Agent to function correctly.

The IKAN ALM Server consists of 3 different components:

the IKAN ALM Web Application
the IKAN ALM Server daemon
the IKAN ALM Server environment

The IKAN ALM Web Application is an interface to the IKAN ALM administration, and must be deployed on a Java EE Web container.

The IKAN ALM Server daemon itself consists of 2 sub-components, a Scheduler and a Monitor. The IKAN ALM Scheduler is responsible for observing the VCR (Version Control Repository) and creating a Build request when changes (modified sources) in the VCR are detected. The IKAN ALM Monitor will manage the different build and deploy actions that are executed by the IKAN ALM Agent(s).

Both the IKAN ALM Server and the IKAN ALM Agent run as OSGi bundles in Apache Karaf containers, benefiting from the advantages of a modular architecture. The IKAN ALM Server daemon will be installed in the IKAN ALM Server Environment, and may be launched by scripts, or started as a Windows service or Unix/Linux daemon.

The IKAN ALM Server Environment contains the following important files and folders:

Build Archive Location: the location where the Build results will be stored,
Work Copy Location: the location where the sources that are checked out from the repository are stored before they are transported to the Agents,
Phase Catalog Location: the location where the Phases that have been imported will be stored, ready to be retrieved by remote Agents when needed,
Scripts Location: the location to be used for storing centralized build and deploy scripts,
Configuration with the (external) security system. For more information, refer to the Appendix JAAS configuration,
Documentation in PDF format.

A machine that needs to execute IKAN ALM Builds and Deploys must have the IKAN ALM Agent installed.

The IKAN ALM Commandline can be installed separately and can be used as an alternative for the web interface to create Level Requests and Reports via a command prompt.

Example configuration 1: Single machine, everything locally installed:

Machine 1: Server, Agent, Commandline

Example configuration 2: Multiple machines, remote Agent and Commandline:

Machine 1: Server, Agent
Machine 2: Agent, Commandline

Prerequisites

The following section provides an overview of the prerequisites for installing IKAN ALM.

The complete requirements are available online at http://www.ikanalm.com.

Hardware Requirements

Component	Memory	Disk
IKAN ALM Server	Min 1GB, recommended 2GB	Min 10GB, recommended 40GB
IKAN ALM Agent	Min 256MB, recommended 512MB	Min 1GB
IKAN ALM Commandline	Min 128MB, recommended 256MB	Min 40MB

Component

Memory

Disk

IKAN ALM Server

Min 1GB, recommended 2GB

Min 10GB, recommended 40GB

IKAN ALM Agent

Min 256MB, recommended 512MB

Min 1GB

IKAN ALM Commandline

Min 128MB, recommended 256MB

Min 40MB

Note that these are just indicative values. If the IKAN ALM Server will also act as a Build Server, it might have more demanding memory requirements depending on the number of builds that run concurrently. For a more mathematical approach, we refer to the article “Capacity Planning for Software Build Management Servers” on the “CM Crossroads” site: http://www.cmcrossroads.com/article/capacity-planning-software-build-management-servers.

There is no hard and fast rule for disk storage space. The actual amount you will require depends on the number and size of the projects managed with IKAN ALM, and on the size of the build results stored in the build archive. More projects and larger build results mean more required disk space.

Java SE Runtime (JRE) 1.7 or 1.8

All IKAN ALM components need at least a Java Development Kit (JDK) or a Server Java Runtime (Server JRE). IKAN ALM has been tested to run with both Oracle Java and OpenJDK. The Java SE Server Runtime Environment (Server JRE) or Software Development Kit (SDK) can be freely obtained from Oracle’s website. Both 32-bit and 64-bit versions are supported. The latest version of Java SE can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Application Server

The IKAN ALM Web application requires a Java EE 5 to 7 compliant web container, supporting the Servlet 2.5 to 3.1 and JSP 2.1 to 2.3 specifications.

Apache Tomcat 7 or 8

IKAN ALM has been tested with Apache Tomcat 7.0.55 and later versions. When choosing a version, please check Tomcat’s own prerequisites (e.g. Tomcat 8 requires at least Java SE v 7).

IKAN ALM has been proven to run on Tomcat on different Operating Systems, including recent versions of Windows and Linux, Sun Solaris, HP Unix, MacOS X, zLinux, … If a suitable Java Runtime is available (Java SE Runtime (JRE) 1.7 or 1.8), IKAN ALM may run on other Operating Systems. Consult the detailed Technical Requirements on http://www.ikanalm.com.

Enable Unicode support in Tomcat

When using Unicode symbols in IKAN ALM (for instance, projects containing files with special characters in the name), an extra setting should be applied to the Tomcat’s server.xml configuration file.

Modify the TOMCAT_HOME/conf/server.xml file:

in the http connector, add the attribute URIEncoding="UTF-8":

<Connector port="8080" protocol="HTTP/1.1"
URIEncoding="UTF-8" connectionTimeout="200000" redirectPort="8443"
/>

This fix is based on the article: http://wiki.apache.org/tomcat/FAQ/CharacterEncoding.

Tomcat Memory Settings

It is recommended to set the following memory settings for running IKAN ALM with Java 8 in Tomcat:

initial Java heap size (-Xms) : 128m
max Java heap size (-Xmx) : 384m
max Metaspace size (-XX:MaxMetaspace) : 128m

If you launch Tomcat from the startup scripts, you need to create or edit TOMCAT_HOME/bin/setenv.bat (Windows) or TOMCAT_HOME/bin/setenv.sh (Linux/Unix), and to add, near the top of the file, a line like:

for Windows:

SET JAVA_OPTS=-Xms128m -Xmx384m -XX:MaxMetaspaceSize=128m
for Linux/Unix:

JAVA_OPTS=-Xms128m -Xmx384m -XX:MaxMetaspaceSize=128m

If you run Tomcat as a Windows service, you need to set the memory settings in the file TOMCAT_HOME/bin/service.bat.

Add the following lines near the top of the file:

set JvmMs=128
set JvmMx=384
set JvmArgs=-XX:MaxMetaspaceSize=128m

After these modifications, you need to re-install the service by running "service.bat remove", followed by "service.bat install". You need Administrative privileges to run these commands.

If you use Java 7, replace the setting –XX:MaxMetaspaceSize=128m with -XX:MaxPermSize=128m. For an explanation, refer to http://javaeesupportpatterns.blogspot.co.uk/2013/02/java-8-from-permgen-to-metaspace.html.

Database

IKAN ALM supports MySQL, MsSQL, Oracle and DB2 database as the back-end. During the installation, it is possible to verify a connection to an existing database, as well as to initialize the existing database with the default data. Beware that when the DB initializing option is selected, the existing data will be overwritten. Before initializing the database, make sure the database/scheme exists.

For MySQL, it is recommended that the database has a character set of UTF8. Here is an example of the MySQL script creating a database from scratch:

CREATE DATABASE alm CHARACTER SET utf8 COLLATE utf8_unicode_ci;

Consult your database documentation for more information on the appropriate UTF8-collation for your system.

Installing IKAN ALM

This section describes the different steps for installing IKAN ALM.

Running the installer

For Windows users

Execute either the 32-bit or the 64-bit installer:

alm_install_5-8_x86.exe

To run this installer image, you will need to have a 32-bit Public Java Runtime Environment (Public JRE) installed.
alm_install_5-8_x64.exe

To run this installer image, you will need to have a 64-bit Public Java Runtime Environment (Public JRE) installed.

Refer to Troubleshooting when the IKAN ALM installer won’t start.

The graphical IKAN ALM installer will start.

Depending on the flavor of Windows OS used, there can be differences in the installer’s behavior. If UAC is enabled (Windows Vista and later), Windows will ask for a confirmation for the program to make changes to the computer (if your user account is an administrator). If you are trying to install the application from an account other than Administrator, you might get the message "requested operation requires elevation".

For Linux/Unix users

Before installing ALM, make sure that the '$JAVA_HOME/jre/lib/security/java.security' file has write access for the current user, otherwise the installation can fail.

An example of granting the maximum access to the file:

sudo chmod 777 /usr/lib/jvm/java-8-openjdk-amd64/jre/lib/security/java.security

Open a shell, go to the folder containing the IKAN ALM installation files and execute java -jar alm_install_5.8.jar.

Assuming Java is installed and present in the PATH, the graphical IKAN ALM installer will start.

Language Selection, Welcome, Readme and LicensePanels

Choose the installation language and click OK.

The following welcome screen will be displayed:
Click Next to continue.

The following screen is displayed:
Carefully read the readme information and click Next to continue.

The following screen is displayed:
Read the license agreement carefully. Select the option “I accept the terms of this license agreement” and click the Next button.

Selecting the Packages to Install

The packages panel is displayed:

Here you can select which IKAN ALM components you wish to install. By default, all components are selected.

Select the component(s) you wish to install, and then click Next.

Refer to the following sections for more information on the installation options:

Installing the Server
Installing the Agent
Installing the Commandline

Installing the Server

This section explains the installation options of the IKAN ALM Server component.

The panels in this section are only displayed if you selected the “ALM Server” package.

ALM Server parameters (1 of 2)

The following fields are available:

Field Description

Field	Description
Install Path	Select the location where IKAN ALM should be installed. The default is `C:\ALM` on Windows, and `$HOME/ALM` on Linux/Unix. You can change this location using the Browse button. Further on in this document, this location will be referred to as `ALM_HOME`.
Java Path	The installation directory of the Java Runtime that will be used to launch the Server. This can point to a Server JRE or JDK. By default, the Java Runtime that started the installer is selected. IKAN ALM needs a Server JRE or JDK 1.7 or 1.8. You can change this location using the Browse button. Files will be copied to the Install Path, and a file will be modified in a subfolder of the Java Path, so make sure that the user who will run the installation has write access to these locations. Make sure that the selected Java Runtime is the same as the one that is used to start Tomcat!
Database type	The type of database that will host the IKAN ALM database. The possible choices are: MySQL (default) MsSQL Oracle DB2 Specific parameters for the selected database can be provided later in the installation procedure.

Install Path

Select the location where IKAN ALM should be installed.

The default is C:\ALM on Windows, and $HOME/ALM on Linux/Unix. You can change this location using the Browse button.

Further on in this document, this location will be referred to as ALM_HOME.

Java Path

The installation directory of the Java Runtime that will be used to launch the Server. This can point to a Server JRE or JDK. By default, the Java Runtime that started the installer is selected. IKAN ALM needs a Server JRE or JDK 1.7 or 1.8.

You can change this location using the Browse button. Files will be copied to the Install Path, and a file will be modified in a subfolder of the Java Path, so make sure that the user who will run the installation has write access to these locations.

Make sure that the selected Java Runtime is the same as the one that is used to start Tomcat!

Database type

The type of database that will host the IKAN ALM database.

The possible choices are:

MySQL (default)
MsSQL
Oracle
DB2

Specific parameters for the selected database can be provided later in the installation procedure.

Click Next to go to the second page of ALM Server parameters.

ALM Server parameters (2 of 2)

The following fields are available:

Field	Description
Server port	The port number used for communication between the Server and its Agents. Note that you must use this same port number in subsequent IKAN ALM Agent installations, otherwise the Agent-Server communication may fail. Default: 20021
Agent port	The port number the local IKAN ALM Agent is going to listen on. Default: 20020
Karaf RMI Registry port	The RMI registry port used by the Karaf container the IKAN ALM Server is running in. Default: 1100
Karaf RMI Server port	The RMI server port used by the Karaf container the IKAN ALM Server is running in. Default: 44445
Karaf SSH port	The SSH port used by the Karaf container the IKAN ALM Server is running in. Default: 8102
Secure Server-Agent communication	When enabled, this causes all Server-Agent communication to be encrypted. Default: disabled

Field

Description

Server port

The port number used for communication between the Server and its Agents.

Note that you must use this same port number in subsequent IKAN ALM Agent installations, otherwise the Agent-Server communication may fail.

Default: 20021

Agent port

The port number the local IKAN ALM Agent is going to listen on.

Default: 20020

Karaf RMI Registry port

The RMI registry port used by the Karaf container the IKAN ALM Server is running in.

Default: 1100

Karaf RMI Server port

The RMI server port used by the Karaf container the IKAN ALM Server is running in.

Default: 44445

Karaf SSH port

The SSH port used by the Karaf container the IKAN ALM Server is running in.

Default: 8102

Secure Server-Agent communication

When enabled, this causes all Server-Agent communication to be encrypted.

Default: disabled

Click Next to go to the application server parameters panel.

Tomcat parameters

Provide the parameters of your Tomcat installation.

The following fields are available:

Field	Description
Port	The Tomcat HTTP Connector port. Default: 8080
Tomcat home dir	Set this to the home directory of the Tomcat installation that will host the IKAN ALM Web application.

Field

Description

Port

The Tomcat HTTP Connector port.

Default: 8080

Tomcat home dir

Set this to the home directory of the Tomcat installation that will host the IKAN ALM Web application.

Click Next to go to the Database parameters panel.

Database connection parameters

Depending on the database that was chosen to host the IKAN ALM database, a panel similar to this one will be displayed:

The following fields are available:

Field	Description
Host	The host name of the database server. Default: the host name of the local system
Port	The port on which the database server is listening on. Default: the default port of the selected database type
Database name	The name of the IKAN ALM database.
Schema	The schema name, only available when the database type is DB2. Default: ALM
Username	A valid user that can connect to the database and has write access to it.
Password	A valid password.
Initialize the database	Specifies whether to initialize the IKAN ALM database. WARNING: when enabled, all IKAN ALM related tables in the target database will be dropped and populated with initial data!
Validate connection	Specifies whether to test the database connection parameters after pressing the Next button.

Field

Description

Host

The host name of the database server.

Default: the host name of the local system

Port

The port on which the database server is listening on.

Default: the default port of the selected database type

Database name

The name of the IKAN ALM database.

Schema

The schema name, only available when the database type is DB2.

Default: ALM

Username

A valid user that can connect to the database and has write access to it.

Password

A valid password.

Initialize the database

Specifies whether to initialize the IKAN ALM database.

WARNING: when enabled, all IKAN ALM related tables in the target database will be dropped and populated with initial data!

Validate connection

Specifies whether to test the database connection parameters after pressing the Next button.

Click Next to continue the installation.

Installing the Agent

When you selected the “ALM Agent” package, the following panel is displayed:

The following fields are available:

Field Description

Field	Description
Install Path	Select the target location where the IKAN ALM Agent should be installed. The default is `C:\ALM` on Windows, and `$HOME/ALM` on Linux/Unix. You can change this location using the Browse button. This field is initialized to the Server Install Path and greyed out when you also selected the IKAN ALM Server component.
Java Path	The installation directory of the Java Runtime that will be used to launch the Agent. This can point to a Server JRE or JDK. By default, the Java Runtime that started the installer is selected. The IKAN ALM Agent needs a Server JRE or JDK 1.7 or 1.8. You can change this location using the Browse button.
Agent port	The port the Agent will be listening on. The default value is `"20020`". I f you change this value, you will also have to change the `"Agent Port`" property of the Machine representing this Agent in the IKAN ALM Global Administration. This field is initialized and greyed out when you also selected the IKAN ALM Server component.
Server host	The hostname (or IP address) of the IKAN ALM Server machine. The Agent will try to connect to the Server by using this name or IP address and using the HTTP or HTTPS protocol. By default it is set to the host name of the local system. This field is initialized and greyed out when you also selected the IKAN ALM Server component.
Server port	The port the IKAN ALM Server is listening on. The Agent will try to connect to the Server on this port. The default value is “20021”. This field is initialized and greyed out when you also selected the IKAN ALM Server component.
Karaf RMI Registry port	The RMI registry port used by the Karaf container the IKAN ALM Agent is running in. Default: 1099
Karaf RMI Server port	The RMI server port used by the Karaf container the IKAN ALM Agent is running in. Default: 44444
Karaf SSH port	The SSH port used by the Karaf container the IKAN ALM Agent is running in. Default: 8101
Secure Server-Agent communication	When enabled, this causes all Server-Agent communication to be encrypted. Default: disabled. This field is initialized and greyed out when you also selected the IKAN ALM Server component.

Install Path

Select the target location where the IKAN ALM Agent should be installed. The default is C:\ALM on Windows, and $HOME/ALM on Linux/Unix.

You can change this location using the Browse button. This field is initialized to the Server Install Path and greyed out when you also selected the IKAN ALM Server component.

Java Path

The installation directory of the Java Runtime that will be used to launch the Agent.

This can point to a Server JRE or JDK. By default, the Java Runtime that started the installer is selected. The IKAN ALM Agent needs a Server JRE or JDK 1.7 or 1.8. You can change this location using the Browse button.

Agent port

The port the Agent will be listening on.

The default value is `"20020`". I f you change this value, you will also have to change the `"Agent Port`" property of the Machine representing this Agent in the IKAN ALM Global Administration. This field is initialized and greyed out when you also selected the IKAN ALM Server component.

Server host

The hostname (or IP address) of the IKAN ALM Server machine. The Agent will try to connect to the Server by using this name or IP address and using the HTTP or HTTPS protocol. By default it is set to the host name of the local system. This field is initialized and greyed out when you also selected the IKAN ALM Server component.

Server port

The port the IKAN ALM Server is listening on.

The Agent will try to connect to the Server on this port. The default value is “20021”.

This field is initialized and greyed out when you also selected the IKAN ALM Server component.

Karaf RMI Registry port

The RMI registry port used by the Karaf container the IKAN ALM Agent is running in.

Default: 1099

Karaf RMI Server port

The RMI server port used by the Karaf container the IKAN ALM Agent is running in.

Default: 44444

Karaf SSH port

The SSH port used by the Karaf container the IKAN ALM Agent is running in.

Default: 8101

Secure Server-Agent communication

When enabled, this causes all Server-Agent communication to be encrypted.

Default: disabled.

This field is initialized and greyed out when you also selected the IKAN ALM Server component.

Click Next to continue the installation.

Installing the Commandline

When you selected the “ALM CommandLine” package, the following panel is displayed:

The following fields are available:

Field Description

Field	Description
Install Path	Select the target location where IKAN ALM should be installed. The default is `C:\ALM` on Windows, and `$HOME/ALM` on Linux/Unix. You can change this location using the Browse button. This field is initialized and greyed out when you also selected the IKAN ALM Server component or the IKAN ALM Agent component.
Java Path	The installation directory of the Java Runtime that will be used to launch the Commandline. This can point to a Server JRE or JDK. By default, the Java Runtime that started the installer is selected. The IKAN ALM Commandline needs at least a JRE or JDK 1.7. You can change this location using the Browse button.

Install Path

Select the target location where IKAN ALM should be installed. The default is C:\ALM on Windows, and $HOME/ALM on Linux/Unix. You can change this location using the Browse button. This field is initialized and greyed out when you also selected the IKAN ALM Server component or the IKAN ALM Agent component.

Java Path

The installation directory of the Java Runtime that will be used to launch the Commandline. This can point to a Server JRE or JDK. By default, the Java Runtime that started the installer is selected. The IKAN ALM Commandline needs at least a JRE or JDK 1.7. You can change this location using the Browse button.

Click Next to continue the installation.

Summary and installation

A Summary panel will be displayed:

Verify all defined parameters, and click Next to start the installation.

When this step has finished successfully, click Next to perform post-installation actions.

When all actions are completed successfully, the following will be displayed:

If the message “BUILD SUCCESSFUL” is displayed, the post-installation actions were all successful.

Click Next to check the last panel of the installation, which displays information about the uninstaller.

Click Done to end the installation.

During the installation, a log file was created in the folder ALM_HOME/FileBased named “Install_V5.8_*.log” (e.g., Install_V5.8_20130526100925_9002832048355522781.log). The installation summary can also be reviewed in the file ALM_HOME/Uninstaller/InstallSummary.htm.

If this was a new IKAN ALM Server installation (no re-installation or upgrade of an older version), and the ‘Initialize the database’ option was NOT selected during the installation, the next step is to initialize the IKAN ALM database.

Initializing the IKAN ALM Database

This step must only be executed when you perform a new (first) IKAN ALM Server installation and if the ‘Initialize the database’ option was NOT selected during the installation.

When using DB2 as the IKAN ALM database, some additional configuration is required. For more information, please refer to the section DB2 configuration.

To initialize the database, launch the script ALM_HOME/FileBased/initializeALMDatabase.cmd (Windows) or ALM_HOME/FileBased/initializeALMDatabase.sh (Linux/Unix):

Starting IKAN ALM

This section describes the steps to perform the startup of the different IKAN ALM components.

If you want to configure IKAN ALM through its GUI, you must first start the IKAN ALM Web application (Starting the IKAN ALM Web application).
If you want to run Builds and Deploys, you must start the IKAN ALM Server and Agent (Starting the IKAN ALM Server and Starting the IKAN ALM Agent).
If you want to use the IKAN ALM Commandline interface, see Using the IKAN ALM Commandline

Starting the IKAN ALM Web application

To start the IKAN ALM Web application, you need to start the Apache Tomcat web server that is hosting it.

The IKAN ALM GUI can be reached by browsing to the url http://<host>:<port>/alm. For example: http://alm_server:8080/alm.

If this is the first installation of IKAN ALM, the License window will be displayed:

Provide a valid license, and then click Submit.

Next, the Log in page will be displayed:

For more information on the IKAN ALM GUI, refer to the IKAN ALM 5.8 User Guide, which is located at ALM_HOME/doc/ALMUserGuide.pdf.

Starting the IKAN ALM Server

The IKAN ALM Server runs as an OSGi bundle inside a Karaf container. Therefore, to start the IKAN ALM Server, the Karaf container must be started first.

On Linux/Unix, from a shell:

Launch the shell script “ALM_HOME/daemons/server/startServer.sh”.

Use “ALM_HOME/daemons/server/stopServer.sh” to stop the IKAN ALM Server.
On Windows, as a Windows Service:

By default, the IKAN ALM Server is registered as a Windows service which will be started automatically at system start-up.

Alternatively, you can control the service via Start > Settings > Control Panel >Administrative Tools > Services. The name of the IKAN ALM Server service is “IKAN ALM 5.8 Server”.
On Windows, from a Command Prompt:

Launch the command file “ALM_HOME/daemons/server/startServer.cmd”.

Use “ALM_HOME/daemons/server/stopServer.cmd” to stop the IKAN ALM Server.

Starting the IKAN ALM Agent

On Linux/Unix, from a shell:

Launch the shell script “ALM_HOME/daemons/agent/startAgent.sh”.

Use “ALM_HOME/daemons/agent/stopAgent.sh” to stop the IKAN ALM Agent daemon.
On Windows, as a Windows Service:

By default, the IKAN ALM Agent is registered as a Windows service which will be started automatically at system start-up. Alternatively, you can control the service via Start > Settings > Control Panel > Administrative Tools > Services.

The name of the Agent service is “IKAN ALM 5.8 Agent”.
On Windows, from a Command Prompt:

Launch the command file “ALM_HOME/daemons/agent/startAgent.cmd”.

Use “ALM_HOME/daemons/agent/stopAgent.cmd” to stop the IKAN ALM Agent.

Using the IKAN ALM Commandline

If you selected the IKAN ALM CommandLine package, it will be installed in ALM_HOME/commandline.

To launch the IKAN ALM Commandline on Linux/Unix:

Open a shell and launch “ALM_HOME/commandline/alm.sh”.
To launch the IKAN ALM Commandline on Windows:

Open a Command Prompt and launch “ALM_HOME/commandline/alm.cmd”.

For more detailed information on the IKAN ALM Commandline, refer to the section Command Line Interface in the IKAN ALM User Guide - Release 5.8.

Uninstalling IKAN ALM

To completely uninstall IKAN ALM from your system, do the following:

On Linux/Unix:

Open a shell and execute the command “java -jar ALM_HOME/Uninstaller/uninstaller.jar”
On Windows XP/2003:

Open Control Panel > Add/Remove Programs, select the entry “IKAN ALM 5.8” and click “Change/Remove”
On Windows Vista/Server2008 and above:

Open “Programs and Features”, select the entry “IKAN ALM 5.8” and click “Uninstall/Change”

The uninstaller windows will be displayed:

WARNING: if you enable the option “Force the deletion of …” the uninstaller will DELETE the ENTIRE installation directory! This means that if your Build Archive, Deploy scripts or target environments are located in this installation directory, they will be REMOVED.

If you leave this option disabled, the uninstaller will keep some files in the installation directory, like the original location of the Build Archive (ALM_HOME/system/buildArchive).

Click Uninstall to start the removal.

When finished, the following will be displayed:

Click Quit to end the uninstaller.

Upgrading IKAN ALM

The general approach to upgrading IKAN ALM is straightforward: first back up the current installation and the database, then reinstall the application and upgrade the database to a higher version.

If the upgrade process fails, you can restore the back-up, and continue running the previous version of IKAN ALM (and contact support).

You should at least back up the following:

IKAN ALM database
Build Archive Location: configured in System Settings

(default = ALM_HOME/system/buildArchive)
Deploy Scripts Location: configured in System Settings

(default = ALM_HOME/system/deployScripts)
Phase Catalog: configured in System Settings

(default = ALM_HOME/system/phaseCatalog)

For safety reasons, it is highly recommended to back up the entire ALM_HOME directory.

Experience has shown that, sometimes, one needs to restore a configuration like a security setting or the configuration of the log files.

IKAN ALM Upgrade Procedure

Stop the IKAN ALM Server/Agent and the IKAN ALM application server (Tomcat) and make the back-up.

This is necessary to make sure you have the latest version of everything.
Uninstall the IKAN ALM Server and (if it has been installed) the local ALM Agent.

To do so, run the uninstaller on the IKAN ALM Server machine.

Information on how to do this can be found in the section Uninstalling IKAN ALM or in the guide HowToALM 5.8_Tomcat_Install.pdf (in case the previous version of IKAN ALM was installed with the console installer).
Highly recommended: also back up the ALM_HOME folder to keep the configuration.
Uninstall the remote agents.

Configure and run the uninstaller on each remote IKAN ALM Agent machine.

Information on how to do this can be found in the section Uninstalling IKAN ALM or in the guide HowToALM 5.8_AgentInstall.pdf.
Configure and run the installer of the ALM Server and local ALM Agent.

Refer to the section Installing IKAN ALM or to the document How-ToALM 5.8_Tomcat_Install.pdf.
Migrate the IKAN ALM database to the latest version.

To do this, run the Database Migration Tool (described in the next section) from the new ALM Server installation.
Finally, run the installer of the remote ALM Agents.

Refer to the guide HowToALM5.8_AgentInstall.pdf.

Database Migration Tool

The Database Migration Tool is a command line tool launched by the migrateALMDatabase script. The tool automatically detects the current database version and, if needed, attempts to migrate it to the latest one.

As pointed out in the previous section, you should back up the IKAN ALM database before starting the DB migration.

To start the migration, you need to run the DB migration tool located in:

ALM_HOME/FileBased/migrateALMDatabase.cmd (on Windows) or

ALM_HOME/FileBased/migrateALMDatabase.sh (on Linux installations).

By default, the DB Migration Tool uses the database connection parameters defined in the ALM_HOME/FileBased/install.properties file. You can also define a custom path to the install.properties by using the -installProperties switch (see the migrateALMDatabase script file contents).

The default Java executable is used to run the migration tool. In case it cannot be found, you may have to set the JAVA_HOME variable in the migrateALMDatabase script file.

The Database Migration will be done in different steps: when migrating from the older 5.2 version, first the 5.2 to 5.5 migration will be executed, before migrating version 5.5 to the (latest) 5.8 version.

Migrating the older IKAN ALM database 5.2 to version 5.5 includes significant changes. Therefore, depending on the size of your database, it may take a while (up to a few hours).

A migration log is created in the ALM_HOME/FileBased/almDbMigration.log file and will also be displayed in the console window.

Appendix A: Manually Installing and Removing the IKAN ALM Server and Agentas a Windows Service

By default, the IKAN ALM installer registers the IKAN ALM Server and Agent components as Windows services. However, for convenience purposes, the IKAN ALM installation includes scripts to unregister or re-register the IKAN ALM Server and Agent as services.

The procedures are identical for the ALM Agent and Server, so we will only describe them for the ALM Server:

To unregister the service, execute "ALM_HOME/daemons/server/karaf/bin/karaf-service.bat remove".
To register the service, execute "ALM_HOME/daemons/server/karaf/bin/karaf-service.bat install".

If you want to reconfigure the service, edit the file ALM_HOME/daemons/server/karaf/etc/karaf-wrapper.conf. You can, for example, change the amount of memory the ALM Server can use (in Mb) by changing: wrapper.java.maxmemory = 512.

It is generally not recommended to change any of the other properties in the karaf-wrapper.conf file, as it may cause the ALM Server to stop working.

For more information on the configuration file, refer to http://yajsw.sourceforge.net/YAJSW%20Configuration%20Parameters.html and http://karaf.apache.org/manual/latest/#_integration_in_the_operating_system.

Appendix B: Manually Installing and Removing the IKAN ALM Server and Agentas a Daemon Process on Linux/Unix Systems

The IKAN ALM installer does not automatically install the ALM Server or Agent as a Linux/Unix daemon. These steps must be performed after installation.

Since the ALM Server and Agent use Apache Karaf as their OSGi runtime environment, this basically comes down to using the Apache Karaf Wrapper feature (see the Karaf 4.0 manual: http://karaf.apache.org/manual/latest/#_service_wrapper).

As an example, we will describe this procedure for installing and removing the ALM Server as a service on a CentOS Linux. For the ALM Agent, repeat the procedure, but substitute "server" with "agent".

If you are currently running the ALM Server, stop it by executing ALM_HOME/daemons/server/stopServer.sh
Launch the ALM Server Karaf by executing ALM_HOME/daemons/server/karaf/bin/karaf_server.sh . This will launch the ALM Server with the Karaf console enabled, which we will need to use the Karaf Wrapper feature.
After the startup messages have finished, press <enter> and you will see the Karaf console prompt: "karaf@root>"
In the Karaf console, execute "feature:install wrapper". This will install the Karaf Wrapper feature. You can verify that this worked by executing " feature:list | grep wrapper". This should give the output:

wrapper | 4.0.7 | x | Started | standard-4.0.7 | Provide OS integration
Now we must call "wrapper:install" which will generate the necessary files to install the ALM Server as a Linux service. In the Karaf console, execute 'wrapper:install -s DEMAND_START -n almserver58 -d "IKAN ALM 5.8 Server" -D "IKAN ALM 5.8 Server Daemon"'.

When this command succeeds, it conveniently reports the commands that we need to execute as subsequent steps.
Shut down the ALM Server Karaf: in the Karaf console, execute "shutdown -f"
Adapt the ALM_HOME/daemons/server/karaf/etc/almserver58-wrapper.conf file that was created, by adding the following options:
- Just before the KARAF_HOME, in the section of the general wrapper properties, set the path to the Java runtime you selected during the IKAN ALM Server installation (Installing the Server):
  
  set.default.JAVA_HOME=/opt/java/jdk1.8.0
- change the path to the java executable:
  
  wrapper.java.command=/opt/java/jdk1.8.0/bin/java * In the section of the JVM Parameters, add following parameters:
  
  + wrapper.java.additional.10=-XX:+UnlockDiagnosticVMOptions
  
  + wrapper.java.additional.11=-XX:+UnsyncloadClass
At this point everything is configured so we can install, remove, stop and start the IKAN ALM Server Linux daemon. All of these commands need administrative privileges, so you will need to execute them with "sudo" :
- To install the service:
  - ln -s /home/ikan/ALM/daemons/server/karaf/bin/almserver58-service /etc/init.d/
  - chkconfig almserver58-service --add
- To start the service when the machine is rebooted:
  - chkconfig almserver58-service on
- To disable starting the service when the machine is rebooted:
  - chkconfig almserver87-service off
- To start the service:
  - service almserver58-service start
- To stop the service:
  - service almserver58-service stop
- To uninstall the service:
  - chkconfig almserver58-service --del
  - rm /etc/init.d/almserver58-service

Appendix C: JAAS configuration

For the authentication and authorization of users, IKAN ALM uses the Java Authentication and Authorization Service (JAAS) (see http://download.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html).

The IKAN ALM Server installation automatically preconfigures JAAS, so this appendix is only for troubleshooting, or if you want to adapt authentication, e.g., for using Windows domain authentication.

JAAS authentication is performed in a pluggable fashion. This permits applications to remain independent from underlying authentication technologies. New or updated authentication technologies can be plugged into IKAN ALM without requiring modifications to the application itself.

IKAN ALM Server JAAS configuration

The IKAN ALM Server installation modifies the java.security file of the Java Runtime that was selected in ALM Server parameters (1 of 2). This file is located in the subfolder jre/lib/security if the Java Runtime is a JDK, or in the subfolder lib/security when a Server JRE was selected.

Note that if you use Tomcat to host the IKAN ALM Web application, it must be started with this selected Java Runtime, or else you will have authentication errors.

The location of the login configuration file is set statically by specifying the URL in the login.config.url.n property (in the “Default login configuration file” paragraph).

For example:

## Default login configuration file##login.config.url.1=file:${user.home}/.java.login.config login.config.url.1=file:/opt/alm/system/security/jaas.config

with “/opt/alm/” the chosen ALM_HOME.

If multiple configuration files are specified (if n >= 2), they will be read and combined into one single configuration:

## Default login configuration file##login.config.url.1=file:${user.home}/.java.login.config login.config.url.1=file:c:/Documents and Settings/Administrator/.java.login.configlogin.config.url.2=file:c:/alm/system/security/jaas.config

JVM option or user.home JAAS configuration

If you are using Tomcat, there are two other ways to set up the JAAS configuration:

The first uses a system property which is set from the command line: -Djava.security.auth.login.config option.

When running Tomcat from a Linux/Unix shell or from a Windows Command Prompt, set the JAVA_OPTS variable in the file TOMCAT_HOME/bin/Catalina.sh or TOMCAT_HOME/bin/Catalina.bat: JAVA_OPTS=-Djava.security.auth.login.config=/opt/alm/system/security/jaas.config
The second option is to use the default configuration file which is loaded from the user’s home directory: file:${user.home}/.java.login.config

JAAS implementation: flat file security

The IKAN ALM Server uses a simple JAAS implementation, where user groups and users are configured in a flat file. In the JAAS configuration file, this is specified as follows (when ALM_HOME=`"/opt/alm`"):

/** * ALM flat file security configuration  * Attention : the passwords in the passwd.config file must
be stored in MD5 encryption format **/**/ALM{  com.tagish.auth.FileLogin required pwdFile=”/opt/alm/system/security/passwd.config";};

Flat file security: contents

The contents of the passwd.config file when using flat file security is fairly easy and self-explanatory:

userid:encrypted password:groupname:groupname:groupnameuser:ee11cbb19052e40b07aac0ca060c23ee:ALM Userproject:46f86faa6bbf9ac94a7e459509a20ed0:ALM User:ALM Projectglobal:9c70933aff6b2a6d08c687a6cbb6b765:ALM User:ALM Administrator

The encrypted password is in MD5 encryption format. There are numerous free downloadable tools that can generate a MD5 checksum for a given string. There is even a JavaScript implementation that you can use online to calculate checksums at: http://pajhome.org.uk/crypt/md5/index.html

For example, to add a user with User ID “testuser” and password “testuser” who belongs to the “ALM User” and “ALM Project” User Groups, do the following:

Add following entry to the passwd.config file: testuser:5d9c68c6c50ed3d02a2fcf54f63993b6:ALM User:ALM Project
Stop and restart Apache Tomcat
Login to IKAN ALM using User ID “testuser” and Password “testuser”.

Appendix D: DB2 configuration

When using DB2 as the IKAN ALM database, please make sure that the page size of the table space and its associated buffer pool is not less than 8K. Otherwise, when creating a new database in DB2, the default page size is 4K and this can cause SQL errors while running the database initialization script.

The page size of a table space in DB2 is determined by the associated buffer pool, but you cannot change the page size of a buffer pool. So, if you want to use an existing DB2 database with the page size already set to 4K, a possible workaround would be to create a new buffer pool with a page size of 8K, and next to create a new table space (e.g., USERSPACE2) with a page size of 8K and associate it with the new buffer pool.

Furthermore, you will also need to create a new system temporary tablespace (e.g., TEMPSPACE2) and associate it with a buffer pool that has a page size set to at least 8K.

Appendix E: Troubleshooting

The installer doesn’t start and displays the error:"Java Runtime not found"

When launching the 32-bit or 64-bit IKAN ALM installer on Windows, you may receive the following error, after which the IKAN ALM installer quits:

The most likely cause is that there is no suitable Java Runtime Environment (JRE) installed. The 32-bit installer needs a 32-bit JRE installed, while the 64-bit installer needs a 64-bit JRE installed. Furthermore, the JRE should be version 1.7 or 1.8.

The solution is to install a suitable JRE.

If for some reason you do not want to install a JRE, there is a workaround to launch the IKAN ALM installer with only a Java Development Kit (JDK) or a Server JRE installed: set the JAVA_HOME environment variable to point to the JDK or Server JRE folder, either globally on the system, or from a commandline prompt, and then launch the IKAN ALM installer.

When you set JAVA_HOME from a commandline prompt, there are two possible pitfalls:

do not wrap the JAVA_HOME path in quotes, even when it contains spaces
when UAC is enabled (Windows Vista and later), the commandline prompt must have Administrative privileges (the title of the prompt must start with "Administrator:")