Demo Installation Guide for Linux

The IKAN ALM 5.8 Linux Demo installation has been tested on current versions of:

However, the IKAN ALM Demo Application should also work on different Linux flavors.

Java SE Development Kit (JDK) V1.7.x or 1.8 is required.

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.

It can both be installed as root or as a regular user (e.g., in the user’s home directory) and multiple versions can coexist on your system. You can also install it via your Linux distribution’s package manager. Note that most distributions only include OpenJDK by default and that the Oracle repositories must be explicitly enabled, e.g., for Ubuntu you must enable Canonical’s "partner" repository.

IKAN ALM integrates with existing versioning tools like Subversion (SVN), Git, Microsoft Team Foundation Version Control (TFVC), Concurrent Versions Systems (CVS), …​ You must establish a connection with an existing Version Control Repository (VCR) in order to make builds or to deploy build results with IKAN ALM.

This repository may reside on the same system as the IKAN ALM Demo, or on a remote host. In both cases you must specify the parameters to connect with this repository. This can be done after the installation of IKAN ALM.

This Demo installation includes the creation of a Subversion repository. In order to connect to this repository, you need Subversion version 1.8 or higher installed on the IKAN ALM Demo system. Subversion can be downloaded from the apache website http://subversion.apache.org.

You can also install Subversion via a Package manager installed on your Linux. For example on Suse Linux, with YAST:

IKAN ALM Demo 5.8 will be distributed as a .tar.gz file named ikanalm_trial.tar.gz. Once extracted, you will find an executable .jar file, this installation guide and a license file. Run the executable jar by using the following command in a shell:

The following window will pop up:

Select your preferred installation language and click OK.

The following welcome screen will pop up:

Click Next to continue.

Carefully read the readme information. Click the Next button to continue.

Read the license agreement carefully, select the option I accept the terms of the license agreement, and click the Next button.

Select the home directory for installing the Demo application on your file system. You can change this location with the Browse button.

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

Click Next to continue.

If the directory already exists, a warning message will appear.

All installation packs must be installed.

Click Next to proceed to the selection of a Java Development Kit (JDK).

As mentioned in the section Java SE Development Kit, a Java Development Kit (JDK) version 1.7 or 1.8 is required.

If the selected directory does not contain a proper JDK, the following error message will be displayed:

Configure the network ports used by IKAN ALM. Normally, the defaults presented should be OK, but it is important that these port numbers are not in use by other processes.

You may check the ports in use with the netstat command: open a shell and provide netstat -ltun in order to show the listening TCP / UDP ports.

In the remainder of this guide, the Application Server Port will be referred to as ALM_APPSERVER_PORT.

Click Next to obtain an installation summary.

Click Next to start the installation with the given settings:

Once the installation is finished, click Next to proceed with setting up the Menu items.

Select the Program Group and Shortcut Name for the Start Menu. The default group and name is IKAN ALM Demo 5.8 and will be installed in the Applications menu. You may change these names.

Click Next to complete the installation.

Together with this Installation Guide and the alm_demo_5-8.jar install file, you should have received a license file named alm_license.lic.

This demo license will expire after 30 days (Step 2: License Agreement). Contact support if you did not receive the license file, or if you want to extend the license period.

Start the IKAN ALM Demo Server:

Open the IKAN ALM web application via a web browser:

Provide the following URL: http://MACHINE_NAME:ALM_APPSERVER_PORT/alm (e.g., http://ikan009:9080/alm)

If this is your first installation, no license will be installed and you will be prompted to provide one.

Enter or browse to the file location of the alm_license.lic file you received and click Submit.

The Log in screen will appear when the license is installed. Log on with User ID global and Password global.

The IKAN ALM Demo Server must be running in order to work with IKAN ALM.

Start the IKAN ALM Demo Server:

Stop the IKAN ALM Demo Server:

An internet browser window will appear, displaying the IKAN ALM Log in screen.

You are ready to start working with the IKAN ALM web interface.

You may add this link to your internet browser’s Favorites.

Log on to IKAN ALM with one of the following predefined User IDs and passwords:

We suggest that you start with User ID global (Password: global), since this User has complete access to all components in the IKAN ALM Demo.

Provide the User ID and Password, and select Log in. The IKAN ALM home page will be displayed and you can start working in IKAN ALM.

The IKAN ALM Demo Installation includes two completely configured demo projects with a versioning system (Subversion), scripting tools, scripts and sources. The global administration and project administration are fully set up and the projects are ready for build and deploy activities.

The IKAN ALM User Guide is available in the following formats:

During the Demo installation a Subversion repository will be created, which contains the sources and scripts of the Customers project. In order to connect to this repository, you need a running Subversion server, as described in this section. In order to start working with the Customers project, you need to make sure that IKAN ALM can connect to the Subversion repository.

Make sure that the IKAN ALM Server is running and log in as User global (Password: global).

Select Global Administration > Version Control Repositories > Overview and specify Subversion in the Type field of the Search Version Control Repositories panel.

The Subversion Repository definition was created during the installation, and an attempt was made to detect a locally installed Subversion server. Most settings are OK to connect with the Subversion Repository created in the ALM_HOME/vcr/subversion/repository, but its Command Path might need to be adapted in case it could not be detected during installation. By default, the repository does not need a User ID or Password.

Click the Edit icon.

Change the Command Path to the location where the Subversion Client command (svn) resides (e.g., /usr/bin). Note that only the directory path must be specified, do not include the command itself.

Click the Test Connection button in order to verify the Subversion definition. An Info message will indicate if the definition is correct. If not, an error message will indicate what went wrong.

Do not forget to click the Save button in order to confirm your changes.

The Desktop allows you to observe the actions (Builds, Deploys) in a project. If you log on for the first time, your Desktop will be empty.

In this section, we will create a desktop item for the Customers project.

On the Desktop screen, click the Add to Desktop button.

The Add to Desktop window pops up.

A Project may have different lifecycles. In IKAN ALM, those lifecycles are organized in Project Streams. In order to follow up all the activity in a Project Stream, you must create a Project Stream Desktop Type.

Select the "1-0" Project Stream of the Customers Project, then click the Add to Desktop button.

A confirmation message will appear if the item is successfully added to the Desktop. Press the Close button to close the Add to Desktop window.

On the Desktop Overview, expand the Project Stream Levels by clicking the icon in front of the Customers 1-0 Project Stream Desktop item. The following Levels are now displayed:

As you can see, there is not much activity going on in the Customers project yet, since the project is locked. In the next step, we will unlock the project.

In order to build the Customers Project, it must be unlocked together with the corresponding Levels in the Project Administration section. This action can only be performed by a User having Project Administration rights, like the “global” or “project” User ID (See Logging on to the IKAN ALM Web Application).

Select Project Administration on the main menu to start the unlock procedure.

Click the Edit icon in front of the Customers Project.

The resulting Project Info screen appears in the Customers Project Administration context. We are not going to change the Project Settings, but you could verify the existence of the Project in the Subversion repository by clicking the Check Project Name in the VCR button.

Select Audit Project on the submenu in order to check the consistency of the Project.

Before showing the Audit Project screen, several checks will be done to verify the setup of the Project. You can click the button to get context-sensitive help on this function. For more information, refer to the chapter Auditing Projects in the IKAN ALM User Guide for more information.

If the project is consistent (branches, levels, environments, phases and parameters are valid), an Unlock link will appear in the Actions panel. Click this link to unlock the Project and its Levels.

As a result, the Locked icons for the Levels will disappear. The Project is not locked anymore. Select the Project Administration icon on the main menu to verify that the Lock button for the Project also disappeared.

As soon as the Project and its Levels are unlocked, there will automatically be some action in the Project. Check the next section to understand what is happening.

It is possible to check out the source code of the demo projects and to commit changes.

Install a Subversion client, for example Tortoise SVN, and check out the source code.

The repository URL is file:///ALM_HOME/vcr/subversion/repository/customers/trunk for the Customers project.

Modify a source file and commit it. The Scheduler will pick up the changes and will start building the Project.

Instead of using one large Ant script that performs all tasks, the deployment of the Customers application uses several small scripts that each perform a specific task. The tasks that were reusable have been encapsulated as IKAN ALM Custom Phases.

More specifically, the deploy to the Test level does three things:

The first task was not general enough to be reused, but for the other two tasks Custom Phases were made: the “Update DB” and the “Tomcat Deploy” phases.

To view the definitions of these phases, go to Global Administration > Phases > Overview.

Click the _Edit _ icon before the com.ikanalm.phases.ant.scripting.tomcatDeploy Phase.

This page displays general information about the Phase, the Phase Parameters that can be set to configure the execution of the Phase, and where the Phase is currently being used (the Connected Levels and Environments panel).

One of the parameters that can be set is “tomcat.server.url”. It sets the base URL of the Tomcat server where an application needs to be deployed. When a Phase is added to an Environment (a Level, Build or Deploy Environment), those parameters can be given a different value for each Environment. That means that the same Phase can be reused in a lot of different Environments, each time performing a different task, which offers a lot of flexibility.

As you can see on the Connected Levels and Environments panel, our Tomcat Deploy phase is currently being used in 2 different places:

For an example of a more advanced usage of Parameters, look at the “contextPath” Phase Parameter. Its default value is set to /${applicationName}, and it has this value set in both the testdeploy and proddeploy Environments (you can see them by clicking the Edit _ icon in front of the _contextPath Parameter). Still, the Customers application is deployed to 2 different contexts, namely “customers_test” and “customers”.

How does this work?

The answer lies in a Deploy Parameter (named “applicationName”) which is defined on both Deploy Environments.

Go to Project Administration, and edit the Customers Project. Next, in the menu, select Deploy Environments > Deploy Parameters:

As you can see, for the testdeploy environment, the value of the “applicationName” parameter is “customers_test”, while for the proddeploy environment, the specified value is “customers”. When the Tomcat Deploy Phase is being executed, the property ${applicationName} will be replaced with the value of the Deploy Parameter, which yields the desired behavior.

For more information on Custom Phases and on how you can create them yourself, please refer to the IKAN ALM User Guide (chapter Global Administration, Phases and appendix Phases: General Information), and to the document Using and Developing Custom Phases.

The IKAN ALM Demo installation has its own jaas.config file located in ALM_HOME/system/security.

By default, the passwd.config file is used as a flat security file.

The IKAN ALM Demo Application uses this simple JAAS implementation whereby User Groups and Users are configured in a flat file. In the JAAS configuration file this is specified as follows (where e.g. ALM_HOME="home/ikan/ALMDemo"):

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

The encrypted password in MD5 encryption format can be generated with a utility like HashCalc (http://www.slavasoft.com/hashcalc/overview.htm) on Windows or GtkHash on Linux.

Adding a user with User ID “testuser” and password “testuser” who belongs to the ALM User and ALM Project User Groups:

This error may occur when a Demo Installation was interrupted. When you try to run the installation again, the Warning above may pop up. The reason is a lock file in the temp directory:

Search for a file named iz-ALMDemo.tmp and remove it.

This error may occur when installing the license.

Make sure that the license file was not modified.

Make sure that the license file was correctly transported to the installation machine (e.g., File size should be > 500 B).

Cause: the IKAN ALM Demo server is not running

Solution:

The last day of the 30 day trial period has ended. If you want to extend your trial period, you must request a new license by sending a mail to support@ikanalm.com.