Setting up WebSphere Application Server

Before you can deploy ELM applications war files, you must set up your WebSphere Application Server.

Before you begin

Ensure you have completed the following tasks:

Important: Starting in version 6.0.6.1, the required Java version is 8.
On UNIX systems, ensure that the Open File Limit value is properly set. For more information, see Planning to install on UNIX and Linux systems.
The database is created. If you use the default Derby database for evaluation purposes, ensure the location to the database in the teamserver.properties file is an absolute path.
1. Go to JazzInstallDir/server/conf/app where JazzInstallDir is where you installed Jazz® Team Server and app is a directory for jts, ccm, rm, qm, dcc, gc, lqe, or relm.
2. For all applications except for LQE, open teamserver.properties for editing.
3. For the LQE application, go to the lqe/template directory. Copy the dbconnection.properties file to the /lqe directory and open the file for editing.
4. Locate the Derby database location com.ibm.team.repository.db.jdbc.location=conf/jts/derby/repositoryDB, and change the location with an absolute path. For example, com.ibm.team.repository.db.jdbc.location=C:/Progra~1/IBM/JazzTeamServer/server/conf/jts/derby/repositoryDB.
The Java™ 2 Security option must be turned off. If this option is turned on in WebSphere Application Server, the web application will not start.
1. In WebSphere Integrated Solutions Console, click Security > Global security.
2. Under Java 2 security, clear the check box for Use Java 2 security to restrict application access to local resources.
3. Ensure that the Enable administrative security and Enable application security check boxes are selected.
To ensure strong security practices, examine and adjust the following settings:
Note: If all applications that will be deployed in the same WebSphere Application Server have Jazz Security Architecture SSO enabled, the following steps are unnecessary.
- Ensure that the Use available authentication data when an unprotected URI is accessed application server security setting is selected. If you are using the Integrated Solutions Console for the server, use the following steps to verify this setting:
  1. In WebSphere Integrated Solutions Console, click Security > Global security > Web and SIP security > General settings.
  2. Click the Use available authentication data when an unprotected URI is accessed check box.
  3. Click OK and Save directly to the master configuration.
- To ensure that the LTPA cookies are secure, enable the Requires SSL setting:
  1. In WebSphere Integrated Solutions Console, click Security > Global security > Web and SIP security > Single sign-on (SSO).
  2. Click the Requires SSL check box.
  3. Also ensure that Set security cookies to HTTPOnly to help prevent cross-site scripting attacks is selected.
  4. Click OK and Save directly to the master configuration.
- Set the Restrict cookies to HTTPS sessions to ensure that the session cookies include the secure field. Enabling this feature restricts the exchange of cookies to HTTPS sessions:
  1. In WebSphere Integrated Solutions Console, click Server > Server Types > WebSphere application servers > server_name > Session management > Enable cookies.
  2. Select the Restrict cookies to HTTPS sessions check box.
- Add the following session management custom property to avoid SESN0008E error message when a user logs out without terminating the session:
  1. In WebSphere Integrated Solutions Console, click Servers > Server Types > WebSphere application servers.
  2. Click server1 and then in the Container Settings section, click Session management.
  3. In the Additional Properties section, click Custom properties.
  4. Click New and enter the following information:
    - Name: InvalidateOnUnauthorizedSessionRequestException
    - Value: true
  5. Click Apply and save directly to the master configuration.
To improve performance of the operating procedures, change the WebContainer thread pool size settings:
1. In WebSphere Integrated Solutions Console, click Servers > Server Types > WebSphere application servers.
2. Click server1 and then in the Additional Properties section, click Thread pools.
3. In the Thread pools page, click WebContainers.
4. Enter 200 in the Minimum Size and Maximum Size fields.
5. Click OK and save directly to the master configuration.
In WebSphere Application Server version 9.0, the Contexts and Dependency Injection (CDI) 1.2 is enabled by default. If CDI is enabled, it might increase unnecessary performance overhead if the application is not using it. ELM applications do not use CDI and to gain performance, you can disable CDI by setting some Java custom properties and manifest attributes. For detailed instructions, see this IBM Support troubleshooting document.

The Jazz web interface requires that authentication be configured in order to perform authorization and personalize the application.

About this task

This document does not provide details for configuring WebSphere authentication or SSL, which is a complex topic. Detailed information about the various authentication and encryption options is covered in the WebSphere Application Server documentation. For more information, go to the WebSphere Application Server documentation and search for this phrase: Securing applications and their environment.

Important: The figures used for heap sizes and JVM arguments are only a suggestion; set the value according to your environment. A typical medium-size team can use a value of 4096 MB, providing 4 GB of heap memory for the Jazz Team Server process on a 64-bit computer with a minimum of 8 GB of physical memory. It is important to use the same amount for Initial and Maximum heap sizes.

When increasing the Java heap size, ensure that enough unused physical memory is available on the machine to cover the increase. If sufficient physical memory is not available, either install additional memory or take into account the effect on overall performance that occurs.

It is also important to have more physical memory than is required by all of the processes on the machine combined to prevent paging or swapping. Paging reduces the performance of the system and affects the performance of the Java memory management system.

Procedure

Verify or update the WebSphere Application Server level. For a list of supported versions and fix packs, see the Hardware and software requirements page.
Jazz Team Server requires several specific settings on the Java Virtual Machine in which it runs. To set these properties, in the WebSphere Integrated Solutions Console, click Servers > Server Types > WebSphere application servers > Server1.
Under Server Infrastructure, click Java and Process Management > Process definition.
Under Additional Properties, click Java Virtual Machine.
In the Generic JVM arguments field, type the following line:
```
-Xmx4g -Xms4g -Xmn1g
-Xgcpolicy:gencon -Xnocompressedrefs
```
Note: Mac OS X is unsupported.
```
-Xmx4g -Xms4g -Xmn1g
-XX:MaxPermSize=768M 
-XX:ReservedCodeCacheSize=512M 
-XX:CodeCacheMinimumFreeSpace=2M
```
```
-Xmx4g -Xms4g -Xmn1g
-Xgcpolicy:gencon -Xcompressedrefs
-Xgc:preferredHeapBase=0x100000000
```
```
-Xmx4g -Xms4g -Xmn1g
-Xgcpolicy:gencon -Xcompressedrefs
-Xgc:preferredHeapBase=0x100000000
```
Tip: If you need more heap size, then you can use the following setting, replacing {N} with the amount of memory to be used and {N/4} with 1/4 of the total memory. For example, if -Xmx is set to 8g, -Xmn should be set to 2g.
```
-Xgcpolicy:gencon -Xmx{N} -Xms{N} -Xmn{N/4}
```
For Engineering Requirements Management DOORS® Next only: The -Xmn value should be 33% of the -Xms value. For example, if the -Xmx size is 4gb, the -Xmn should be 1365m. The following Deployment wiki document contains useful information about Engineering Requirements Management DOORS Next sizing and tuning: Sizing and tuning guide for Rational DOORS Next Generation 6.0: configuration management.

For Lifecycle Query Engine only: If Lifecycle Query Engine application pages become unresponsive as a result of memory issues, see this technote for troubleshooting.
Click Apply, and then click Save directly to the master configuration.
One of the custom properties you must add is JAZZ_HOME, a system property that specifies where to find certain configuration files. This property uses a URL rather than a simple path, so specify the value as a file-style URL: file:///file path. Under Java Virtual Machine > Additional Properties, click Custom properties.
Remember: You must use three forward slashes (///) after file:

Important: In a distributed environment, when you are using a separate application server for each web application, you must add these custom properties for each instance of the WebSphere Application Server.
Click New, enter JAZZ_HOME in the Name field, and enter file:///JazzInstallDir/server/conf in the Value field. Substitute JazzInstallDir with the location of Jazz Team Server installation directory. For example, enter file:///C:/PROGRA~1/IBM/JazzTeamServer/server/conf on Windows or enter file:///home/user/IBM/JazzTeamServer/server/conf on UNIX systems.
Note: To avoid problems, do not use spaces in file paths. For the Program Files directory you can use PROGRA~1, and for the Program Files (x86) directory, you can use PROGRA~2.
Click OK.
Repeat step 8 and add these custom properties:
- Name: java.awt.headless Value: true
- Name: org.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin Value: true
- If you install the Lifecycle Query Engine application: Name: lqe.config.location Value: file:///JazzInstallDir/server/conf/lqe
- If you install the Link Index Provider application: Name: ldx.config.location Value: file:///JazzInstallDir/server/conf/ldx
- If you are connecting to an Oracle database, Name: ORACLE_JDBC_DRIVER_FILE Value: Absolute path to the JDBC driver/ojdbc8.jar
  Note: The path to the JDBC driver must be an absolute path. Do not use URL path (file:///). For more information about Oracle Java Database Connectivity (JDBC) connections, see Setting up an Oracle database.
  
  Restriction: Because of a defect in Oracle JDBC driver 12.1.0.2.0, this version of the driver cannot be used. For details, see repotools -createTables command fails with ORA-01000 on Oracle 12 on the IBM Support portal page.
- If you are connecting to a SQL Server database, Name: SQLSERVER_JDBC_DRIVER_FILE Value: Absolute path to the JDBC driver/sqljdbc42.jar
  Note: The path to the JDBC driver must be an absolute path. Do not use URL path (file:///). For more information about SQL Server JDBC connections, see Setting up an SQL Server database.
- Name: log4j.configuration Value: file:///JazzInstallDir/server/conf/startup_log4j.properties
  Note: The settings that the startup_log4j.properties file contains are used at the early stages in the startup process to pass messages to the WebSphere Application Server SystemOut.log file. After the early stages, each Jazz application switches to using the application-specific settings from the JazzInstallDir/server/conf/app context/log4j.properties file.
If your user ID or password contain non-ASCII characters, such as double-byte characters, add the following property:
- Name: default.client.encoding Value: UTF-8
Click Save directly to the master configuration.
Complete the following steps to define the Jazz Reporting Service (JRS) shared libraries. You will reference this shared library when configuring the Report Builder.
In the WebSphere Integrated Solutions Console navigation pane, expand Environment and click Shared libraries.
In the Scope list, select Node=MachineNameNode01, Server=server1 and click New.
Enter the shared library name JRS Shared Library, add a description, and set the classpath to: JRS_install_dir\server\conf\rs\WAS_SharedLibrary. For example: C:\Progra~1\IBM\JazzTeamServer\server\conf\rs\WAS_SharedLibrary.
Under Class Loading, select the Use an isolated class loader for this shared library check box, click Apply, and then click Save.
Add a custom property to make sure the application works with SameSite enabled. Perform the following steps:
1. In the WebSphere Integrated Solutions console, click Server > Server Types > WebSphere application servers, then click on the server_name .
2. Under Web Container Settings, click Web container transport chains.
3. Click the chain_name used by your ELM application (chains that use the ELM application's port number).
4. Click HTTP inbound channel.
5. Click Custom properties, then click New.
6. Under General Properties specify the following:
  - In the Name field, enter sameSiteNone.
  - In the Value field, enter JAZZ_AUTH_TOKEN,JSESSIONID,JazzFormAuth,LtpaToken2,X-com-ibm-team-foundation-auth-loop-avoidance ,jfs-oauth-access-token*,jfs-oauth-access_token-secret*, jfs-request-token-* ,JSA_AUTH_COMPLETE,JSA_SESSION_IDENTITY,JSA_CSRF*.
7. Click Apply or OK.
8. Click Save to save your configuration changes.
9. Add the SameSite setting to the first entry that uses the ELM port and then make sure that the other entries that use the same ELM port have the same value.
For changes to take effect, restart the application server.

What to do next

(When the server starts for the first time)

Note: A migration occurs when the server starts for the first time, you need to check if there is any error in the CCM log file. The Perform Enterprise Extensions migration tasks start the migration and the Completed Enterprise Extensions migration tasks end the task.