Install application files with the console

Install application files with the console

+
Search Tips | Advanced Search

Overview

Installing application files consists of placing assembled enterprise application, Web, enterprise bean (EJB), or other installable modules on a server or cluster configured to hold the files. Installed files that start and run properly are considered deployed.
Before installing enterprise application files, ensure that you are installing your application files onto a compatible deployment target. If the deployment target is not compatible, select a different target.
To install new enterprise application files to a WAS configuration, you can use the following options:

Administrative console
wsadmin scripts
Java MBean programs
Java programs that call J2EE DeploymentManager (JSR-88) methods

This topic describes how to use the console to install an application, EJB component, Session Initiation Protocol (SIP) module (SAR), or Web module.
After you start performing the steps below, click Cancel to exit if you decide not to install the application. Do not simply move to another console page without first clicking Cancel on an application installation page.

Procedure

Click...
Applications | Install New Application

in the console navigation tree.

On the first Preparing for application installation page:

Specify the full path name of the source enterprise application file (.ear file otherwise known as an EAR file).
The EAR file that you are installing can be either on the client machine (the machine that runs the Web browser) or on the server machine (the machine to which the client is connected). If you specify an EAR file on the client machine, then the console uploads the EAR file to the machine on which the console is running and proceeds with application installation.
You can also specify...

standalone Web application archive (WAR)
SAR
Java archive (JAR)

If you are installing a standalone WAR or SAR file, specify the context root.

Select whether to view all installation options.

Prompt me only when additional information is required

Display the module mapping step as well as any steps that require you to specify needed information to install the application successfully.

Show me all installation options and parameters

Display all installation options. To use Generate default bindings, which supplies default values for incomplete bindings, select this option.

Click Next.

If you selected Show me all installation options and parameters, for the second Preparing for application installation page:

Select whether to generate default bindings.
Use the default bindings causes any incomplete bindings in the application to be filled in with default values. Existing bindings are not altered. You can customize default values used in generating default bindings. For example, you can specify a JNDI prefix for EJB files in EJB modules, default data source and connection factory settings for EJB modules, virtual host for Web modules, and so on. Preparing for application installation settings describes available customizations and provides sample bindings.

Click Next.
If security warnings are displayed, click Continue. The Install New Application pages are displayed. If you chose to generate default bindings, you can proceed to the Summary step. Example: Installing an EAR file using the default bindings provides sample steps.

Specify values for installation options as needed.
You can click on a step number to move directly to that panel instead of clicking Next.

Panel Description
Select installation options On the Select installation options panel, provide values for the settings specific to WAS. Default values are used if you do not specify a value.
Map modules to servers On the Map modules to servers panel, specify deployment targets where you want to install the modules contained in your application. Modules can be installed on the same deployment target or dispersed among several deployment targets. Each module must be mapped to a target server.
On a single-server product, a deployment target can be an appserver or Web server.
On a multiple-server product, a deployment target can be an appserver, cluster of appservers or Web server.
Provide options to compile JSPs If the Precompile JavaServer Pages files setting is enabled on the Select installation options panel and your application uses JavaServer Pages files, then you can specify JSP compiler options on the Provide options to compile JSPs panel.
Provide JNDI names for beans If your application uses EJB modules, on the Provide JNDI names for beans panel, specify a JNDI name for each enterprise bean in every EJB module. You must specify a JNDI name for every enterprise bean defined in the application. For example, for the EJB module MyBean.jar, specify MyBean.
Map default data sources for modules containing 1.x entity beans If your application uses EJB modules that contain Container Managed Persistence (CMP) beans that are based on the EJB 1.x specification, for Map default data sources for modules containing 1.x entity beans, specify a JNDI name for the default data source for the EJB modules. The default data source for the EJB modules is optional if data sources are specified for individual CMP beans.
Map data sources for all 1.x CMP beans If your application has CMP beans that are based on the EJB 1.x specification, for Map data sources for all 1.x CMP beans, specify a JNDI name for data sources to be used for each of the 1.x CMP beans. The data source attribute is optional for individual CMP beans if a default data source is specified for the EJB module that contains CMP beans. If neither a default data source for the EJB module nor a data source for individual CMP beans are specified, then a validation error displays after you click Finish and the installation is cancelled.
Map EJB references to beans If your application defines EJB references, for Map EJB references to beans, specify JNDI names for enterprise beans that represent the logical names specified in EJB references. Each EJB reference defined in the application must be bound to an EJB file before clicking Finish on the Summary panel.
Map resource references to resources If your application defines resource references, for Map resource references to resources, specify JNDI names for the resources that represent the logical names defined in resource references. You can optionally specify login configuration name and authentication properties for the resource. After specifying authentication properties, click OK to save the values and return to the mapping step. Each resource reference defined in the application must be bound to a resource defined in your WAS configuration before clicking on Finish on the Summary panel.
Map virtual hosts for Web modules If your application uses Web modules, for Map virtual hosts for Web modules, select a virtual host from the list that should map to a Web module defined in the application. The port number specified in the virtual host definition is used in the URL that is used to access artifacts such as servlets and JSP files in the Web module. Each Web module must have a virtual host to which it maps. Not specifying all needed virtual hosts will result in a validation error displaying after you click Finish on the Summary panel.
Map security roles to users or groups If the application has security roles defined in its deployment descriptor then, for Map security roles to users or groups, specify users and groups that are mapped to each of the security roles. Select Role to select all of the roles or select individual roles. For each role, you can specify whether predefined users such as Everyone or All authenticated users are mapped to it. To select specific users or groups from the user registry:

Select a role and click Lookup users or Lookup groups.

On the Lookup users or groups panel displayed, enter search criteria to extract a list of users or groups from the user registry.

Select individual users or groups from the results displayed.

Click OK to map the selected users or groups to the role selected on the Map security roles to users or groups panel.

Map RunAs roles to users If the application has Run As roles defined in its deployment descriptor, for Map RunAs roles to users, specify the Run As user name and password for every Run As role. Run As roles are used by enterprise beans that must run as a particular role while interacting with another enterprise bean. Select Role to select all of the roles or select individual roles. After selecting a role, enter values for the user name, password, and verify password and click Apply.
Ensure all unprotected 1.x methods have the correct level of protection If your application contains EJB 1.x CMP beans that do not have method permissions defined for some of the EJB methods, for Ensure all unprotected 1.x methods have the correct level of protection, specify if you want to leave such methods unprotected or assign protection with deny all access.
Bind listeners for message-driven beans If your application contains message driven enterprise beans, for Bind listeners for message-driven beans, provide a listener port name or an activation specification JNDI name for every message driven bean.
Map default data sources for modules containing 2.x entity beans If your application uses EJB modules that contain CMP beans that are based on the EJB 2.x specification, for Map default data sources for modules containing 2.x entity beans, specify a JNDI name for the default data source and the type of resource authorization to be used for the default data source for the EJB modules. You can optionally specify a login configuration name and authentication properties for the data source. When creating authentication properties, click OK to save the values and return to the mapping step. The default data source for EJB modules is optional if data sources are specified for individual CMP beans.
Map data sources for all 2.x CMP beans If your application has CMP beans that are based on the EJB 2.x specification, on the Map data sources for all 2.x CMP beans panel, for each of the 2.x CMP beans specify a JNDI name and the type of resource authorization for data sources to be used.
You can optionally specify a login configuration name and authentication properties for the data source. When creating authentication properties, click OK to save the values and return to the mapping step. The data source attribute is optional for individual CMP beans if a default data source is specified for the EJB module that contains CMP beans. If neither a default data source for the EJB module nor a data source for individual CMP beans are specified, then a validation error is displayed after you click Finish and installation is cancelled.
Ensure all unprotected 2.x methods have the correct level of protection If your application contains EJB 2.x CMP beans that do not have method permissions defined in the deployment descriptors for some of the EJB methods, on the Ensure all unprotected 2.x methods have the correct level of protection panel, specify whether you want to assign a specific role to the unprotected methods, add the methods to the exclude list, or mark them as unchecked. Methods added to the exclude list are marked as uncallable. For methods marked unchecked no authorization check is performed prior to their invocation.
Provide options to perform the EJB Deploy If the Deploy enterprise beans setting is enabled on the Select installation options panel, then you can specify options for the EJB deployment tool on the Provide options to perform the EJB Deploy panel. On this panel, you can specify extra class paths, RMIC options, database types, and database schema names to be used while running the EJB deployment tool.
Map shared libraries On the Shared library references and Shared library mapping panels, specify shared library files for your application or Web modules to use. A defined shared library must exist to associate your application or module to the library file.
Provide JSP reloading options for Web modules If your application uses Web modules, for Provide JSP reloading options for Web modules, configure the class reloading of JavaServer Pages files.
Map context roots for Web modules If your application uses Web modules, for Map context roots for Web modules, specify a context root for each Web module in the application.
Initialize parameters for servlets If your application uses Web modules, for Initialize parameters for servlets, specify or override initial parameters that are passed to the init method of Web module servlet filters.
Map environment entries for Web modules If your application uses Web modules, for Map environment entries for Web modules, configure the environment entries of Web modules such as servlets and JSP files.
Map resource environment entry references to resources If your application contains resource environment references, for Map resource environment entry references to resources, specify JNDI names of resources that map to the logical names defined in resource environment references. If each resource environment reference does not have a resource associated with it, after you click Finish a validation error is displayed.
Correct use of system identity If your application defines Run-As Identity as System Identity, for Correct use of system identity, you can optionally change it to Run-As role and specify a user name and password for the Run As role specified. Selecting System Identity implies that the invocation is done using the WAS security server ID and should be used with caution as this ID has more privileges.
Correct isolation levels for all resource references If your application has resource references that map to resources that have an Oracle database doing backend processing, for Correct isolation levels for all resource references, specify or correct the isolation level to be used for such resources when used by the application. Oracle databases support ReadCommitted and Serializable isolation levels only.
Bind message destination references to administered objects If your application uses message driven beans, for Bind message destination references to administered objects, specify the JNDI name of the J2C administered object to bind the message destination reference to the message driven beans.
If multiple message destination references are linked to the same message destination, only one JNDI name is collected. When a message destination reference links to the same message destination as a message driven bean and the destination JNDI name has been collected already, the destination JNDI name for the message destination reference is not collected.
Provide JNDI names for JCA objects If your application contains an embedded .rar file, for Provide JNDI names for JCA objects, specify the name and JNDI name of each J2C connection factory, J2C administered object and J2C activation specification.
Bind J2C activationspecs to destination JNDI names If your application contains an embedded .rar file, its activationSpec property has the value Destination, and its introspected type is javax.jms.Destination, for Bind J2C activationspecs to destination JNDI names, specify the jndiName value for each activation bound to it.
Select current backend ID If your application has EJB modules for which deployment code has been generated for multiple backend databases using an assembly tool, for Select current backend ID, specify the backend ID representing the backend database to be used when the EJB module runs.
For information on backend databases, refer to EJB deployment tool.
This step is not shown if the Deploy enterprise beans setting is enabled on the Select installation options panel and if a database type other than None is specified on the Provide options to perform the EJB Deploy panel.
Provide options to perform the Web services deployment If the Deploy Web services setting is enabled on the Select installation options panel and your application uses Web services, then you can specify wsdeploy command options on the Provide options to perform the Web services deployment panel. For information on this panel, refer to descriptions of the wsdeploy -cp and -jardir options.
Configure remote request dispatch properties If you are using a remote request dispatcher, we need to first configure it for use. Remote Request Dispatcher (RRD) is a pluggable extension to the Web container that allows application frameworks, servlets and JavaServer Pages to include content from outside of the current executing resource’s Java virtual machine (JVM) as part of the response sent to the client. Refer to Remote request dispatcher property settings for information on where to configure these properties in the administration console.

On the Summary panel, verify the cell, node, and server onto which the application modules will install:

Beside Cell/Node/Server, click Click here.

Verify the settings.

Return to the Summary panel.

Click Finish.

Results
Several messages are displayed, indicating whether your application file is installing successfully.
If Validate input off/warn/fail on the Select installation options panel is set to warn, the default, several validation warnings might be displayed. If the setting is fail, the validation warnings might cause errors.
If you receive an OutOfMemory exception and the source application file does not install, your system might not have enough memory or your application might have too many modules in it to install successfully onto the server. If lack of system memory is not the cause of the exception, package your application again so the .ear file has fewer modules.
If lack of system memory and the number of modules are not the cause of the exception, check the options you specified on the Java Virtual Machine page of the appserver running the administrative console. Then, try installing the application file again.

During installation certain application files are extracted in the directory represented by the configuration session and, when the configuration is saved, these files are saved in the WAS configuration repository. On Windows machines, there is a limit of 256 characters for file paths. Therefore, the application installation might fail if the path for application files in the configuration session or in the configuration repository exceeds the limit of 256 characters. You might see FileNotFound exceptions with path name too long in the message. To overcome such problems, make application names and module URI names shorter in length, which helps reduce the file path length. Then, try installing the application file again.

What to do next
After the application file installs successfully...

Save the changes to the configuration.
The application is registered with the administrative configuration and application files are copied to the target directory, which is app_server_root/installedApps/cell_name by default or the directory that you designate.
For a multiple-server product, files are copied to remote nodes when the configuration on the deployment manager synchronizes with the configuration on individual nodes.

Start the application.

Test the application. For example, point a Web browser at the URL for the deployed application and examine the performance of the application. If necessary, edit the application configuration.

Preparing for application installation settings

Select installation options settings

Provide options to perform the EJB Deploy settings

Bind listeners for message-driven beans settings

Related concepts

Enterprise (J2EE) applications
Application bindings

Related tasks

Manage shared libraries
Assembling applications
Installing applications with the wsadmin tool
Troubleshooting deployment

Related Reference
Example: Installing an EAR file using the default bindings

Panel	Description
Select installation options	On the Select installation options panel, provide values for the settings specific to WAS. Default values are used if you do not specify a value.
Map modules to servers	On the Map modules to servers panel, specify deployment targets where you want to install the modules contained in your application. Modules can be installed on the same deployment target or dispersed among several deployment targets. Each module must be mapped to a target server. On a single-server product, a deployment target can be an appserver or Web server. On a multiple-server product, a deployment target can be an appserver, cluster of appservers or Web server.
Provide options to compile JSPs	If the Precompile JavaServer Pages files setting is enabled on the Select installation options panel and your application uses JavaServer Pages files, then you can specify JSP compiler options on the Provide options to compile JSPs panel.
Provide JNDI names for beans	If your application uses EJB modules, on the Provide JNDI names for beans panel, specify a JNDI name for each enterprise bean in every EJB module. You must specify a JNDI name for every enterprise bean defined in the application. For example, for the EJB module MyBean.jar, specify MyBean.
Map default data sources for modules containing 1.x entity beans	If your application uses EJB modules that contain Container Managed Persistence (CMP) beans that are based on the EJB 1.x specification, for Map default data sources for modules containing 1.x entity beans, specify a JNDI name for the default data source for the EJB modules. The default data source for the EJB modules is optional if data sources are specified for individual CMP beans.
Map data sources for all 1.x CMP beans	If your application has CMP beans that are based on the EJB 1.x specification, for Map data sources for all 1.x CMP beans, specify a JNDI name for data sources to be used for each of the 1.x CMP beans. The data source attribute is optional for individual CMP beans if a default data source is specified for the EJB module that contains CMP beans. If neither a default data source for the EJB module nor a data source for individual CMP beans are specified, then a validation error displays after you click Finish and the installation is cancelled.
Map EJB references to beans	If your application defines EJB references, for Map EJB references to beans, specify JNDI names for enterprise beans that represent the logical names specified in EJB references. Each EJB reference defined in the application must be bound to an EJB file before clicking Finish on the Summary panel.
Map resource references to resources	If your application defines resource references, for Map resource references to resources, specify JNDI names for the resources that represent the logical names defined in resource references. You can optionally specify login configuration name and authentication properties for the resource. After specifying authentication properties, click OK to save the values and return to the mapping step. Each resource reference defined in the application must be bound to a resource defined in your WAS configuration before clicking on Finish on the Summary panel.
Map virtual hosts for Web modules	If your application uses Web modules, for Map virtual hosts for Web modules, select a virtual host from the list that should map to a Web module defined in the application. The port number specified in the virtual host definition is used in the URL that is used to access artifacts such as servlets and JSP files in the Web module. Each Web module must have a virtual host to which it maps. Not specifying all needed virtual hosts will result in a validation error displaying after you click Finish on the Summary panel.
Map security roles to users or groups	If the application has security roles defined in its deployment descriptor then, for Map security roles to users or groups, specify users and groups that are mapped to each of the security roles. Select Role to select all of the roles or select individual roles. For each role, you can specify whether predefined users such as Everyone or All authenticated users are mapped to it. To select specific users or groups from the user registry: Select a role and click Lookup users or Lookup groups. On the Lookup users or groups panel displayed, enter search criteria to extract a list of users or groups from the user registry. Select individual users or groups from the results displayed. Click OK to map the selected users or groups to the role selected on the Map security roles to users or groups panel.
Map RunAs roles to users	If the application has Run As roles defined in its deployment descriptor, for Map RunAs roles to users, specify the Run As user name and password for every Run As role. Run As roles are used by enterprise beans that must run as a particular role while interacting with another enterprise bean. Select Role to select all of the roles or select individual roles. After selecting a role, enter values for the user name, password, and verify password and click Apply.
Ensure all unprotected 1.x methods have the correct level of protection	If your application contains EJB 1.x CMP beans that do not have method permissions defined for some of the EJB methods, for Ensure all unprotected 1.x methods have the correct level of protection, specify if you want to leave such methods unprotected or assign protection with deny all access.
Bind listeners for message-driven beans	If your application contains message driven enterprise beans, for Bind listeners for message-driven beans, provide a listener port name or an activation specification JNDI name for every message driven bean.
Map default data sources for modules containing 2.x entity beans	If your application uses EJB modules that contain CMP beans that are based on the EJB 2.x specification, for Map default data sources for modules containing 2.x entity beans, specify a JNDI name for the default data source and the type of resource authorization to be used for the default data source for the EJB modules. You can optionally specify a login configuration name and authentication properties for the data source. When creating authentication properties, click OK to save the values and return to the mapping step. The default data source for EJB modules is optional if data sources are specified for individual CMP beans.
Map data sources for all 2.x CMP beans	If your application has CMP beans that are based on the EJB 2.x specification, on the Map data sources for all 2.x CMP beans panel, for each of the 2.x CMP beans specify a JNDI name and the type of resource authorization for data sources to be used. You can optionally specify a login configuration name and authentication properties for the data source. When creating authentication properties, click OK to save the values and return to the mapping step. The data source attribute is optional for individual CMP beans if a default data source is specified for the EJB module that contains CMP beans. If neither a default data source for the EJB module nor a data source for individual CMP beans are specified, then a validation error is displayed after you click Finish and installation is cancelled.
Ensure all unprotected 2.x methods have the correct level of protection	If your application contains EJB 2.x CMP beans that do not have method permissions defined in the deployment descriptors for some of the EJB methods, on the Ensure all unprotected 2.x methods have the correct level of protection panel, specify whether you want to assign a specific role to the unprotected methods, add the methods to the exclude list, or mark them as unchecked. Methods added to the exclude list are marked as uncallable. For methods marked unchecked no authorization check is performed prior to their invocation.
Provide options to perform the EJB Deploy	If the Deploy enterprise beans setting is enabled on the Select installation options panel, then you can specify options for the EJB deployment tool on the Provide options to perform the EJB Deploy panel. On this panel, you can specify extra class paths, RMIC options, database types, and database schema names to be used while running the EJB deployment tool.
Map shared libraries	On the Shared library references and Shared library mapping panels, specify shared library files for your application or Web modules to use. A defined shared library must exist to associate your application or module to the library file.
Provide JSP reloading options for Web modules	If your application uses Web modules, for Provide JSP reloading options for Web modules, configure the class reloading of JavaServer Pages files.
Map context roots for Web modules	If your application uses Web modules, for Map context roots for Web modules, specify a context root for each Web module in the application.
Initialize parameters for servlets	If your application uses Web modules, for Initialize parameters for servlets, specify or override initial parameters that are passed to the init method of Web module servlet filters.
Map environment entries for Web modules	If your application uses Web modules, for Map environment entries for Web modules, configure the environment entries of Web modules such as servlets and JSP files.
Map resource environment entry references to resources	If your application contains resource environment references, for Map resource environment entry references to resources, specify JNDI names of resources that map to the logical names defined in resource environment references. If each resource environment reference does not have a resource associated with it, after you click Finish a validation error is displayed.
Correct use of system identity	If your application defines Run-As Identity as System Identity, for Correct use of system identity, you can optionally change it to Run-As role and specify a user name and password for the Run As role specified. Selecting System Identity implies that the invocation is done using the WAS security server ID and should be used with caution as this ID has more privileges.
Correct isolation levels for all resource references	If your application has resource references that map to resources that have an Oracle database doing backend processing, for Correct isolation levels for all resource references, specify or correct the isolation level to be used for such resources when used by the application. Oracle databases support ReadCommitted and Serializable isolation levels only.
Bind message destination references to administered objects	If your application uses message driven beans, for Bind message destination references to administered objects, specify the JNDI name of the J2C administered object to bind the message destination reference to the message driven beans. If multiple message destination references are linked to the same message destination, only one JNDI name is collected. When a message destination reference links to the same message destination as a message driven bean and the destination JNDI name has been collected already, the destination JNDI name for the message destination reference is not collected.
Provide JNDI names for JCA objects	If your application contains an embedded .rar file, for Provide JNDI names for JCA objects, specify the name and JNDI name of each J2C connection factory, J2C administered object and J2C activation specification.
Bind J2C activationspecs to destination JNDI names	If your application contains an embedded .rar file, its activationSpec property has the value Destination, and its introspected type is javax.jms.Destination, for Bind J2C activationspecs to destination JNDI names, specify the jndiName value for each activation bound to it.
Select current backend ID	If your application has EJB modules for which deployment code has been generated for multiple backend databases using an assembly tool, for Select current backend ID, specify the backend ID representing the backend database to be used when the EJB module runs. For information on backend databases, refer to EJB deployment tool. This step is not shown if the Deploy enterprise beans setting is enabled on the Select installation options panel and if a database type other than None is specified on the Provide options to perform the EJB Deploy panel.
Provide options to perform the Web services deployment	If the Deploy Web services setting is enabled on the Select installation options panel and your application uses Web services, then you can specify wsdeploy command options on the Provide options to perform the Web services deployment panel. For information on this panel, refer to descriptions of the wsdeploy -cp and -jardir options.
Configure remote request dispatch properties	If you are using a remote request dispatcher, we need to first configure it for use. Remote Request Dispatcher (RRD) is a pluggable extension to the Web container that allows application frameworks, servlets and JavaServer Pages to include content from outside of the current executing resource’s Java virtual machine (JVM) as part of the response sent to the client. Refer to Remote request dispatcher property settings for information on where to configure these properties in the administration console.