Production Operations Guide

Deploying Portal Applications

The term application deployment refers to the process of making an application or module available for processing client requests in a WebLogic Server domain. This chapter discusses recommended procedures and best practices for deploying WebLogic Portal applications and shared libraries to the server.

This chapter includes the following topics:

Preparing to Deploy

Before you deploy a WebLogic Portal application, you need to configure the destination domain. For detailed information on domain configuration, see Creating Your Clustered Domain.

Overview of Deployment Descriptors and Config Files

In WebLogic Portal 8.1 and prior versions, an application configuration file named META-INF/application-config.xml was used to configure WebLogic Portal components such as cache, campaigns, behavior tracking, content management, and others.

As of WebLogic Portal 9.2, this configuration file has been removed and its contents moved to a collection of new, schema-compliant, descriptors. These new descriptors are each focused on a single service or group of related services. To view the complete set of descriptor files used by an application in WorkSpace Studio, select the Merged Projects view.

These files are processed using the same infrastructure that WebLogic Server uses to process all the J2EE descriptors (like application.xml or web.xml). These descriptors support merging from J2EE Shared Libraries and also support deployment plans. (For more information on merging, see Descriptor Merging.) The WebLogic Portal descriptors are installed with default settings that you can override by copying them into your application and editing them. A significant benefit of this configuration is that the contents of your project’s EAR file is focused on your project, and not on the WebLogic Portal product code.

This section includes these topics:

Descriptor Merging

When the server processes the deployment descriptors, it merges them. All descriptors from the application and from the shared libraries that the application references are merged. For each separate deployment descriptor, a merged “virtual” descriptor is created, which can be used by the server to deploy the application. The rules that govern descriptor merging are explained in Shared Library Rules of Precedence. Remember that the referencing application and its deployment plan always override settings imported from a referenced library.

Viewing Merged Descriptors

If you want to see merge results without deploying an application, you can use the WebLogic Server utility called weblogic.appmerge. This utility takes an application that references shared libraries and creates a J2EE application including the merged contents and merged descriptors. This utility is useful for debugging purposes. For details, see the WebLogic Server document, “Using weblogic.appmerge to Merge Libraries.”

WorkSpace Studio provides information about shared libraries (also called library modules). You can use WorkSpace Studio to copy files from shared libraries to your application. When you do this, you can then modify the copied file. From then on, the local copy takes precedence over the library module copy. Using the Package Explorer view, you can view and browse the contents of shared libraries.

Another utility, called ddbrowser, is included with the WebLogic Portal installation. This utility inspects your application and shows you all the “mergeable” descriptors. For each descriptor in the application, you can see the contributions from each library as well as the resulting merged descriptor.

To use ddbrowser, set the WL_HOME environment variable to point to the WebLogic Home directory of your installation. Then run the following command:

java -jar $WL_HOME/common/p13n/lib/ddbrowser.jar.

Portal Web Application Deployment Descriptors

A Portal Web Application includes several deployment descriptors. By default, these descriptors are located in the WebContent/WEB-INF directory of the web project. The deployment descriptors are listed in Table 4-1.

Enterprise Application Deployment Descriptors

The J2EE specifications define standard, portable deployment descriptors for J2EE modules and applications. BEA defines additional WebLogic-specific deployment descriptors for deploying a module or application in the WebLogic Server environment. A WebLogic Portal enterprise application, also called an EAR Project, includes the deployment descriptors listed in Table 4-2. By default, these files are located in the EarContent/META-INF directory of the EAR project.

Configuration Files

Table 4-3 lists Web application configuration files. These files are not descriptor files (they cannot be used in deployment plans and they are not merged).

Using Deployment Plans

Deployment plans let you easily tune an application’s deployment descriptors on a deployment-by-deployment basis without actually modifying the descriptors themselves in the application EAR file. For instance, you might use a deployment plan to adjust descriptors for a staging environment and another plan to make adjustments for your production environment. Typically, developers set initial baseline descriptor values.

A deployment descriptor is an XML document used to define the J2EE behavior or WebLogic Server configuration of an application or module at deployment time. A deployment plan is an XML document that resides outside of an application's archive file, and can apply changes to deployment properties stored in the application's existing WebLogic Server deployment descriptors.

For detailed information on deployment plans, see the WebLogic Server document “Configuring Applications for Production Deployment.” This document describes deployment plans in detail, discusses the XML schema for deployment plans, and explains how to create, edit, and use them.

Using Application-Scoped JDBC

With application-scoped JDBC, it is possible to use more than one database in a WebLogic Portal domain, allowing each application deployed in the domain to access its own database. WebLogic Server enables this by providing the ability for you to scope JDBC pools to the application level.

When you package your enterprise application, you can include JDBC resources in the application by packaging JDBC modules in the EAR and adding references to the JDBC modules in all applicable descriptor files. When you deploy the application, the JDBC resources are deployed, too. Depending on how you configure the JDBC modules, the JDBC data sources deployed with the application will either be restricted for use only by the containing application (application-scoped modules) or will be available to all applications and clients (globally-scoped modules).

By default, JDBC pools are scoped to the domain level. If you want to scope JDBC pools to the application level, some configuration is required. For detailed information on configuring application-scoped JDBC, see the WebLogic Server document “Configuring JDBC Application Modules for Deployment.”

Building a Portal Application

This section explains how to build a portal application and create an EAR file using WorkSpace Studio or from the command line. This section discusses creating both EAR files and exploded EARs.

Building in WorkSpace Studio

To deploy a portal application to a production environment, you must first build the application in WorkSpace Studio to compile necessary classes in the portal application and create a deployable EAR file. The EAR can either be compressed (an EAR file) or uncompressed (an exploded EAR directory).

For detailed information on building an application in WorkSpace Studio, see the WorkSpace Studio document “Understanding the Build Process.”

To create an exploded EAR directory, first build an EAR file, and then use the Java jar xf command to uncompress the file.

Building from the Command Line

You can export an Ant build file for your project using WorkSpace Studio. For more information, see the WorkSpace Studio document “Creating Custom Ant Build Files for an Application.”

Deploying the EAR

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

This section includes the following topics:

Deploying to a Development Environment

In a typical development environment, developers use WorkSpace Studio to develop portal components. They typically deploy and run against a local server domain that is configured in Development mode. No Managed Servers are used. The best practice is to use WorkSpace Studio to deploy (publish) and test your application.

Deploying to a Staging or Production Environment

In a domain with an Administration Server and one Managed Server or multiple Managed Servers in a cluster, it is strongly recommended that you deploy the portal EAR file to the Managed Server or cluster. Do not deploy to the Administration Server; this reserves the Administration Server for administration functions, allows the Administration Server to operate with a smaller heap, and allows specific fire-walling of administration functions on this server.

The best practice is to configure your staging and production servers in Production mode rather than Development mode.

The WebLogic Server feature that allows applications to be deployed directly to a Managed Server is called Managed Server Independent (MSI) mode. See “Understanding Managed Server Independent Mode” in the WebLogic Server documentation for information on MSI and several limitations of MSI. One of the most important limitations is that security provider data cannot be modified if the Administration Server is down. Another limitation is that any WebLogic Portal configuration that must write to a deployment plan for persistence will not work if the Administration Server is down.

Redeploying to a Staging or Production Environment

Redeploying means deploying a new version of an existing/running/deployed application. If you redeploy a portal application to a staging or production environment, follow the same procedure as deploying described in the previous section. However, on redeployment, you must propagate datasync and other WebLogic Portal assets to the target database as a separate operation using the propagation tools. See General Propagation Scenarios for more information on redeploying.

Deploying an Exploded EAR

If you deploy an exploded EAR file to a managed server, extra configuration is required. You must place a new datasync.properies file in the end user’s application under the META-INF directory. In this datasync.properties file, add the following property:

PERSISTENT_STORE=DATABASE_STORE

This change is only required if you deploy an exploded EAR file.

Deploying J2EE Shared Libraries

WebLogic Portal product code is included in your application by referencing several J2EE Shared Libraries. These libraries are part of the WebLogic Portal installation. You can also develop your own shared libraries containing your application code. J2EE Shared Libraries allow you to decouple the development life cycles of various portions of your application. These libraries can be versioned and deployed independently, allowing each library to be developed and distributed independently (rather than as a single large EAR file).

This section discusses several aspects of shared libraries:

Library Descriptors

Listing 4-1 shows a sample enterprise application, myApp.ear. Note that the descriptor weblogic-application.xml includes a reference (shown in bold) to a library called p13n-app-lib. Note, too, that no other information, other than the name p13n-app-lib, is given to describe the library.

The enterprise application locates the library because the <library-ref> element causes the server at runtime to look for a deployed library with the same name. Since the <library-ref> element does not specify any version information, the server looks for the latest, or highest, version number available to it. The name and version number of a shared library is contained in the library itself, in the META-INF/MANIFEST.MF file. For example:

META-INF/MANIFEST.MF
    Extension-Name: p13n-app-lib
    Specification-Version: 10.0.0
    Implementation-Version: 10.0.0

For more information, see Library Versions. Note that the same pattern applies to the WEB-INF/weblogic.xml file for portal web applications.

To be located by the server, a shared library must be deployed as a library. This deployment differs from the deployment of a runnable application. When a library is deployed as a library, the library file is registered with the server, and is therefore available to referencing applications.

To deploy a library, use the WebLogic Server Console, the weblogic.Deployer command, the wldeploy Ant task, or with a WLST script. For information these methods, see the WebLogic Server documents “ The WebLogic Server Administration Console,” “ weblogic.Deployer Command Line Reference,” “ wldeploy Ant Task Reference,” and “ WLST Command and Variable Reference.”

For example, you can use the WebLogic Server Console to deploy a shared library in exactly the same way you deploy an application, except that a checkbox is available that distinguishes the shared library from a runnable application.

Listing 4-2 shows an entry in the server domain’s config/config.xml file for the shared library referenced by the application in Listing 4-1.

<library>
  <name>p13n-app-lib#10.0.0@10.0.0</name>
  <target>myServer</target>
  <module-type>ear</module-type>
  <source-path>/bea/weblogic100/deployable-libraries/p13n-app-lib.ear
  </source-path>
  <security-dd-model>DDOnly</security-dd-model>
</library>

Library Versions

You can deploy several libraries with the same name and different version numbers. The version number that an application uses is specified in the application’s configuration file META-INF/weblogic-application.xml or weblogic.xml for Web applications. If no version number is specified, as in Listing 4-3, the server selects the highest-versioned available deployed library named p13n-app-lib.

<library-ref>
  <library-name>p13n-app-lib</library-name>
</library-ref>

If, on the other hand, you know that version 10.0.0 of p13n-app-lib is inadequate, and your application needs to use version 10.0.1 or higher, you can reference the library as shown in Listing 4-4.

<library-ref>
  <library-name>p13n-app-lib</library-name>
  <specification-version>10.0.1</specification-version>
</library-ref>

If you want to use a specific version, and no other version, then you can specify the <exact-match> element, as shown in Listing 4-5.

<library-ref>
  <library-name>p13n-app-lib</library-name>
  <specification-version>10.0.0</specification-version>
  <exact-match>true</exact-match>
</library-ref>

Creating Content Repositories

If you are using a content repository, you need to create that repository or repositories on the destination server. To do this, use the WebLogic Portal Administration Console as explained in the Content Management Guide. This means creating only the root repositories, not the content items and types. To move items and types between environments, use the WebLogic Portal propagation tools. For more information on propagation tools, see Developing a Propagation Strategy.

You can also specify the default content repository for an enterprise application in the configuration file META-INF/content-config.xml. See Enterprise Application Deployment Descriptors for more information.

Using Multiple Enterprise Applications in a Single Domain

You can create and run multiple enterprise applications in a single-cluster domain. As shown in Figure 4-1, a single domain can host multiple enterprise applications (EARs). Each EAR deployment can host multiple web applications, and any number of desktops can be created based on the web applications. The web applications and desktops associated with one enterprise application (EAR) are not dependent on those in another enterprise application (they are decoupled).

The following restrictions apply to this configuration of multiple enterprise applications in a single domain:

Application Tuning Tips

The best practice is to use deployment plans to modify descriptor values before deploying an application. See Using Deployment Plans. See also the WebLogic Server document “WebLogic Server Performance and Tuning.”

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:

Using the Import Utility

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

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 Portal Administration Console. See the Federated Portals Guide for details.

Using Production Redeployment with WebLogic Portal

This section discusses using the production redeployment technique to redeploy a WebLogic Portal application to a production environment.

This section includes these topics:

What is Production Redeployment?

Production redeployment enables a portal administrator to redeploy a new version of an application in a production environment without stopping the deployed application or otherwise interrupting the application’s availability to clients. Production redeployment works by deploying a new version of an updated application alongside an older version of the same application. WebLogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the application during the redeployment continue to use the older, retiring version of the application until they complete their work.

Production redeployment support in WebLogic Portal is based on support from WebLogic Server. Before continuing, we recommend that you review the following WebLogic Server documentation:

Conceptual Overview and Limitations

Figure 4-2 depicts a typical production redeployment scenario for a WebLogic Portal application. As the diagram shows, a new portal version, App V2, has been deployed side-by-side with the original App V1. During production redeployment, existing users continue to interact with App V1 while new users interact with App V2. When all user sessions connected to App V1 end or time out, App V1 is undeployed.

The key to understanding how production redeployment works for a portal application is to note that during production redeployment, both the old and new application share the same database, security repository, and content repository.

Because both applications share the same back-end systems, side effects can occur during production redeployment. To illustrate this, consider the following scenario. Developers have added a new portlet to the App V2 portal’s home page. When the new portal is deployed, that portlet and the updated page definition containing the new portlet are placed in the production database. Now, because both the old and new applications share the same database, App V1 may attempt to display the new portlet. Unfortunately, any supporting file-based code that underlies the portlet will not exist in the App V1 deployment, resulting in an error.

This simple example scenario illustrates that side effects during production redeployment typically occur because the shared database contains application-specific references. Potentially, differences that exist between the underlying deployments of the “side-by-side” applications can result in errors. Keep in mind that all external touch points to your application, such as application resources that are referenced in the database, must be consistent between the two applications. For example, the class name of a portlet backing file is stored in the database along with the portlet’s definition. If you rename or remove a backing file, existing users accessing the original application may encounter errors. Similarly, if you add a new page to your portal that contains new portlets, during production redeployment the page and portlet definitions will be added to the database and could inadvertently show up in the original application. In this case users of the original application could experience errors.

These scenarios illustrate possible side effects that can occur during production redeployment of a WebLogic Portal application. Later sections discuss additional, possible side effects as well as recommended use cases for production redeployment.

Overview of Basic Steps

Figure 4-3 illustrates the basic steps for production redeployment with a WebLogic Portal installation.

The following sections discuss possible scenarios for production redeployment and the known limitations of each.

Application Redeployment Scenarios

This section describes several scenarios in which application redeployment can be used with WebLogic Portal.

This section discusses the following redeployment scenarios:

Adding, Removing, or Updating a Non-Portal Asset

Adding, removing, or updating a non-portal asset refers to a adding or removing an asset that does not require any change to the database. In this scenario, production redeployment is a safe and recommended technique for achieving zero-downtime redeployment.

Examples:

Adding, Removing, or Updating Portal Assets with Database Changes

In this scenario, assets that require database changes are added to or removed from the new version of the portal. If you change the structure of a portal, such as by adding a new page to an existing book, upon deployment, the changes are automatically pulled into the database.

In this scenario, WebLogic Portal does not fully support production redeployment. This is because application database rollback is not supported. WebLogic Portal cannot revert the changes in the database once they have been applied.

Examples:

Deploying and Propagating

In this scenario, the newly deployed application requires portal assets to be propagated. Because propagation alters the portal database, application rollback is not supported in this case. For an introduction to propagation, see Developing a Propagation Strategy.

Production Redeployment Issues and Limitations

This section discusses several issues and limitations related to production redeployment of a WebLogic Portal application. Please review this section before attempting to use application redeployment with a WebLogic Portal application.

This section includes these topics:

Application Rollback

Reversing or “rolling back” the production redeployment process switches the state of the active and retiring applications and redirects new client connection requests accordingly. Reverting the production redeployment process might be necessary if you detect a problem with a newly-deployed version of an application, and you want to stop clients from accessing it. Application rollback is described in the WebLogic Server document “Rolling Back the Production Redeployment Process.”

Generally, anytime your production redeployment changes WebLogic Portal database entries, application rollback is not supported for WebLogic Portal production redeployment. Again, because the old and new applications share the same database, if the database changes during redeployment, those changes cannot be rolled back, leading to possible side effects for users of the original application.

For more information and examples of scenarios where database changes occur, see Application Redeployment Scenarios.

Memory and CPU Requirements

Because the production redeployment feature executes two full version of the WebLogic Portal application at the same time, you need to consider memory and CPU requirements. While it is impossible to specify the exact amount of memory and CPU that will be required for production redeployment, a good rule of thumb is to double the current running load on the server. For example if the application is taking one gigabyte of memory and using 40% of the current CPU then it should be assumed that the second version will also require the same about of memory and CPU. For this reason, you may want to consider scheduling your production redeployments when there is less user activity and load on the WebLogic Portal server instances.

Propagation

The WebLogic Portal propagation tools do not support database rollback. For this reason if a deployment scenario requires propagation to be used, roll back of the application cannot be performed.

See Rolling Back an Import Process for more information.

Database Instances

It is recommended that you use the same data store between versions of a WebLogic Portal application.

Database Changes

WebLogic Portal does not support changes to the database schema when using production redeployment.

Cache Invalidations

The WebLogic Portal cache framework only invalidates cache entries for the current application. Any applications that are running during production redeployment will not see cache invalidations. Because of this, it is possible to see stale cache entries between different version of the application.

Content Repositories

File-based content repositories are not supported for production redeployment.

Applications that Use Expression-Based Roles

Production redeployment is not supported for any application that uses expression-based role policies. For information on defining roles using expressions, see the WebLogic Portal Security Guide.

External Systems

External systems that depend on a WebLogic Portal application can be affected when using production redeployment. Because production redeployment only uses HTTP session management to manage which version of an application a user is connected to, the following non-HTTP frameworks always reference the newer version of the application:

Side Effects of Production Redeployment

This section lists known side-effects of using production redeployment with a WebLogic Portal application. This section includes these topics:

Customizations

Customization to desktops are not immediately viewable in new or old versions of a portal application. For example, if an administrator alters users’ desktops in the new version of an application, the change may not be immediately viewable. Because customizations are cached for users of the old version of the application, users will not see the new customization until the cache times out.

Portal Resources

When the new version of the application is deployed, WebLogic Portal alters the portal database. For example, when a new portlet is added that does not exist in the old application, the database is updated for the new application. Because of this, users currently using the older version of the application may see the portlet but not have the ability to render it because the file system assets do not exist in the older version.

Entitlements

Entitlements have both LDAP and RDBMS artifacts, meaning they will be shared between versioned applications which use the same database. One side effect of this is that a WebLogic Portal Administration Console administrator in the older application could affect entitlements in the versioned application (and vice versa).

WSRP

A WSRP consumer maintains a session state with a producer on behalf of a user. Therefore, any external application consuming a WSRP portlet will transition to the new application version after the session times out.

System Classpath Changes

Any changes to system classpaths will require the server to be restarted.