Production Operations User Guide

Preparing and Deploying the EAR File

This chapter discusses the steps for preparing your application's Enterprise archive (EAR) file to be deployed.

Note: WebLogic Portal only supports deployment to a clustered or stand-alone server configuration. Deployment of a WebLogic Portal application to a non-clustered managed server is not supported.

This chapter includes the following topics:

Preparing the EAR File for Deployment

To bring your portal online in a production environment, it is first necessary to prepare your portal application. Typical preparation steps include modifying deployment descriptors for the product, building the Enterprise archive (EAR) with all its pre-compiled classes, and deciding if you want to compress that EAR into an archive or leave it exploded.

Configuring Portal Application Deployment Descriptors

Similar to any J2EE application, a portal application has a number of deployment descriptors that you may want to tune for your production environment.

Modifying Application Deployment Descriptors

Within the Portal application is the /META-INF directory that contains a number of deployment descriptors, including application-config.xml, a portal-specific deployment descriptor that contains cache configuration, behavior tracking, campaign, and commerce tax settings. If these values are different for your production environment than for your existing development settings, modify this file appropriately before building the portal application.

Modifying Web Application Deployment Descriptors

Within any portal web application is a /WEB-INF directory that contains a number of deployment descriptors you may need to modify for your production environment.

web.xml is a J2EE standard deployment descriptor. Among other settings, it has a set of elements for configuring security for the web application. For more details about web.xml see web.xml Deployment Descriptor Elements.

Note: If you are running your portal application on a managed server, you can improve the performance of the WebLogic Administration Portal by adding the following parameter to the web.xml file:

<context-param>
    <param-name>portalFileDirectory</param-name>
    <param-value>/</param-value>
</context-param>

This parameter takes advantage of an optimized call to an mbean that returns EAR content information. Without this parameter, the mbean call recursively searches for .portal files. To avoid the overhead of this recursive call, you can place all of your .portal files in one directory and specify the directory with the portalFileDirectory parameter. In the example above, all .portal files reside in the web application's root directory (/).

If you use this parameter, you must place all of the .portal files in the same directory under the portal web application. Use the <param-value> to specify the directory.

weblogic.xml is a standard WebLogic Server deployment descriptor for web applications that has a number of important descriptor entries. For more details, see: weblogic.xml Deployment Descriptor Elements.

Note: In a clustered production environment, it is important that you configure the <session-param> descriptor element in weblogic.xml to enable session replication to take place across the cluster. Without this setting, you will not have failover of a user's state information if a server in the cluster is stopped. You may need to add the following block to weblogic.xml.

<session-descriptor>

	<session-param>

		<param-name>PersistentStoreType</param-name>

		<param-value>replicated_if_clustered</param-value>

	</session-param>

</session-descriptor>

By default if PersistentStoreType is not set, it defaults to disabling persistent session storage.
The other commonly modified element in weblogic.xml for production environments is the <jsp-descriptor>. For production, it is common to make these modifications:

Turn off debugging by setting debug to false.
Precompile the JSPs in the web application to reduce the time needed to display pages on their first invocation by setting precompile to true.

Also set precompileContinue to true, because if any JSPs do not compile, deployment of the web application stops.

You may need to add these elements to weblogic.xml inside the existing <jsp-descriptor> section. For example:

<jsp-param> <param-name>precompile</param-name> <param-value>true</param-value> <param-name>precompileContinue</param-name> <param-value>true</param-value> </jsp-param>
In a compressed EAR environment, set pageCheckSeconds to -1 to disable polling of JSP pages for changes.

Modifying WebLogic Workshop Deployment Descriptors

WebLogic Workshop has a number of additional deployment descriptors that are important if you are developing web services. You can find information on these descriptors in WebLogic Workshop Internals.

Creating Content Management Repositories

Before packaging your application into an EAR file, use the WebLogic Administration Portal to create any content management repositories you want to use in your application. This means creating only the root repositories, not the content nodes and content items. After you create repositories, they are registered in the application-config.xml deployment descriptor. When you create the application EAR, application-config.xml becomes read-only and cannot be modified within the EAR. That is, you cannot add or remove repositories in the WebLogic Administration Portal when the application is in an EAR file.

For information on creating repositories, see Add a New Repository Connection.

Compiling with Your Runtime JVM

If you are going to use a particular Java Virtual Machine (JVM) in your production environment, it is a good idea to compile the EAR application with the JDK for that JVM. You can change the JVM for your WebLogic Workshop project by going to Tools > Application Properties, selecting WebLogic Server, and specifying the path to the JDK Home (root directory) you want to use.

Building a Portal Application with WebLogic Workshop

To deploy a portal application to a production environment, you must first build the application in WebLogic Workshop to compile necessary classes in the portal application. There are two options:

Build > Build EAR - Most common. Use this option to compile the classes and build the portal application as a compressed EAR.

or
Build > Build Application - Use this option to compile the classes and build the portal application as an exploded (uncompressed) EAR. This option, however, many not invoke all the same processing as Build EAR. Review how WebLogic Workshop treats deployment descriptors when Build EAR is run and determine if there is an impact. See WebLogic Workshop Internals for more information.

Alternatively, to generate an uncompressed EAR, you can run Build > Build EAR and then uncompress the generated EAR file.
After you create an exploded EAR, rename the application directory so that it has a .ear extension. For example, if the application directory is called myPortalApp, rename the directory to myPortalApp.ear. Adding the .ear extension to the directory name prevents deployment exceptions for exploded EARs.

Building In the Command Line

You can build your portal application from the command line using the wlwBuild command. This can make it easier for you to automate the process of building your application. See wlwBuild Command for more information.

Deploying the EAR for a New Application

This section provides instructions for the initial deployment of your portal application.

At this point you can deploy your portal application to the cluster. First, place the .ear file (or exploded EAR) on the filesystem of the administration server. To make it easier to redeploy changes to the application, place the file in a known location from which you will always deploy the application, such as the root directory of the administration domain.

The steps for initial application deployment to the administration server and managed servers, and the order with which you start the managed servers, differ in different scenarios. Table 5-1 describes different scenarios and the deployment/startup procedures that must be used for each.

Table 5-1 Initial Deployment/Startup Scenarios

Scenario	Deployment/Startup Procedures
Application not previously deployed, only administration server running - application does not use commerce (no `commerce*.jar` files in the application root directory)	1. Make sure the EAR (compressed or exploded) is in the location you want on the administration server. 2. Start the administration server. 3. Open the WebLogic Server Administration Console (`http://adminserver:port/console`) and select Deployments > Applications. 4. Click Deploy a new Application, and select the archive for the application from the filesystem. Click Target Application. 5. Target the application to the administration server and the cluster. 6. Deploy the application. 7. Once deployment has completed, start the managed servers however you like, such as in parallel (simultaneously).
Application not previously deployed, only administration server running - application uses commerce (has the `commerce*.jar` files in the application root directory)	Perform the previous deployment steps except the last step. When you start the managed servers, start a single managed server first. After this managed server has started, you can start the remaining managed servers in parallel.
Administration server and cluster up and running (whether or not commerce is being used)	8. Make sure the EAR (compressed or exploded) is in the location you want on the administration server. 9. In the WebLogic Server Administration Console on the administration server (`http://adminserver:port/console`), select Deployments > Applications. 10. Click Deploy a new Application, and select the archive for the application from the filesystem. Click Target Application. 11. Target the application to the administration server only. 12. Deploy the application on the administration server. 13. Once deployment has completed, select Deployments > Applications > appName. 14. On the Targets tab, target the administration server and the cluster, and click Apply. 15. On the Deploy tab, redeploy the application.

Scenario

Deployment/Startup Procedures

Application not previously deployed, only administration server running - application does not use commerce (no commerce*.jar files in the application root directory)

1. Make sure the EAR (compressed or exploded) is in the location you want on the administration server.

2. Start the administration server.

3. Open the WebLogic Server Administration Console (http://adminserver:port/console) and select Deployments > Applications.

4. Click Deploy a new Application, and select the archive for the application from the filesystem. Click Target Application.

5. Target the application to the administration server and the cluster.

6. Deploy the application.

7. Once deployment has completed, start the managed servers however you like, such as in parallel (simultaneously).

Application not previously deployed, only administration server running - application uses commerce (has the commerce*.jar files in the application root directory)

Perform the previous deployment steps except the last step. When you start the managed servers, start a single managed server first. After this managed server has started, you can start the remaining managed servers in parallel.

Administration server and cluster up and running (whether or not commerce is being used)

8. Make sure the EAR (compressed or exploded) is in the location you want on the administration server.

9. In the WebLogic Server Administration Console on the administration server (http://adminserver:port/console), select Deployments > Applications.

10. Click Deploy a new Application, and select the archive for the application from the filesystem. Click Target Application.

11. Target the application to the administration server only.

12. Deploy the application on the administration server.

13. Once deployment has completed, select Deployments > Applications > appName.

14. On the Targets tab, target the administration server and the cluster, and click Apply.

15. On the Deploy tab, redeploy the application.

Most components must be targeted to the administration server as well as the cluster. Here are the following exceptions:

AppNameAdmin is not required on the administration server (though deploying AppNameAdmin on the administration server will not cause any problems).
AppNameDatasync is not required on the target server or cluster (though deploying AppNameDatasync to the target server or cluster will not cause any problems).

This full level of deployment on the administration server and the cluster is required, and it is the only supported configuration. There are several application design challenges specific to clustering that WebLogic Portal solves to ensure that portal applications perform properly and optimally in a cluster environment. The full targeting scheme described is part of the solution to those design challenges.

If you want to reduce the number of modules deployed on the administration server and the cluster, click Target Each Module in the deployment steps and untarget AppNameAdmin from the administration server and AppNameDatasync from the cluster.

While you need to deploy your portal application to the administration server, the administration server is not typically used to serve pages for portal applications.

Using Targeted Deployment

In the previous steps, you targeted the entire application for deployment rather than targeting individual modules to the administration server and to the cluster. This is the recommended deployment approach. Since almost all modules must be deployed to both the administration server and to the cluster, any performance or disk space benefits you want to achieve by targeting individual modules is not significant.

However, if for some reason you want to use targeted deployment, use the following recommendations, which are listed in order from easiest to most difficult.

Avoid targeted deployment. Deploy the entire application to the administration server and to the cluster.
Use Netscape or Mozilla browsers to perform targeted deployment in the WebLogic Administration Console.
Perform multiple targeted deployments. Deploy half of the modules first, then deploy the rest.
Run the weblogic.Deployer utility in Linux or UNIX environments. For information on using the weblogic.Deployer utility, see Deployment Tools Reference.
Write Java code to call the weblogic.Deployer main() and pass in the module arguments.
Use the WebLogic Server Scripting Tool (WLST). This option has not been tested on WebLogic Portal deployment. For information on WLST, see Code Library.

Starting Managed Servers

The sequence with which you start managed servers is important and depends upon your application deployment. See Table 5-1 for the startup sequences you must use.

If you are not deploying (a new application or an updated application), you can start all managed servers in parallel (simultaneously).

There are numerous ways to start a managed server and bind it to your administration server, including using Node Manager. For your initial setup, you may want to use the startManagedWebLogic script in the domain root directory. You can run this script by specifying the name of the managed server for this server instance and the URL of the administration server. Before starting the script, edit it and give the managed server more memory than it is allocated by default. This can be done by specifying a new MEM_ARGS setting. For example, change the memory allocation to -Xms512m -Xmx512m.

After starting a managed server, you can browse your portal application by going to the appropriate URL on the managed server instance. To provide your users a single point of entry to your cluster, as well as support session failover, you will need to configure a proxy server.

Configuring Your Proxy Server

For instructions on configuring a proxy plugin for WebLogic Server, see Configure Proxy Plugins.

There are no WebLogic Portal-specific configuration tasks when setting up a proxy plug-in.

Troubleshooting Unresolved URLs

If you are using a proxy server or switching back and forth between non-secure and secure ports, you may find that URLs do not resolve if you use the {url:port} or {url:securePort} variables. This is because the variables for those values are read from the request. For example, if a user in a non-secure port (port 80) clicks a secure https link that was created with a URL template that uses the {url:securePort} variable, the port number of the request (80) is used for the {url:securePort} variable, which would create a secure request (https) on an non-secure port. The same could happen if a user on a proxy server (port 80) clicks a link to a resource outside the proxy server (port 443).

In both of those cases, you need to hard code port numbers in the URL templates to get URLs to resolve correctly.

For more information using URL templates, see Creating URLs to Portal Resources at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/url.html

Deploying a Portal Application to the Cluster

This section contains instructions for redeployment, partial redeployment, and iterative deployment of datasync data, such as user profile properties, user segments, content selectors, campaigns, discounts, and other property sets.

Redeploying Applications

Use the following procedure to redeploy an application.

In the WebLogic Server Administration Console on the administration server (http://adminserver:port/console), select Deployments > Applications.

In the list of deployed applications, click the trash can icon next to the application you want to redeploy. This undeploys the current version of the application.

After undeployment (when the application name disappears from the list of applications), replace the EAR with the updated application on the filesystem.

Redeploy the application, targeting the administration server and the cluster.

Run the Propagation Utility if you have updated datasync files. For more details on what datasync files contain and how to use them, see Using the Datasync Web Application.

Redeploying a Portal Application with weblogic.Deployer

You can use the WebLogic Server Administration Console or weblogic.Deployer tool to redeploy an updated portal application to your production server. See weblogic.Deployer Utility.

The following batch file shown in Listing 5-1 is an example of how to use weblogic.Deployer to redeploy a portal application to production.

Listing 5-1 Batch File That Calls weblogic.Deployer

@echo off
echo Redeploys a Portal Web Project to a Server or Cluster
echo First Parameter is the name of the Server or Cluster
echo Second Parameter is the name of the Application
echo Third Parameter is the administrative username for the Portal Server
set SERVER=%1
set APPNAME=%2
set USERNAME=%3
echo server = %SERVER%
echo appname = %APPNAME%
echo username = %USERNAME%
java weblogic.Deployer -redeploy -username %USERNAME% -name %APPNAME% -targets %SERVER%

Partial Redeployment with weblogic.Deployer

In certain situations you can reduce the time needed to redeploy individual pieces of a portal application by using the weblogic.Deployer tool.

If your updates are contained within a particular portal web application, you can redeploy just that web application and greatly reduce the time spent in redeployment. This is of use if you have new portlets and page flows, but no new EJBs, libraries, or modules (which are Enterprise application scoped).

Because a portal web application has a number of dependencies on WebLogic Workshop control classes, those needed to be redeployed as well. The following batch file can be used to help simplify that process. You need to have weblogic.Deployer in your classpath, which can be added by running WEBLOGIC_HOME/common/bin/commEnv script.

Listing 5-2 Batch File for Redeploying WebLogic Server Control Classes

@echo off
echo Redeploys a Portal Web Project to a Server or Cluster
echo First Parameter is the name of the Server or Cluster
echo Second Parameter is the name of the Application
echo Third Parameter is the name of the Portal Web Application
echo Fourth Parameter is the administrative username for the Portal Server
set SERVER=%1
set APPNAME=%2
set WEBAPPNAME=%3
set USERNAME=%4
echo server = %SERVER%
echo appname = %APPNAME%
echo webappname = %WEBAPPNAME%
echo username = %USERNAME%
set TARGETS=%APPNAME%@%SERVER%
set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/TimerControl_-livsjc6qp6ws@
    %SERVER%
set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/p13controls_k3cw9vg6497r@
    %SERVER%
set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/MDBListener_-1x0154i4jz0he@
    %SERVER%
set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/GenericStateless@%SERVER%
set TARGETS=%TARGETS%,.workshop/%APPNAME%/EJB/ProjectBeans@%SERVER%
java weblogic.Deployer -redeploy -username %USERNAME% -name %WEBAPPNAME% -targets %TARGETS%

Deploying JSR-168 Portlets in a WAR File

WebLogic Portal provides a utility for automatically deploying JSR-168 portlets that are packaged in JSR-168 WAR files. This utility lets you import JSR-168 WAR files containing JSR-168 portlets, and expose the portlets in WSRP producers.

This section explains how to use the import utility and includes these topics:

Starting the Import Utility

To start the utility, do the following:

Start the Administration Server.

In a browser, enter the following URL:

http://servername:port/appName/jsr168/jsr168import.jsp
where servername is the IP name of Administration Server, port is the port number, and appName is the name of the portal Enterprise application that is deployed on the server. For example:
http://localhost:7001/myProjectAdmin/jsr168/jsr168import.jsp
The utility is shown in Figure 5-1. Figure 5-1 JSR-168 WAR Import Utility

Using the Import Utility

This section explains how to use the import utility to import JSR-168 WAR files into an enterprise application.

Use the Browse buttons to select the following files:

portal-application.zip, portal-project.zip, and netui-webapp.zip - By default, these template files are located in the BEA_HOME/workshop/templates directory. Note that these filenames are defaults. It is possible that custom versions of these files have been updated at your site. Typically, you will select the most recently modified versions of these files.
JSR168 compliant .wars - Select a WAR file containing the JSR168 compliant portlets that you want to deploy. You can select multiple WAR files.

Enter a name for the new portal application. The utility creates this application (an EAR file). The EAR file is built using the selected templates in the same manner that WebLogic Workshop builds an application. Each JSR-168 WAR file becomes a web application that is packaged in the EAR. Use a unique name for the application. (Do not use a name that matches any existing applications deployed to the server.)

If you select the Auto-deploy to running server checkbox, the new portal application is automatically deployed. Typically, this option is only used for simple development or test deployments. If you want to upload the new application to a more complex environment, such as a staging or production environment, it is recommended that you do not select this checkbox. Instead, use the WebLogic Server Console to deploy the EAR.

Click Perform Import to create the new application. If Auto-deploy to running server is selected, the newly created EAR file is deployed automatically. If you did not select the checkbox, you need to deploy the EAR using the WebLogic Server Console. You can find the new EAR file in the domain root directory.

Accessing the Portlets

After the new EAR file is deployed, you can add the portlets contained in the imported WAR file(s) to your application. To do this, you need to add the web application(s) as WSRP producers. After a web application is added as a producer, you can incorporate the application's portlets as you would with any WSRP producer using the WebLogic Administration Portal. See the Administration Portal online help topic Add a Remote Producer for detailed information.