As a developer that builds JEE applications that are deployed to IBM WebSphere application servers, I have spent a lot of time creating and configuring WebSphere application server profiles. There are several ways to automate the creation of a WebSphere server profile. The route I have chosen to take is a combination of leveraging built-in WebSphere scripts, server configuration archives and custom Jython scripts.

The package of sample scripts and configuration referenced throughout this article can be download from this repository on GitHub.

Why would I want to automate this?

Why not? As a developer completing a repetitive process, you should always be thinking… is there a way to automate this process and make it repeatable? Aside from that, there are many specific reasons why you would want to automate the creation of WebSphere server profile including:

• Reduce the amount of time it takes other developers to set up their workstation to run the application. Those who have worked with complex JEE applications running on WebSphere know it is not simple task to set up a new server profile, configure it and get your application running, especially when there is a lack of quality documentation about the application.
• Create a quality source of documentation that describes the server configuration requirements your application requires to run. You can define server configurations in a Word document and attempt to keep that document in sync with your application server environment as it changes, but that is always a challenging thing to do. The best and most current source of documentation for how to set up your server environment should be your scripts, which would have to be updated every time there is a change to application server configurations.
• Enable your continuous integration server to spin up new server instances on the fly without user intervention. If you are writing end-to-end integration tests for your application that run as part of your continuous integration, you may want to spin up a clean new application server instance each time (using the latest server configuration) before releasing your application. Scripting will enable you to do that.

Application Server Profiles in WebSphere

Developers who build JEE applications that are deployed on IBM WebSphere application servers are generally familiar with the concept of server profiles. Essentially a server profile is the definition of the application server that your application runs on. It includes all the server configurations that your application requires to run such as JDBC data sources, JMS queues, and system properties.

The concept of application server profiles has existed at least since WebSphere 6 and has been carried forward until at least WebSphere 8.5. Luckily many of the tools used to administer server profiles have not changed much through each release of WebSphere. During my initial experimentation, I found that many of the built-in scripts I used were available in WebSphere 7, 8 and 8.5. I also found that my custom Jython scripts were able to run on all three of these versions of WebSphere with little or no modification.

Server Profile Basics

Before diving into the automation process, there are a few key concepts and tools that you should understand including where server profiles actually reside on your computer. Generally all your server profiles are defined in a profiles directory wherever your WebSphere application server software is installed. The path to your WebSphere installation may differ depending on your selections during the installation process. You will need to know where your profiles are located. Here are some examples on a Windows machine:

• WebSphere 7 – C:\Program Files\IBM\SDP\runtimes\base_v7\profiles
• WebSphere 8 – C:\Program Files\IBM\WebSphere\AppServer\profiles

Useful Scripts and Commands

IBM provides a number of useful scripts that can be used via the command-line to manage your application server. These scripts are found in bin directory in the root of our WebSphere installation (ex. C:\Program Files\IBM\SDP\bin) or within the bin directory of your server profile (ex. C:\Program Files\IBM\SDP\runtimes\base_v7\profiles\bin). Open a command prompt in this directory and try some of the following commands. Note that many of the commands require you to specify the server profile you are dealing with since you can have multiple server profiles on your system.

To view a list of server profiles that have already been created:

manageprofiles -listProfiles

To delete a server profile:

manageprofiles -delete -profileName AppServer01

To start an application server:

startServer Server1 -profileName AppServer01

To stop an application server:

stopServer Server1 -profileName AppServer01

To backup the configuration of an existing server profile to a server configuration archive file:

backupConfig AppServer01.zip -profileName AppServer01

To restore a server configuration archive to an existing server profile:

restoreConfig AppServer01.zip -profileName AppServer01

Automating the Creation of the Server Profile

If you haven’t already downloaded the script package, then you should do so now. Some snippets of the script will be shown below for demonstration purposes.

The primary script used to automate the creation of WebSphere server profile is a Windows batch script. This batch script invokes all the necessary commands to create a new server profile and apply your server’s configuration settings. The script is divided into several steps each of which are described below.

Step 1 – Collect User Inputs

In order for the script to be portable, it prompts the user for inputs that could be unique depending on the machine it is being run on or the circumstances in which it is being run. For example, the script will prompt for:

1. An application prefix to use for naming the server profile itself as well as various components within the profile
2. The installation path of WebSphere on the user’s machine
3. An option to start the server automatically after the profile has been created

After collecting user input, provides the user with a description of what will be created and allows the user to back out of the process. For example, creating a server profile with the application prefix “MyServer” would look something like this:

A server profile will be created using the following settings:
 - profile name: MyServerProfile
 - profile path: C:\Program Files\IBM\SDP_RAD9\runtimes\base_v7\profiles\MyServerProfile
 - cell name: MyServerCell
 - node name: MyServerNode
 - server name: MyServer

Step 2 – Create An Empty Server Profile

The next step is to create the user profile based on the user’s inputs. The script makes use of the manageprofiles command provided by IBM to create the profile:

call %WAS_INSTALL_DIR%\bin\manageprofiles -create -profileName %PROFILE_NAME% -templatePath default -profilePath "%PROFILE_PATH%" -enableAdminSecurity false -cellName %CELL_NAME% -nodeName %NODE_NAME% -serverName %SERVER_NAME% -portsFile %APP_PREFIX%Ports.props -applyPerfTuningSettings development -isDeveloperServer -omitAction defaultAppDeployAndConfig

There are a number of switches used here to specify profile settings:

• -profileName specifies the name of the profile to be created and is based on the user’s input which was stored in the PROFILE_NAME variable
• -templatePath specifies the name of the template to base the profile creation on; IBM provides several different server templates that could be used but I opted to use the default template
• -profilePath specifies where the profile should be created; I opted to create the profile in the typical profiles directory within the WebSphere installation folder
• -enableAdminSecurity is set to false to avoid requiring a username and password to login to the administrative console from the browser
• -cellName, -nodeName and -serverName  specify names to be used for each of the respective scopes in the server profile and are generated based on the user-specified application prefix
• -portsFile allows you to specify the various ports that your server profile will be run on including your HTTP, HTTPS and administrative console ports; refer to the AppServer01Ports.props file in the provided script package for an example
• -applyPerfTuingSettings and -isDeveloperServer are set to indicate the server profile should be optimized for a developers machine
• -omitAction specifies that the default applications and server configurations that IBM provides should not be applied to the server profile since I have no use for these and would like to keep the server profile as light as possible

Step 3 – Restore Server Configuration

This step is optional but may be required under certain circumstances. Essentially you can restore a server’s configuration by restore a configuration archive file (sometimes referred to as a CAR file) or by restoring configuration from a properties file. There are benefits and limitations to both methods though.

Configuration Archives Files:

• A configuration archive file is an archive file with a .zip or .car extension that is generated using IBM-provided scripts. The archive contains a backup of the configuration files in the server profile directory and can be used at a later point to restore the profile.
• The configuration archive can be used to back up and restore nearly all server configurations (with some exceptions, see here).
• In my experience, the configuration archive is not a fool-proof way of sharing server configurations. Within WebSphere 7 the configuration archive seemed to be portable across different developer’s workstations however I did experience problems sharing a configuration archive for WebSphere 8.5.
• The down-side to using a configuration archive is that your server configurations are buried within the server profile’s XML files and not easily viewed or modified by a developer. Often times, the configuration archive is restored and then the developer has to login to the administrative console to make a number of changes to tweak the server’s configuration for their purposes.

Server Configuration Properties File:

• This properties file defines server configurations in a key-value pair format. A server profile’s configurations can be dumped to one of these properties files using custom JACL or Jython scripts that invoke IBM-provided APIs.
• There are certain limitations on which server profile configurations can actually get exported to a properties file.
• There are several benefits to using a properties file instead of a configuration archive:
  • Configuration is defined in a human-readable format and is self-documenting.
  • Configuration can be modified prior to running the script. For instance, a developer may want to adjust certain system properties or endpoints to match their target development environment.

Ideally you would only want to restore server configurations from a properties file and avoid use of the server configuration archive method if possible. In my case, there were certain configurations that I simply could not restore using the properties file. For instance I was unable to successfully export and restore custom SSL configurations. For that reason, I have chosen to use both mechanisms in my script in the following manner:

1. First the configuration archive is restored onto the server profile. This acts as the “base” level of configuration and includes configurations that were not possible to restore using properties files.
2. Secondly the server configuration properties file is applied to the server profile. This properties file acts as a “configuration override” and provides the developer with the ability to easily override whatever server configurations they need to override. For instance, different projects may have different properties files to support their specific development environments.

To restore the server configuration archive, the IBM-provided restoreConfig script is used:

call %PROFILE_PATH%\bin\restoreConfig %PROFILE_NAME%.zip -force -profileName %PROFILE_NAME%

To restore the server configuration properties file, the IBM wsadmin script is used along with a custom Jython script:

call %PROFILE_PATH%\bin\wsadmin -lang jython -conntype NONE -f applyConfig.py %PROFILE_NAME%.props

Step 4 – Start the Server

At this point, the server profile has been created and server configuration has been restored. All that is left to do is start the server:

call "%PROFILE_PATH%\bin\startServer" %APP_PREFIX%

Once the script completes, the administrative console can be accessed in the browser to verify that the server has started successfully and contains the restored server configurations. Typically, the WebSphere 7 administrative console is located at http://localhost:9060/ibm/console/login.doc although the port may vary depending on the ports you have configured in your script.

Potential Script Enhancements

These scripts could be further enhanced to improve the automation process, for example:

• The process of exporting a server configuration archive and/or server configuration properties file from an existing fully configured server profile could be automated. I have provided an example of this in the sample scripts (refer to ExtractServerProfileConfig.bat).
• The server configuration properties file is quite verbose and length. The effort required by a developer to modify configurations in this properties file could be reduced or eliminated by doing a few things:
  • If you know there are only certain properties that need to be modified on the developer’s workstation then you could prompt for these values during the first step of the CreateServerProfile.bat script then use the user’s inputs to modify the properties file programmatically (for instance, using VBScript).
  • If the sub-set of properties that could require modifications by a developer is substantial, you could create a second culled-down version of the properties file containing only those essential configurations. Within the CreateServerProfile.bat script, you could then first apply the larger, complete server configuration properties file followed by the culled-down version that was potentially modified by the developer. Remember that these properties files act as “overlay” files and can be used to modify the server profile’s existing configurations.

References

Sample WebSphere 7 Server Profile Scripts

Importing and exporting WebSphere Application Server version 6/v7/v8 profiles

WebSphere Application Server Profile Management in Rational Application Developer