Developing on the cloud with Rational Application Developer and IBM Pure Application System

Authors: VictorSosa, JohnGough, RobbieMinshall, MaryYost, XiangYueGao
Build basis: IBM Software Delivery and Lifecycle Patterns v1

IBM Software Delivery and Lifecycle Patterns offering is a set of IBM Rational solutions, based on best practice implementations which are ready to be imported into IBM private cloud offerings including IBM PureApplication System and IBM Workload Deployer. The solutions are delivered in the form of Virtual System Patterns or Shared Services. A Virtual System Pattern (VSP) will contain all the components you need to fully deploy the solution including the operating system, database, application server and product code. Deployment scripts are also included which prompt the user for basic information about the environment and then deploy and configure the solution.

The steps depicted in this article are for IBM PureApplication System, but can be applied to IBM Workload Deployer as well.

IBM Rational Application Developer pattern

This pattern has a pre-installed stack of IBM products for rapid provisioning, meaning that you can quickly start contributing to a development project.

This IBM software stack is conformed by:

• IBM® Installation Manager v1.6.2
• IBM® Rational® Application Developer v8.5.1 iFix 1.
• IBM® Rational® Team Concert client v4.0.2
• IBM® Rational® Desktop Connection Toolkit for Cloud Environments v1.0.5.2
• IBM® WebSphere® Application Server Test Environment v7.0
• IBM® WebSphere® Application Server v8.0
• IBM® WebSphere® Application Server v8.5
• IBM® WebSphere® Application Server Liberty Profile v8.5
• IBM® WebSphere® SDK Java Technology Edition v7

This virtual system pattern also provides:

• RedHat® Enterprise Linux® v6.3
• TigerVNC Server v1.1.0
• TigerVNC Server applet v1.0.90
• XULRunner v1.9.2.13
• root user account enabled to be used in command-line mode by default.
• virtuser user account enabled for both command-line and VNC modes. This is the default non-root user.

Importing the pattern.

To import the pattern, use the importPatterns.py sample located in <ipas_cli>\samples folder.

Follow these steps to import the pattern into PureApplication System. It is assumed that the PureApplication System command-line toolkit is already downloaded in the local system and uncompressed.

1. Open a command terminal.
2. Change to the folder where the PureApplication System command-line toolkit is uncompressed.
3. Use the importPatterns.py sample to import the pattern. The syntax is as follows:

<ipas_cli>\bin\pure.bat -h <ipas_host> -u <ipas_user> -p <ipas_password> -f <ipas_cli>\samples\importPatterns.py -s <your_RAD_VSP.tar.gz>

Where:

• <ipas_cli>: Is the directory where the command-line package is uncompressed. For instance: C:\pure.cli
• <ipas_host>: The name or IP address of the PureApplication System target.
• <ipas_user>: User name which has access and permissions in the PureApplication System.
• <ipas_password>: Password of the user.
• <your_RAD_VSP.tar.gz>: The full path to the tar ball of the pattern in your local system. For instance C.\RAD_VSP_tarball\IBM_RAD_VSP.tar.gz

This work will take a while since it has to import the image into PureApplication System.

Description of the pattern parts

The pattern is conformed by two parts: Image part and script packages. Each have specific deployment parameters that can be used to customize depending on the deployment needs.

To see these parts do the following:

1. Go to Patterns > Virtual Systems
2. Look for IBM Rational Application Developer Pattern 8.5.1 iFix 1. You can filter out the patterns for a quick search.
3. Select the pattern and wait for the details in the pane at the right.
4. Scroll down to Topology for this pattern section.

Image part

This part contains the RHEL 6.3 OS image with basic OS functionality. Besides IBM software, no third party software is installed.

The image part contains several deployment parameters that can be configured for customization of each instance. Some of them are locked with default values (recommended and forced values in some cases), some other can be changed at deployment time i.e. not locked, and a couple others need to be explicitly specified at deployment time. All fields need to be fulfilled, otherwise the instance can't be created.

Parameter name	Description
VNC uses SSH Tunneling	Defaulted to True. Specifies whether SSH tunneling is desired to add more security to the VNC access or not. Not locked.
Virtual CPUs	Default: 2. Specifies how many CPUs this instance will have for processing. Not locked
Memory size	Default: 4096. Specifies in megabytes how much RAM the instance will have. Not locked.
Password for root	Not defaulted. Specifies the password for root user in the operating system. Not locked.
Password for virtuser	Not defaulted. Specifies the password for virtuser user in the operating system. Not locked.
Enable VNC	Defaulted to True. Specifies whether VNC will be used to access the remote desktop. In remote desktop environments (DaaS, Desktop as a Service) this should be True. Locked.
Jazz server instance URI	Defaulted to Unknown. Specifies the URI that will be configured in RAD's workspace for the RTC connection. If Unknown is specified, then no connection will be done in the workspace. Not locked.
Jazz username	Defaulted to Unknown. Specifies the user name for the RTC connection. If Unknown is specified in Jazz server instance URI parameter, then this value will be ignored. Not locked.
Jazz password	Specifies the user's password for the RTC connection. If Unknown is specified in Jazz server instance URI parameter, then this value will be ignored. Not locked.
RAD workspace	Defaulted to /home/virtuser/IBM/rationalsdp/workspace. Specifies the default workspace for RAD. If Unknown is specified in Jazz server instance URI parameter, then this value will be ignored. Locked.
RAD Installation Directory	Defaulted to /home/virtuser/IBM/SDP. Used internally by the RTC connection configuration. Do not modify this value. Locked.
User to configure the connection	Defaulted to virtuser. Used internally by the RTC connection configuration. Do not modify this value. Locked.
Use JDK 7 as default for new WAS 8.5 profiles	Defaulted to True. Specifies whether JDK 7 for new profiles is desired since WAS 8.5 comes with JDK 6 by default. Locked.
Rational License Key Server hostname	Defaulted to Unknown. To specify an already-existent Rational license server. If Unknown is specified, then this parameter will be ignored. Locked.
License server port	Defaulted to 27000. To specify an already-existent Rational license server port. If Unknown is specified in Rational License Key Server hostname parameter, then this parameter will be ignored. Locked.
Installation Manager data location	Defaulted to /home/virtuser/var/ibm/InstallationManager. Used by Rational License Key Server discovery service to configure the license information in IBM Installation Manager. Do not modify. Locked.
User running VNC process	Defaulted to virtuser. VNC session will be run by the specified user. Do not modify. Locked.
Password for VNC user	Not defaulted. Specifies the password for VNC virtuser user session. This is not the same as the operating system password. If this password is less than 6 character long, it will be fulfilled with padding zeros (0). For instance, if “123” is specified as the password, the resulting password will be “123000”. Not locked.
Screen Resolution for VNC session	Defaulted to 1280x1024. Screen resolution to dispatch the VNC remote desktop session. Not locked.

Script Packages

The virtual system pattern contains three script packages:

• Rational firewall configurator.
• Rational License Key Server discovery service.
• Rational enable root VNC.

The first two are included in the ready-to-deploy pattern, meaning that you don't need to add or modify anything in the pattern to use them.

The last one, is added to the script packages catalog, but it is not added by default in the virtual system pattern. If you need root VNC access to the desktop, just add it to the virtual system pattern. See Enabling root VNC access section

Rational firewall configurator script package

By default, the firewall of the RHEL OS image in the pattern is closed to any requests so there is a need to open the required ports to ensure the instance security.

These ports are specified in the ports_to_add parameter when deploying an instance, and can specify several port numbers separated by commas.

Port	Description
27000	Used by Rational License Key Server discovery service script package to allow the traffic between the License Server and the deployed instance. If you specified your own Rational License Key Server, you need to modify this port accordingly.
5801	Used by the VNC viewer applet that runs in a web browser for accessing root VNC session. This works only if root VNC session is enabled. See Enabling root VNC access section.
5802	Used by the VNC viewer applet that runs in a web browser for accessing virtuser VNC session.
5901	Used by the VNC viewer for accessing root VNC session. This works only if root VNC session is enabled. See Enabling root VNC access section.
5902	Used by the VNC viewer for accessing virtuser VNC session.

This parameter is locked by default, but you can unlock it so you can customize each deployment. See Unlocking deployment parameters.

Rational License Key Server discovery service script package

When used with Rational License Key Server Shared Service included in IBM Software Delivery and Lifecycle Patterns, it can automatically configure the token licensing for RAD and RTC client in this pattern.

The default parameter, im_data_location, specifies the location where Installation Manager holds the metadata for its own functioning. This is also where the license metadata is hold and therefore where the token license configuration is stored.

Note: This parameter is used internally by the script. Do not modify, otherwise the automatic configuration of the license will fail.

Rational enable root VNC script package

This script package is included in the tar ball archive and gets imported in the script packages catalog. It is not included in the virtual system pattern though.

If VNC access for root user is desired, this script package needs to be explicitly added in it. See Enabling root VNC access section

This script package provides the following parameters for deployment customization. All of them are required:

Parameter name	Description
root_uses_ssh	Defaulted to True. Specifies whether SSH tunneling is required to connect to the VNC session. See Accessing the remote desktop section.
root_vnc_password	The password used when attempting to access the VNC session with the root user. If the password is less than 6 character long, it will be fulfilled with padding zeros (0). For instance, if “123” is specified as the password, the resulting password will be “123000”.
root_vnc_resolution	Defaulted to 1280x1024. Screen resolution used to dispatch the VNC screen.

Deployment of the pattern

Deployment is the actual step that provides an instance to work with. To deploy the pattern do the following instructions:

1. Go to the PureApplication System Workload dashboard in a web browser.
2. Go to Patterns > Virtual Systems.
3. Search and select IBM Rational Application Developer Pattern v8.5.1
4. Click Deploy.
5. A dialog will come up. Enter the name of the instance to be deployed.
6. Configure the environment and schedule.
7. Click Configure virtual parts to expand it.
8. Click on Rational Application Developer.
9. Specify the deployment parameters for this instance. Note some of them have default values but others don't. All passwords need to be explicitly specified.
10. Click OK to dismiss the deployment parameters dialog.
11. Click OK to dismiss the deploy dialog.

Once the page is refreshed, you will see the status of the deployment. You can come back to this page on Instances > Virtual Systems page.

This will create a new instance. To know remote access details do the following:

1. Go to Instances > Virtual Systems.
2. Select your instance.
3. In Details pane, expand Virtual Machines and your instance information.
4. Scroll down and look for Network interface X, where X represents the public interface. That's your hostname and IP address.
   
5. In the bottom of the instance information, in Consoles section, you will see a VNC link, which will open a new web browser tab with an embedded VNC Viewer. See Accessing the remote desktop section.

Accessing the remote desktop

The remote desktop access is achieved via a VNC viewer. It depends on configuration of SSH enforcement at deployment time, meaning whether it was set to True or False.

The VNC session for virtuser is always on display 2 (port 5902). If you added Rational enable root VNC script package, the VNC session display is always 1 (port 5901)

With no SSH enforcement

If you specified False (to either root or virtuser or both) you can connect directly to the VNC session. Follow these steps.

1. Go to Instances > Virtual Systems
2. Select your instance.
3. In Details pane, expand Virtual Machines and your instance information.
4. Scroll down and look for Network interface X, where X represents the public interface. That's your hostname and IP address. Save it for future reference.
5. Open your VNC viewer.
6. Enter your <hostname>:1 or <hostname>:2 depending on your choice (root or virtuser VNC session).
   
7. Click Connect.
8. A password will be prompted, type the one you configured at deployment time.
9. Click OK.

At this point, you should be able to have a VNC session for the user you selected. If you selected virtuser, you can launch RAD from Applications > IBM Software Delivery Platform > IBM Rational Application Developer 8.5.

With SSH enforcement

If True was specified, you will need to create a VNC tunnel prior accessing the virtual desktop. It is highly recommend to use PuTTY to do that.

To create the tunnel follow these steps:

1. Open PuTTY.
2. In Session section, enter the hostname.
3. Select SSH as the connection type.
   
4. Go to Connection > SSH > Tunnels.
5. In Source Port enter the port of the VNC user's session (5901 for root and 5902 for virtuser).
6. In Destination enter localhost:<port>. The port as in step 5.
7. Click Add.
   PuTTY" />
8. If you want to configure another port (for another user) repeat steps 5 through 7 with the appropriate port values.
9. Optional: If you want to save these configurations, go back to Session, enter a name for the session and click Save. Then you'll be able to reload the session without the need to recreate the SSH configuration.
10. Click Open.
11. You will be prompted for a user and password. Use the credentials you specified at deployment time (OS credentials, not VNC).
    

Note: Keep the session opened as long as you keep working with your remote desktop. If you close it, the VNC session will be closed as well.

Now that you've configured the tunneling, let's proceed with the VNC connection:

1. Open your VNC viewer.
2. Enter localhost:<display> depending on your user choice. Use 1 for root (port 5901) or 2 for virtuser (port 5902)
   
3. Click Connect.
4. A password will be prompted, type the one you configured at deployment time.
5. Click OK.

At this point, you should be able to have a VNC session for the user you selected. If you selected virtuser, you can launch RAD from Applications > IBM Software Delivery Platform > IBM Rational Application Developer 8.5

Using the web VNC Client

In every IBM Rational Application Developer Pattern v8.5.1 instance, there is a link to open an embedded VNC viewer in the browser.

The main difference is the port it uses. The VNC server uses 5902 to dispatch the VNC sessions request, but in this case, it is using HTTP requests on port 5802. The VNC Applet server in turn takes that request in port 5802 and redirects it to 5902 so the real VNC server dispatches the VNC session to that port, 5802. Hence, the VNC session is dispatched to the web browser

To open this web client, do the following:

1. Go to Instances > Virtual Systems
2. Select your instance.
3. In Details pane, expand Virtual Machines and your instance information.
4. Go to the bottom of the Details pane and find Consoles section.
5. Click VNC link.

This will open a new browser tab with the VNC viewer.

If using SSH tunnel, add another port to your SSH Tunnel configuration in PuTTY using ports 5801, for root, or 5802, for virtuser, just like the image below and pointing to locahost as the hostname in the URL address bar.

Note: When using the VNC link in the Console section, it points always to virtuser VNC session (port 5802). If root user is desired, then <hostname>:5801 in the URL address bar of the web browser.

Enabling root VNC access

Enablement of the root VNC session is done via Rational enable root VNC script package. This script package will allow a root user to access its own remote desktop and graphically work on the instance.

Linux best practices dictate that root jobs must be done for administration purposes, not for daily work. This is why the Rational software will not be listed under Applications menu. If you want to launch either RAD, RTC client or any WAS instance as root, you will need to do it in the command-line.

To add this script package to the virtual system pattern, perform the next steps in PureApplication System Workload dashboard:

1. Go to Patterns > Virtual Systems.
2. Look for IBM Rational Application Developer Pattern v8.5.1 and select it.
3. Click Edit.
4. Expand Scripts section.
   
5. Drag and drop Rational enable root VNC script package onto Rational Application Developer part.
   
6. Optional: You can modify the default values of this script at this time.
7. Click Done Editing.
8. At deployment time you will need to specify the VNC password for root. Screen resolution and SSH tunneling parameters have default values.

Unlocking deployment parameters

Rational Application Developer Pattern v8.5.1 provides several deployment parameters to allow customization at deployment time but they are locked by default. To unlock them, and allow a more fine-grained customization, follow these steps:

1. Go to Patterns > Virtual Systems.
2. Look for IBM Rational Application Developer Pattern v8.5.1 and select it.
3. Click Edit.
   
4. Click on the small table with a pencil icon in the part you want to edit (Image part or script packages).
   
5. From the list in the popup dialog, click on the lock icon of the desired parameters.
   
6. Click OK.
7. Repeat on each of the parts.

You can modify the default deployment values of the parameters in this same dialog.

RAD Licensing

This pattern comes with a free trial license for 60 days. However, there are three ways to specify a valid license in Rational Application Developer Pattern v8.5.1: Specifying your own Rational License Key Server at deployment time, letting Rational License Key Server discovery service script package to configure the license on your behalf or bringing your own permanent license.

Bringing your own license: Floating license

When you deploy an instance, you are asked about two specific parameters:

• Rational License Key Server hostname
• Rational License Key Server port.

By specifying these two parameters, you are letting the deployment mechanism to configure the license on your behalf but with your information.

This means you need to check with your administrator for the correct hostname and port.

To verify, or fix, the license information in the instance, you can open Installation Manager and then manage your license information. In the instance in a VNC session:

1. Go to Applications > My Installation Manager > My Installation Manager.
2. Click on Manage Licenses.
3. Select the Rational Application Developer 8.5.1 installation package.
4. Select Configure Floating license support.
5. Click Next.
6. Accept the license agreement terms.
7. Click Next.
8. Inspect, or fix, your license server.
9. Click Cancel to close this dialog or Finish to save your changes.

Bringing your own license: Permanent license

If no Rational License Key Server is specified and no Rational License Key Server shared service is configured on the same cloud group this instance lives on, no valid license is configured there yet. It is running on a free trial license.

If you have a permanent license, you can do the following steps to configure it:

1. Go to Applications > My Installation Manager > My Installation Manager.
2. Click on Manage Licenses.
3. Select the Rational Application Developer 8.5.1 installation package.
4. Select Import product Activation Kit.
5. Click Next.
6. Browse to your Activation kit file.
7. Click Finish.

If you launch RAD, you will have a valid license for it.

Using Rational License Key Server discovery service script package

IBM Software Delivery and Lifecycle Patterns has a shared service that can be deployed in PureApplication System: Rational License Key Server Shared Service.

This service is used to allow automatic discovery of the license server on instances that are deployed on the same cloud group as the shared service.

In Rational Application Developer Pattern, there is a script package that allows this functionality: Rational License Key Server discovery service. This script package will find out the license server and configure the license on your behalf.

This script package is enabled by default in the pattern. No modification or update is needed.

Troubleshooting

OK button in Deploy pattern dialog doesn't start the deployment.

When deploying a new instance from a pattern, ensure all parameters have values, even if you don't actually have a value for that. For instance, this scenario applies to Rational License Key Server URL parameter and that's why it is provided with a default value “Unknown” which will make the process to skip this step.

RTC Connection is not auto-configured in my instance

When a RTC instance is provided in Jazz server instance URI parameter, make sure RAD workspace value is the desired one as well.

RTC connections are configured per workspace, hence if, for instance, you specify /home/virtuser/myWorkspace in RAD workspace parameter but you are opening /home/virtuser/workspace in RAD launcher, then the repository connection will not be present.

This means that the workspace you provide at deployment time will be the one that has the RTC connection. By default, the RAD workspace is /home/virtuser/IBM/rationalsdp/workspace

RAD doesn't have a valid license

Per RAD Licensing section, there are three ways to have a valid license in RAD:

1. Specifying a Rational License Key Server host and port, which implies the company has valid licenses for it. If not enough licenses, then talk to your administrator.
2. Applying a permanent license in Installation Manager, which implies the company owns licenses.
3. Use the Rational License Key Server shared service provided in IBM Software Delivery and Lifecycle patterns.

In these three ways, the first two are directly tied to company owned licenses. Engage with your system administrator or management line. In last one, there could be a couple of things to check:

1. Make sure you have virtualsystem 2.0.0.6 System plugin activated in Cloud > System Plugins in Foundation Pattern Type 2.0.0.6 prior deployment of an instance.
2. Make sure Rational License Key Server shared service is deployed and in Running status.
3. Make sure the Rational License Key Server shared service is deployed in the same cloud group as the RAD pattern.
4. Make sure Maestro scripts are executed when deploying an instance, look at the deployment history.

Must Gather Logs script is not gathering the logs from RAD workspace nor WAS profiles

The appropriate mechanism to have all the logs is using Must Gather Logs script in the Script Packages section of the deployed instance. To gather the logs, click on Execute Now link and wait for the script to finish.

This script package gathers all logs excepting two:

• RAD workspaces logs
• WAS profiles logs.

This is due to the fact that it is virtually impossible to know where are going to be those locations at deployment time. To gather them you will need either access the remote desktop via VNC or use SSH to gain access to the system and gather the logs manually

• <RAD Workspace>/.metadata/.log for RAD workspaces.
• <WAS_Profile>/logs for WAS profiles.

Can't connect to a remote server to do my development

There are situations where a development team needs to access to remote servers to do their work, like for example shared databases o remote application servers. By default, all ports are closed in the virtual machine and therefore all incoming or outgoing requests are rejected.

There is one script package, Rational firewall configurator, that is opening specific ports. You can edit the default value in it and specify the ports needed in the instance. This will help you to automatically configure the firewall in RHEL at deployment time.

If the instance is already deployed you can use the iptables service to open the ports needed. To do that you can perform the following commands as root user in a terminal:

Listing 1. How to open ports in the firewall

# iptables -I INPUT -p tcp --dport $PORT -j ACCEPT
# iptables -I OUTPUT -p tcp --sport $PORT -j ACCEPT
# iptables -I INPUT -p udp --dport $PORT -j ACCEPT
# iptables -I OUTPUT -p udp --sport $PORT -j ACCEPT

Where $PORT is the port number to open.

This instructions will open your firewall for the current session. If a reboot happens, this configuration will be lost, so it is recommended to save the firewall and restart it:

Listing 2. Saving and restarting iptables service

# /etc/rc.d/init.d/iptables save
# service iptables restart

Can't connect to the remote desktop on VNC

Are you using SSH tunnel? I.e. specified True in Use SSH tunnel parameter? If so, make sure you are properly configuring the SSH tunnel in PuTTY.

Also, make sure you are using the correct hostname (either the one in Network Interface field in the virtual machine information section or localhost if using SSH tunnel).

If trying to access to the remote desktop using the embedded VNC viewer in a web browser, make sure it is pointing to the correct port, either 5801 for root user, or 5802 for virtuser.

If using a VNC viewer different than the web browser based one, make sure you are pointing to the right display (1 or 2) or port (5901 or 5902)

Can't find the RAD launcher in root VNC session

According to Linux best practices, the root user must be used for administration only tasks. Therefore, it doesn't have direct launchers of RAD, WAS nor RTC.

If still this is desired, then you can launch RAD in a Terminal and do the following commands:

Listing 3. Launching RAD in command-line

# cd /home/virtuser/SDP
# ./eclipse -product com.ibm.rational.rad.product.v85.ide

This will launch RAD and you can then select a workspace where the root user will have access to.

You can create a launcher to run RAD by double-clicking an icon. Refer to the External links section.

SSH tunnel is configured but VNC link in Consoles section is not working

Whether you are using root or virtuser, make sure you are pointing to the correct port. Embedded VNC Viewer uses 5801 for root and 5802 for virtuser. Make sure you are using the correct one.

VNC link in Consoles section always points to virtuser VNC session. If you want to use root VNC session, then you will need to open a tab in the browser and point to <hostname>:5801 explicitly.

SSH tunnel rules apply for this embedded VNC viewer.

VNC Viewer can connect to the remote desktop, but the password seems to fail

There is a known limitation in VNC server regarding passwords: They need to be a 6 characters long and only the first 8 are significant.

At deployment time, if a password is less than 6 characters, it will append zeros to the password in order to fulfill this requirement.

VNC Clipboard is not working

VNC Clipboard is enabled by default for both virtuser user and root user, if explicitly enabled. This can be quickly identified by looking at the VNC Config window in the task bar. If this window is closed, the clipboard will not be enabled between both machines (local and remote).

To restart the clipboard program, run the following command in a Terminal as the desired user:

Listing 4. Starting vncconfig as virtuser

$ vncconfig -iconic -display 2 &

Listing 5. Starting vncconfig as root

# vncconfig -iconic -display 1 &

RAD hangs on password recovery after creating repository connection

This is a known problem on RTC client that is not related to RAD itself. The defect is tracked in Jazz.net site (Registration needed).

To avoid this problem, when specifying RTC credentials for the RTC Connection Repository deselect Remember my password in the Jazz Repository Connection window.

You can also disable UI prompt before creating a connection repository. Go to Window > Preferences > General/Security/Secure Storage > Disable UI Prompt

If this problem is happening, open a Terminal and kill the process running RAD. Then relaunch RAD in the same workspace and disable Remember my password in the Jazz Repository Connection window.

External links:

• IBM
• Learn more about IBM Software Delivery and Lifecycle Patterns v1.0
• Learn more about IBM PureApplication System.
• Learn more about Rational License type definitions.
• Learn more about Rational Application Developer 8.5.1.
• Learn more about Rational Team Concert client 4.0.2.
• Learn more about WebSphere Application Server
  • 7.0
  • 8.0
  • 8.5
  • Liberty Profile.
• How to use the PureApplication System command-line interface.
• When to work as root and when to work as a System user by Linux.org Admin.
• RedHat Enterprise Linux Step-by-Step guide. Using the desktop by RedHat Inc.
• vncpasswd (1) – Linux Man pages