CLM deployment automation for WAS - departmental topology

Authors: IndradriBasu, SudhakarFrederick
Build basis: Rational solution for Collaborative Lifecycle Management (CLM) 2013

To deploy CLM applications in WebSphere Application Server, it is necessary to configure the WebSphere environment for the applications to function properly. Configuring WebSphere and deploying the CLM applications could take more than 140 steps when performed manually and could be time consuming, error prone and critical steps can be overlooked while carrying out the configuration. This topic provides one possible approach to accelerate CLM application deployment in a stand-alone Websphere Application Server environment with the Departmental Topology to mitigate some of the challenges mentioned above.

Introduction

The purpose of this possible solution is to provide a customizable and parameterized approach to automate both the Websphere configuration and the deployment of the CLM applications. By default, the WebSphere installation comes with an administrative utility called *"wsadmin"* and is used in this scenario to execute jython scripts to configure and deploy the CLM applications.

The solution consists of 3 parts: 2 Jython scripts and a properties file as described below. The scripts can be downloaded here.

1. The properties file (config.props)

• The properties file is a single source of information acting as an input file for both the Jython scripts. Prior to running either script the property values in this file need to be edited to match the target deployment environment. The example properties file provided here is mostly self explanatory and pre-populated with example values; however, the details of each parameter are described in Configuration Reference section.

2. WebSphere Configuration and deployment scripts

2.1 WebShphere Environment Configuration script configureWASforCLM.py

The first script automates setting the necessary WebSphere configuration parameters needed before deploying Jazz CLM applications in your WebSphere environment. The set of tasks (from Setting up WebSphere Application Server), the script automates are listed below:

• Disables Java2 security parameters
• Enables Administrative Security (if not already enabled)
• Sets the unprotected URI authentication system property
• Sets the JVM Heap parameters (parameterized)
• Sets platform dependent generic JVM arguments
• Creates necessary JVM Custom Properties (JAZZ_HOME, log4.configuration, etc) for CLM applications
• Sets trace specification properties
• Creates Session Management custom properties
• Configures "WebContainer" ThreadPool parameters
• Configures/Enables SSO (Requires SSL) properties
• Configures and validates LDAP Registry

Each of the tasks above and the values for thier parameters are controlled by and parameterized via the properties file (config.props).

In addition, this script will do these tasks:

• Prompt and restart the WebSphere environment if required
• Optionally, create logs file with execution and configuration details
• Display command line help on syntax errors

2.2. CLM application deployment script DeployCLM.py

The DeployCLM.py script deploys the CLM applications in a WebSphere environment and automates the following tasks:

• Deploys the CLM applications into the target WebSphere application server
• Applies automatically derived or user specified application context roots
• Maps LDAP groups definitions with CLM application to enable Jazz based application security
• Optionally, the script can create and configure virtual hosts for the CLM Applications to support logically distributed deployment which also acts as an alternative for reverse proxy. For more information, refer to Configuring virtual hosts for applications on WebSphere Application Server
• Starts CLM applications and displays status

In addition this script will:

• Optionally, create a logs file with execution and configuration details.
• Display command line help on syntax errors.

Prerequisites and Assumptions

The following prerequisites must be met before using the scripts:

1. The reader is assumed to have a basic understanding of the CLM Installation process and basic WebSphere administrative and installation functions
2. CLM Applications are installed on the host server.
   Refer to Installing Jazz Team Server and the Rational solution for Collaborative Lifecycle Management applications
3. WebSphere Application Server is installed and the target Application Server profile exists.
4. If you are going to configure LDAP authentication, ensure the CLM server is able to communicate with the LDAP server host.
   Refer to the System Requirements for more details.
5. When running the scripts the username and password arguments should be the one that may have been provided during the creation of the Application Server profile. However, if the configureLDAP parameter is set to true, after the script has run to completion you must access the WAS administrative console by using the LDAP identity specified in the ldapAdminUser parameter.

Configuration and execution

Download [https://jazz.net/wiki/pub/Deployment/CLMAutomationScriptsforWASDepartmentalTopology/SampleAutomationCLMScripts_Departmental_20131002.zip][the scripts]] to an appropriate location on the target server. To begin with, the properties file (config.props) needs to be configured with the details of the target WebSphere environment and then the appropriate Jython script needs to be executed with wsadmin.

Note:

• Both Jython scripts use the same properties file as a single source of information about the target deployment environment
• You can download and store scripts and properties anywhere in the file system of your WebSphere Application Server host

A. Configuring the Properties file

Modify the properties file config.props according to your target deployment environment. The provided config.props file has example values filled in plus comments on what the expected values should be. Also Refer to the Configuration Reference section for a detailed list of configuration parameters.

NOTE:

• The properties file (config.props) is structured as follows:

[section]

parameter = value

where:

[section] must not be changed and is a specific name that identifies the start of a collection of parameter values, such as those relating to LDAP configuration.

parameter must not be changed and is a name for a configuration parameter

value is a user modifiable string

WARNING DO NOT change or remove any Section or parameter. Only the value can be changed, otherwise the program may fail to execute.

B. Running the script to Configure WebSphere for CLM Applications

As mentioned above, the configureWASforCLM.py script can be run for accelerating WebSphere Application Server environment before deploying the CLM applications.

Procedure:

1. On the WebSphere Server host, open a command prompt or a terminal window.
2. Change directory to WebSphere_Install_Dir/AppServer/profiles/<profile name>/bin (default location for wsadmin.bat/sh.
3. Run the configureWASforCLM.py.

Syntax:

 wsadmin.bat|sh –lang jython –username <websphere admin username> -password <websphere admin user password> -f <script file path> --c <config file path> 
[--l <log file path>] 

Example:
C:\IBM\WebSphere\AppServer\profiles\AppSrv01\bin>wsadmin.(bat/sh) -lang jython -username admin -password Password -f C:/temp/configureWASforCLM.py 
–-c C:/temp/config.props –-l C:/temp/configWAS.log 

Note:

• At this point WebSphere is unaware of the LDAP configuration hence the username and password should be the one that may have been provided during the creation of the Application Server profile.
• This script will work as per the values declared in the configuration properties file (config.props)
• The script prompts before saving the Websphere profile configuration and it is recommended to check for any errors in the output or in the log file before saving.

C. Running the script to deploy CLM applications in WebSphere

Now that you have configured the WebSphere environment, the next step is to deploy the CLM applications in WebSphere. After a successful execution of the configuration script (configWASforCLM.py) , the DeployCLM.py script can be run to deploy the CLM applications along with the needed configuration as specified in the properties file (config.props).

Procedure:

1. On the WebSphere Server host, open a command prompt or a terminal window.
2. Change directory to WebSphere_Install_Dir/AppServer/profiles/<profile name>/bin.
3. Running the DeployCLM.py (refer to the syntax below).

Syntax:

wsadmin.(bat/sh) –lang jython [–username <websphere admin user name> -password <websphere admin user password>] -f <script file path> --c <config file path> 
[--l <log file path> ]

Example:
C:\IBM\WebSphere\AppServer\profiles\AppSrv01\bin>wsadmin .bat -lang jython -username clmadmin -password Password -f C:/temp/DeployCLM.py 
–-c C:/temp/config.props –-l C:/temp/deployCLM.log 

Note:

• If the WebSphere environment has been configured to authenticate via LDAP, the username and password needed to be supplied here should be of the “ldapAdminUser” parameter of the config.props file (refer to details of LDAP parameters in the next section).

Configuration Reference

The table below contains the description of all the possible parameters in the properties file.

Parameter	Description
[WebSphere]
profileName	WebSphere Profile Name. Example: AppSrv01
[JazzServer]
JazzInstallDir	The path where you have installed the CLM tools. Example: C:\IBM\JazzTeamServer. Note: If you have installed in C:\Program Files\...\...\ use shortnames like progra~1 instead. Or if you have installed in C:\Program Files (x86)\...\...\ then use progra~2 in the path.
WARFileLoc	Specify the folder path in Jazz Server Installation directory where the .war files are located. Example: C:/IBM/JazzTeamServer/server/webapps
[SQLServer]
isSQLServerDB	Values: true or false If you are going to use SQL Server Databases for CLM applications. Set this value to true.
sqlDriverPath	Specify the SQL server JDBC driver file path. If the above option is false, you can ignore this parameter.
[Oracle]
isORACLEDB	Values: true or false If you are going to use ORACLE Databases. Set this value to true.
oraDriverPath	Specify the ORACLE JDBC driver file path. If the above option is false, you can ignore this parameter.
[JVMHEAP]
alterHeapSize	Values: true or false IMPORTANT: The program configures JVM Heap parameters. If you don't want the program to alter the JVM parameters then set the value to false. By default this value is set to true.
minHeap	The minimum heap size that is available to the JVM (in megabytes). Note: By default the value is 4096 which is recommended for small deployment teams.
maxHeap	The maximum heap size that is available to the JVM (in megabytes) Note: By default the value is 4096 which is recommended for small deployment teams.
[WCThreadPool]
minSize	IMPORTANT: The program configures WebContainer threadpool size. This parameter is to set the minimum threadpool size. The suggested minimum size is 200.
maxSize	This parameter sets the maximum threadpool size or the maximum number of threads allowed in the pool. The suggested maximum size is 200.
[JVMGenericArguments]
default	Values: true , false or custom Generic JVM parameters are optional parameters.
	If the default parameter is set to: 'true' => the program will impose default configuration as mentioned in the CLM Infocenter. 'false' => the program will NOT add any values for the Generic arguments. 'custom' => then the program will add the value that is specified in the 'customValue' parameter of this section.
customValue	If you have set the default parameter value to custom then you can add a custom value to the generic JVM arguments. Example: -Xgcpolicy:gencon -Xmx{N} -Xms{N} -Xmn{N/8} -Xcompressedrefs -Xgc:preferredHeapBase=0x100000000
[LDAP]
configureLDAP	Values: true or false IMPORTANT: If you want the program to configure LDAP, set this value to true. If the value is false, the value of all the parameters in this section will be ignored the program will skip LDAP configuration.
ldapAdminUser	Specify the name of the user with WAS Primary Administrative privileges that is defined in the LDAP registry
isSIdentityAuto	Default value is true. Contact your WebSphere administrator if you encounter any problems.
ldapServer	LDAP server hostname. NOTE: It is recommended to use fully qualified Domain name to avoid any problems.
ldapServerPort	LDAP server port. Default is 389.
ldapType	For Microsoft Active Directory us ACTIVE_DIRECTORY. For IBM Tivoli Directory Server use IBM_DIRECTORY_SERVER. For any custom LDAP server use CUSTOM. For any other than the above, please consult WebSphere product documentation.
searchTimeout	Number of seconds for LDAP to respond before canceling a request. Default value is 120 seconds.
BaseUserDN	Specifies the base distinguished name (DN) of the directory service, which indicates the starting point for LDAP searches on the directory server for Users.
BaseGroupDN	Specifies the base distinguished name (DN) of the directory service, which indicates the starting point for LDAP searches on the directory server for Groups.
BindDName	Specifies the DN for the application server to use when binding to the directory service
BindPasswd	Specifies the password for the application server to use when binding to the directory service
CaseInSensitive	Specifies that a case insensitive authorization check is performed when using the default authorization.
[LDAPAdvancedProperties]
UserFilter	Specifies the LDAP user filter that searches the user registry for users. Example: UserFilter = (&(sAMAccountName=%v)(objectcategory=user))
GroupFilter	Specifies the LDAP group filter that searches the user registry for groups Example: GroupFilter = (&(cn=%v)(objectcategory=group))
UserIdMap	Specifies the LDAP filter that maps the short name of a user to an LDAP entry. Example: UserIdMap = user:sAMAccountName
GroupIdMap	Specifies the LDAP filter that maps the short name of a group to an LDAP entry. Example: GroupIdMap = *:cn
GroupMemberIdMap	Specifies the LDAP filter that identifies user-to-group relationships. Example: GroupMemberIdMap = memberof:member
[ApplicationContextRoot]
ADMIN	Specifies the context root for ADMIN application. Example: /admin
JTS	Specifies the context root for JTS application. Example: /jts
CCM	Specifies the context root for CCM application. Example: /ccm
QM	Specifies the context root for QM application. Example: /qm
RM	Specifies the context root for RM application. Example: /rm
CLMHELP	Specifies the context root for the CLMHelp application. Example: /clmhelp
RMC	Specifies the context root for Converter application. Example: /converter
[JazzSecurity]
configureGroups	Values: true or false By default the value set to true Set this value to false if you do not want the program to map the LDAP groups for the CLM applications which acts as application security or if you want to configure group mappings manually
JazzAdmins	Name of the LDAP group for Jazz administrators
JazzDWAdmins	Name of the LDAP group for Jazz Data warehouse administrators
JazzGuests	Name of the LDAP group for Jazz guest users
JazzProjectAdmins	Name of the LDAP group for Jazz Project Administrators
JazzUsers	Name of the LDAP group for Jazz users
[VirtualHosts]
configureVHosts	Values: true or false The default value is set to false. Set this value to true if you want this program to create and configure virtual hosts in WebSphere application server for the CLM applications.
jts_VHost	Creates virtual host for Jazz Team Server (/jts) application.
ccm_VHost	Creates virtual host for Change and Configuration Management (/ccm) application.
rm_VHost	Creates virtual host for Requirements Management (/rm) application.
qm_VHost	Creates virtual host for Quality Management (/qm) application.
admin_VHost	Creates virtual host for Lifecycle Project Administration (/admin) application.
clmhelp_VHost	Creates Virtual host for Information Center (/clmhelp) application.
converter_VHost	Creates virtual host for Requirements Management view mode version of the graphical artifacts (/converter) application.

Related topics: Automatically deploying the Collaborative Lifecycle Management applications on WebSphere Application Server

External Links:

• None

Additional contributors: None

Questions and comments: