Installing HATS applications on an IBM i server

The WebSphere administrative console is a browser-based graphical administrative interface for configuring and managing WebSphere resources. You can use the WebSphere administrative console to display and change your WebSphere Application Server - Express configurations, and to manage your WebSphere Application Server - Express resources.

To start the administrative console on a workstation, follow these steps:

1. Start the HTTP Server Administration Web interface.
2. Click the Manage tab.
3. Select your application server from the Server list.
4. Enable the adminconsole application if it is not already enabled.
   1. In the navigation menu, click Manage installed applications.
   2. Select the adminconsole application.
   3. Click Properties.
   4. For Application Enablement, select Enabled.
5. To start your application server, click the Start button ( ) at the top of navigation menu. If your application server is running, you must stop it and restart it.
6. In the navigation menu, click Launch Express Console.
7. When prompted, enter a user ID. The WebSphere administrative console is displayed in the browser window.
   Note:

   The user ID does not need to be an IBM i user profile. This user ID is used only to track which users make changes to the application server configuration.

WebSphere Application Server - Express provides a command line administrative tool named wsadmin, which you can use to run administrative commands interactively or through the use of Jacl script files. The wsadmin tool uses the Bean Scripting Framework (BSF), which supports a variety of scripting languages to configure and control WebSphere Application Server - Express. In WebSphere Application Server - Express, wsadmin supports the Jacl and Jython scripting languages.

To start an interactive wsadmin session, follow these steps:

1. Enter the Start Qshell (STRQSH) command on an IBM i command line.
2. Use the cd command to change to the bin directory of the product installation root:

   cd /QIBM/ProdData/WebASE51/ASE/bin

3. At the Qshell prompt, enter this command:

   wsadmin -instance instance

   where instance is the name of the instance that you want to administer.

Before you exit the interactive session, run this command to save your configuration changes:

$AdminConfig save

If you do not run this command, wsadmin discards your changes when you exit the interactive session.

You can use the WebSphere administrative console to install enterprise applications on your application server. These instructions assume the use of WebSphere Application Server - Express.

To install an application, follow these steps:

1. Start the WebSphere administrative console.
2. Expand Applications and click Install New Application.
3. Specify the path of the application that you want to install.
   • If the application is stored on your workstation, select Local path.
   • If the application is stored on a node in your WebSphere Application Server - Express cell, select Server path. For a server path, specify the fully qualified path of the application. For example, if the EAR file myApp.ear for your application is located in the installableApps directory of the myAppSvr instance, specify:

     /QIBM/UserData/WebASE51/ASE/myAppSvr/installableApps/myApp.ear

     Note:

     When using the Server path option, the QEJBSVR user profile must have *RX authority to the EAR or WAR file and the directory where the file is located.
4. If the application is a WAR module, specify the context root.
5. Click Next.
6. Specify options for bindings and mappings.
7. Click Next.
   Note:

   WebSphere Application Server - Express reads the deployment descriptor of your application before it displays the next page. It uses the information from the deployment descriptor to determine which information you need to provide before you install the application. As a result, you may not see all of the panels described here.
8. Provide options to perform the installation

   On this panel, you can specify several general options that determine how WebSphere Application Server - Express installs your application.

   1. If you want WebSphere Application Server - Express to precompile JavaServer Pages (JSP) files as part of the installation, select Pre-compile JSP. If you do not select this option, JSPs are compiled the first time they are accessed.
   2. Specify the directory where you want to install the application EAR file. By default, the application is installed in the /QIBM/UserData/WebASE51/ASE/instance/installedApps/node directory, where instance is the name of your instance and node is the name of the node for your instance. It is recommended that you use the default value.
   3. Specify where the application configuration used during runtime comes from. If this option is not selected, configurations specified during application installation, and stored in the configuration files, are used. If this option is selected, the configuration specified during installation is ignored, and the settings in the original application are used. The default is not to use the binary configuration. It is recommended that you use the default setting.
   4. Specify a name for the application. Application names must be unique within a cell.
      Note:

      Because WebSphere Application Server - Express does not support enterprise beans, the Deploy EJBs option does not apply. Ignore this option.
   5. By default, WebSphere Application Server - Express creates MBeans for various resources (such as servlets or JSP files) within an application when the application is started. These MBeans allow you to use the HTTP Server Adminisration interface and the wsadmin administrative tool to manage your application. It is recommended that you use the HTTP Server Administration interface to manage applications. If you do not want to use this capability, deselect this option.
   6. To enable class reloading when application files are updated, select Enable class reloading. If you enable class reloading, you can update your application and apply the changes without restarting the application server. In addition, WebSphere Application Server periodically scans the application for updates. It may be convenient to have reloading turned on in a development environment. In a production environment, it is suggested reloading be turned off, or that the reload interval be large. Enabling class reloading has these effects on your application:
      • For non-Web modules, enabling class reloading sets reloadEnabled to true in the deployment.xml file for the application. If an application's class definition changes, the application server run time stops and starts the application to reload application classes.
      • For Web modules such as servlets and JavaServer page (JSP) files, a Web container reloads a Web module only when the IBM extension reloadingEnabled in the ibm-web-ext.xmi file is set to true. You can set reloadingEnabled to true when editing your Web module's extended deployment descriptors in an assembly tool. To disable reloading of a Web module, set the IBM extension reloadingEnabled in the ibm-web-ext.xmi file to false. Or, if the Web module has the IBM extension reloadingEnabled in the ibm-web-ext.xmi file set to true, enable class loading, and set the Reload Interval property to zero (0).
   7. If you enable class reloading, you can also specify the reload interval (in seconds). This value specifies how often the application server scans the application's file system for updated files. The default value is specified by the reload interval attribute in the IBM extension (META-INF/ibm-application-ext.xmi) file of the EAR file or the IBM extension file for each Web module in the EAR file. To enable reloading, specify a value between 1 and 2147483647). To disable reloading, specify zero (0). If reloading is not enabled with the Enable class reloading property, the reload interval setting is ignored.
   8. For the Deploy WebServices option, specify whether the Web services deploy tool (wsdeploy) runs during application installation. The tool generates code that is required for applications that use Web services. The default is not to run the wsdeploy tool. You must enable this setting if the EAR file contains modules that use Web services and you have not previously run the wsdeploy tool on the EAR file.
9. Map resource references to resources

   If your application defines resource references, specify JNDI names for the resources that represent the logical names defined in resource references. You must bind all of the resource references to a resource before you click Finish. The resources are defined in your WebSphere Application Server - Express configuration.

10. Map virtual hosts for web modules
    If your application contains Web modules, you must map each Web module to a virtual host. Select a virtual host to map to a Web module defined in the application. The port number specified in the virtual host definition is used in the URL that enables access to objects such as servlets and JSP files in the Web module.

    Note:

    You should never select the admin_host virtual host. This is a special virtual host used by the WebSphere administrative console application.
11. Map security roles to users/groups

    If the application has security roles defined in its deployment descriptor, you can specify users and groups to map to each role. Select the checkbox beside Role to select all of the roles or select individual roles. You can map predefined users such as Everyone or All Authenticated to each role. To select specific users or groups from the user registry:

    1. Select a role and click Lookup users or Lookup groups.
    2. On the Lookup users/groups panel, enter search criteria to view a list of users or groups from the user registry.
    3. Select one or more users or groups from the results displayed.
    4. Click OK to map the selected users or groups to the selected role or roles.
12. Map RunAs roles to user

    If the application's deployment descriptor defines one or more RunAs roles, specify the RunAs user name and password for every RunAs role. RunAs roles are used by enterprise beans that must run as a particular role while interacting with another enterprise bean. Select the checkbox for the role or roles that you want to configure. After you select a role, enter values for the user name and password, then click Apply.

13. Mapping Resource Environment References to Resources

    If your application contains resource environment references, specify JNDI names of resources that map to the logical names defined by the references. If each resource environment reference does not have a resource associated with it, the installation wizard displays a validation error when you click Finish.

14. Replacing RunAs System to RunAs Roles

    If your application defines RunAs Identity as System Identity, you can optionally change it to RunAs role and specify a user name and password for the RunAs role specified. Selecting System Identity implies that the invocation is done using the WebSphere Application Server - Express security server ID and should be used with caution.

15. On the Summary panel, verify that the installation settings are correct. For the Cell/Node/Server item, click Click here to verify the settings.
16. Click Finish.
17. Save the application server configuration. The application is registered with the administrative configuration and application files are copied to the target directory when you save the configuration.

You can use wsadmin to deploy applications into your application server. The wsadmin tool supports non-interactive installation, in which you run a single command that specifies the application to install, and interactive installation, in which you are prompted for information about the installation.

To use the wsadmin tool to deploy applications into your application server, follow these steps:

1. On the IBM i command line, run the STRQSH (Start Qshell) command.
2. Run the cd command to change to the directory that contains the wsadmin tool:

   cd /QIBM/ProdData/WebASE51/ASE/bin

3. Start wsadmin.
4. At the wsadmin prompt, run one of these commands:
   • This command uses the EAR file and the command option information to install the application:

     $AdminApp install earfile {-server myAppSvr}

     where earfile is the fully qualified path of the EAR file that you want to install and myAppSvr is the name of your application server instance.
   • This command starts an interactive installation that prompts you through a series of installation tasks:

     $AdminApp installInteractive earfile

     where earfile is the fully qualified path of the EAR file that you want to install.
5. Run this command to save your changes:

   $AdminConfig save

You can use the administrative console to start your applications.

To start an application, follow these steps:

1. Start the WebSphere administrative console.
2. Expand Applications and click Enterprise applications.
3. Select the check box for the application or applications that you want to start.
4. Click Start.

You can use wsadmin to start applications in your application server.

To start an application with wsadmin, follow these steps:

1. On the IBM i command line, run the STRQSH (Start Qshell) command.
2. Run the cd command to change to the directory that contains the wsadmin tool:

   cd /QIBM/ProdData/WebASE51/ASE/bin

3. Start wsadmin.
4. At the wsadmin prompt, run this command to identify the application manager MBean for the server where the application resides and assign it the appManager variable:

   set appManager [$AdminControl queryNames type=ApplicationManager,*]

   This command returns the application manager MBean.
5. Run this command to start the application:

   $AdminControl invoke $appManager startApplication myApp

   where myApp is the name of the application that you want to start.