Deploying Applications and Modules with weblogic.Deployer

Overview of Common Deployment Scenarios

Learn these common deployment tasks which are organized into several general categories, starting with the most basic tasks and progressing to more advanced tasks.

Before you deploy an application, perform the appropriate tasks described in Configuring Applications for Production Deployment.

Uploading Deployment Files from a Remote Client—Explains how to upload an application or module to the Administration Server from a remote client.
Deploying to a Single-Server Domain—Explains the basics of deploying an application or module to a single-server WebLogic domain.
Deploying an Application with a Deployment Plan—Explains how to deploy an application with a deployment plan that fully configures the application.
Deploying an Application That Looks Up System Resources from JNDI During preStart—Explains how to deploy an application that looks up system resources via JNDI.
Targeting Deployments to Servers, Clusters, and Virtual Hosts—Describes all WebLogic Server target types, and explains how to identify targets during deployment.
Using Module-Level Targeting for Deploying an Enterprise Application—Describes how to target individual modules in an enterprise application to different WebLogic Server targets.
Deploying JDBC, JMS, and WLDF Application Modules—Describes how to deploy both standalone and application-scoped JDBC, JMS, and WLDF modules in a WebLogic Server domain.
Controlling Deployment File Copying with Staging Modes—Describes how to use non-default staging modes to control WebLogic Server file-copying behavior.
Distributing Applications to a Production Environment—Describes how to deploy and test a new application directly in a production environment without making the application available for processing client requests.
Deploying Shared Java EE Libraries and Dependent Applications—Describes how to deploy Java EE Libraries and optional packages to a WebLogic Server environment, and how to deploy and manage applications and modules that reference these shared resources.
Best Practices for Deploying Applications—Summarizes key deployment practices.

Uploading Deployment Files from a Remote Client

In order to deploy an application or module to a domain, the deployment file(s) must be accessible to the domain's Administration Server. If the files do not reside on the Administration Server machine or are not available to the Administration Server machine via a network mounted directory, use the -upload option to upload the files before deploying them.

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -deploy -upload c:\localfiles\myapp.ear

To upload an exploded archive directory, specify the directory name instead of an archive filename (for example c:\localfiles\myappEar).

When you upload files to the Administration Server machine, the archive file is automatically placed in the server's upload directory. You can configure the path of this directory using the instructions in Changing the Default Staging Behavior for a Server.

Upload Behavior When Updating an Application or Plan

When mixing local and remote (upload) deployment operations, it is very important to use a process that tracks how an application is deployed. Consider the following series of events:

An administrator or developer deploys an app (myapp.ear) with a deployment plan (productionEnvPlan.xml) to an Administration Server having a Managed Server using:

   java weblogic.Deployer -adminurl http://test:7001 -username weblogic
      -password weblogic -deploy c:\localfiles\myapp.ear
      -plan c:\localfiles\productionEnvPlan.xml

If the administrator or developer uses WebLogic Portal on the Managed Server and saves some configuration changes to the myapp.ear application. When the application is saved, WebLogic Portal updates the application using the following:
```
   java weblogic.Deployer -adminurl http://test:7001 -username weblogic
      -password weblogic -update -name myapp.ear -upload 
      -plan c:\localfiles\nuPlan.xml
```
The application and deployment plan file from the remote machine are uploaded to the Administration Server upload directory. The deployment is updated and the configuration uses the deployment plan at c:\domain\servers\adminServerName\upload\plan\nuPlan.xml.

At this point, an administrator or developer expecting the behavior derived from the application (c:\localfiles\myapp.ear) and deployment plan (c:\localfiles\productionEnvPlan.xml) can easily become confused. If the administrator or developer:

Reviews the application and deployment plan files, the files have not changed. New behaviors appear to be unexplained.
Makes changes to the c:\localfiles\myapp.ear application file or c:\localfiles\productionEnvPlan.xml deployment plan file xml, the deployment configuration changes in the upload directory are at risk of being lost.

Deploying to a Single-Server Domain

A single-server WebLogic Server domain, consisting only of an Administration Server, represents the simplest scenario in which to deploy an application or module. If you are deploying files that reside on the same machine as the domain, use the -deploy command and identify the file location, with connection arguments for the Administration Server.

For example:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -deploy c:\localfiles\myapp.ear

In the above command, WebLogic Server creates a default deployment name of myapp, as described in Understanding Default Deployment Names, because myapp is the name of the deployment file without the extension. If you want to specify a non-default deployment name, use the -name option, as in:

java weblogic.Deployer -adminurl http://localhost:7001 
   -username weblogic -password weblogic -deploy 
   -name myTestApplication c:\localfiles\myapp.ear

To deploy an application or module to multiple targets, see Targeting Deployments to Servers, Clusters, and Virtual Hosts.

Deploying an Application with a Deployment Plan

When you use weblogic.Deployer to deploy an application, the deployment plan and WebLogic Server deployment descriptors must define a valid configuration for the target environment, or the deployment fails. This means you cannot use weblogic.Deployer with a deployment plan that defines null variables for an application's required resource bindings.

To deploy an application and deployment plan using weblogic.Deployer, include the -plan option with the -deploy command, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
     -password weblogic -deploy -name myTestDeployment 
     -source /myDeployments/myApplication.ear
     -targets myCluster -stage 
     -plan /myDeployments/myAppPlan.xml

If you are deploying from an application root directory and the deployment plan is located in the /plan subdirectory, you still need to identify both the actual deployment source files the plan to use for deployment, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
     -password weblogic -deploy -name myTestDeployment 
     -source /myDeployments/installedApps/myApplication/app/myApplication.ear
     -targets myCluster -stage
     -plan /myDeployments/installedApps/myApplication/plan/plan.xml

When you deploy or distribute an application with a deployment plan, the deployment plan and any generated deployment descriptors are copied to the staging directories of target servers along with the application source files.

You can also stage deployment plans independently of the application archive. See Staging Deployment Plans.

Deploying an Application That Looks Up System Resources from JNDI During preStart

Because preStart application life cycle listeners are invoked during the prepare phase of an application—which occurs when an edit session is activated—JNDI lookup of system resources fails if you create a new system resource during the same edit session in which you deploy an application that uses the system resource.

For example, if you acquire an edit lock from the WebLogic Server Administration Console, then create a new JDBC system resource and deploy an application that uses the new JDBC system resource during the same edit session (in other words, before activating changes in the WebLogic Server Administration Console), JNDI lookup of the JDBC system resource will fail because the preStart application life cycle listeners were invoked before the system resource was activated. To look up system resources from JNDI in your preStart life cycle listeners, Oracle recommends that you create the system resource during startup or during a separate edit session, before you deploy any applications that use the system resource. For example:

Acquire an edit lock by clicking Lock & Edit in the WebLogic Server Administration Console.
Create the desired system resource. See Create JMS system modules in Oracle WebLogic Server Administration Console Online Help.
Complete the edit session by clicking Activate Changes in the WebLogic Server Administration Console.
Acquire another edit lock by clicking Lock & Edit in the WebLogic Server Administration Console.
Deploy the application that uses the system resource you created in step 2. For information on deploying applications from the WebLogic Server Administration Console, see Deploy applications and modules in Oracle WebLogic Server Administration Console Online Help.

See Overview of Java EE Libraries and Optional Packages in Developing Applications for Oracle WebLogic Server for more information.

Targeting Deployments to Servers, Clusters, and Virtual Hosts

In most production environments, you typically deploy applications to one or more Managed Servers configured in a WebLogic Server domain.

In some cases, the servers may be included as part of a WebLogic Server cluster, or a virtual host may be used for directing Web application requests. The term deployment target refers to any server or collection of servers to which you can deploy an application or module.

Understanding Deployment Targets

Deployment targets are the servers or groups of servers to which you deploy an application or standalone module. During the deployment process, you select the list of targets from the available targets configured in your domain. You can also change the target list after you have deployed a module.

The following table describes all valid deployment targets for WebLogic Server, and lists the types of modules that you can deploy to each target.

Table 6-1 WebLogic Server Deployment Targets

Target Type	Description	Valid Deployments
WebLogic Server Instance	A WebLogic Server instance, such as an Administration Server in a single-server domain, or a Managed Server.	Java EE applications Java EE modules JMS, JDBC, or WLDF modules Java EE libraries
Cluster	A configured cluster of multiple WebLogic Server instances	Java EE applications Java EE modules JMS, JDBC, or WLDF modules Java EE libraries
Virtual Host	A configured host name that routes requests for a particular DNS name to a WebLogic Server instance or cluster. See Configuring Virtual Hosting in Administering Server Environments for Oracle WebLogic Server for more information.	Web applications
JMS Server	A JMS Server configured in a WebLogic Server domain	A JMS queue or topic defined within a JMS module* *When deployed as a standalone application module, a JMS, JDBC, or WLDF resource appears as a Java EE deployment in the WebLogic Server Administration Console. A standalone JMS application module can be targeted to server, cluster, or virtual host targets; queues and topics defined within a JMS module can be further targeted to a configured JMS server. For information on sub-module targeting, see Using Sub-Module Targeting with JMS Application Modules.

Deploying to One or More Targets

To deploy to a single WebLogic Server target, list the configured target name after the -targets option to weblogic.Deployer. For example, to deploy a Web application to a configured virtual host named companyHost, use the command:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -deploy -targets companyHost c:\localfiles\myWebApp.ear

Specify multiple targets using a comma-separated list, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -deploy -targets ManagedServer-1,ManagedServer-2 
   c:\localfiles\myapp.ear

Deploying to a Cluster Target

If you specify a cluster target (using -targets mycluster), WebLogic Server targets all server instances in the cluster by default. This corresponds to homogenous module deployment, which is recommended in most clusters. If you want to deploy a module only to a single server in the cluster (that is, "pin" a module to a server), specify the individual server instance name, rather than the cluster, as the target. This type of deployment is less common, and should be used only in special circumstances where pinned services are required. See Understanding Cluster Configuration and Application Deployment in Administering Clusters for Oracle WebLogic Server for more information.

Note:

Pinning a deployment to a subset of server instances in a cluster (rather than to a single server on the cluster) is not recommended and will generate a warning message.

When you deploy an application to a cluster target, WebLogic Server ensures that the deployment successfully deploys on all available members of the cluster. If even a single, available WebLogic Server instance in the cluster cannot deploy the application, the entire deployment fails and no servers in the cluster start the application. This helps to maintain homogeneous deployments to the cluster, because deployment operations succeed or fail as a logical unit.

If a clustered server is unreachable at the time of deployment (for example, because of a network failure between the Administration Server and a Managed Server, or because a cluster member is shut down) that server does not receive the deployment request until the network connection is restored. This default behavior ensures that most deployment operations succeed, even when servers are taken offline.

Enforcing Consistent Deployment to All Configured Cluster Members

The default cluster deployment behavior ensures homogeneous deployment for all clustered server instances that can be reached at the time of deployment. However, if the Administration Server cannot reach one or more clustered servers due to a network outage, those servers do not receive the deployment request until the network connection is restored. For redeployment operations, this can lead to a situation where unreachable servers use an older version of the deployed application, while reachable servers use the newer version. When the network connection is restored, previously-disconnected servers may abruptly update the application as they receive the delayed redeployment request.

It is possible to change WebLogic Server's default deployment behavior for clusters by setting the ClusterConstraintsEnabled option when starting the WebLogic Server domain. The ClusterConstraintsEnabled option enforces strict deployment for all servers configured in a cluster. A deployment to a cluster succeeds only if all members of the cluster are reachable and all can deploy the specified files.

Note:

Do not use the ClusterConstraintsEnabled option unless you have an extremely reliable network configuration, and you can guarantee that all cluster members are always available to receive deployment and redeployment requests. With ClusterConstraintsEnabled, WebLogic Server will fail all deployment operations to a cluster if any clustered server is unavailable, even if a single server has been shut down for maintenance.

To set the ClusterConstraintsEnabled for the domain when you start the Administration Server, include the appropriate startup argument:

-DClusterConstraintsEnabled=true enforces strict cluster deployment for servers in a domain.
-DClusterConstraintsEnabled=false ensures that all available cluster members deploy the application or module. Unavailable servers do not prevent successful deployment to the available clustered instances. This corresponds to the default WebLogic Server deployment behavior.

Using Module-Level Targeting for Deploying an Enterprise Application

An enterprise application (EAR file) differs from other deployment units because an EAR can contain other module types (WAR and JAR archives). When you deploy an enterprise application using the WebLogic Server Administration Console, you can target all of the archive's modules together as a single deployment unit, or target individual modules to different servers, clusters, or virtual hosts.

You can also use module-level targeting to deploy only a subset of the modules available in an EAR. This can simplify packaging and distribution of applications by packaging multiple modules in a single, distributable EAR, but targeting only the modules you need to each domain.

Module-Targeting Syntax

To target individual modules in an enterprise application, use the module_name@target_name syntax. For example:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name myEnterpriseApp
   -targets module1@myserver1,module2@myserver2,module3@myserver3 
   -stage -deploy c:\localfiles\myEnterpriseApp.ear

Targeting Web Application Modules

To target Web application modules that are part of an .ear file, you can use the Web application's context-root name as the module name or specify the web-uri.

For example, if the application.xml file for a file, myEnterpriseApp.ear, defines:

<module>
  <web>
    <web-uri>myweb.war</web-uri>
    <context-root>/welcome</context-root>
  </web>
</module>

You can deploy only the Web application module by using the context-root name:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name mywebapplication -targets /welcome@myserver1
   -stage -deploy c:\localfiles\myEnterpriseApp.ear

You can deploy only the Web application module by using the web-uri:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name mywebapplication -targets myweb.war@myserver1
   -stage -deploy c:\localfiles\myEnterpriseApp.ear

To deploy a Web application as a default Web application, set the value of the context-root element to "/". For example, if the application.xml file for a file, myEnterpriseApp.ear, defines:

<module>
  <web>
    <web-uri>myweb.war</web-uri>
    <context-root>/</context-root>
  </web>
</module>

You can deploy only the Web application module by using the context-root name:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name mywebapplication -targets /@myserver1
   -stage -deploy c:\localfiles\myEnterpriseApp.ear

Starting and Stopping Modules

You can start or stop individual child modules, as follows:

java weblogic.Deployer -username weblogic -password weblogic -adminurl 
t3://localhost:7001 -name appName -start -targets moduls1@myserver1

java weblogic.Deployer -username weblogic -password weblogic -adminurl 
t3://localhost:7001 -name appName -stop -targets moduls1@myserver1

Note:

Use caution starting and stopping modules in production when modules have dependencies.

Deploying JDBC, JMS, and WLDF Application Modules

Standalone JDBC, JMS, and WLDF application modules can be deployed similar to standalone Java EE modules. For a standalone JDBC, JMS, or WLDF application module, the target list determines the WebLogic Server domain in which the module is available.

JNDI names specified within an application module are bound as global names and available to clients. For example, if you deploy a standalone JDBC application module to a single-server target, then applications that require resources defined in the JDBC module can only be deployed to the same server instance. You can target application modules to multiple servers, or to WebLogic Server clusters to make the resources available on additional servers.

If you require JDBC, JMS, or WLDF resources to be available to all servers in a domain, create system modules, rather than deployable application modules. See Configuring JMS System Resources in Administering JMS Resources for Oracle WebLogic Server, Configuring WebLogic JDBC Resources in Administering JDBC Data Sources for Oracle WebLogic Server, and Configuring Diagnostic System Modules in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Note:

Deploying a JMS module does not necessarily mean it is properly targeted and active, and that the JNDI name is available. The JNDI name is not available until the JMS module is properly targeted. See Understanding JMS Resource Configuration in Administering JMS Resources for Oracle WebLogic Server.

Targeting Application-Scoped JMS, JDBC, and WLDF Modules

JMS, JDBC, and WLDF application modules can also be included as part of an enterprise application, as an application-scoped resource module. Application-scoped resource modules can be targeted independently of other EAR modules during deployment, if necessary, by using module-level targeting syntax. For example:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name myEnterpriseApp
   -targets myWebApp@myCluster,myJDBCModule@myserver1,myEJBModule@myserver1 
   -stage -deploy c:\localfiles\myEnterpriseApp.ear

Using Sub-Module Targeting with JMS Application Modules

Certain JMS resources defined within a JMS application module can be further targeted to a JMS Server available on the module's target during deployment. These resources are known as submodules. Certain types of submodule require deployment to a JMS Server, such as:

Queues
Topics

Other submodules can be targeted to JMS Servers as well as WebLogic Server instances and clusters:

Connection factories
Foreign servers
SAF imported destinations
Uniform distributed topics
Uniform distributed queues

To specify submodule targets at deployment or undeployment time, you must use an extended form of the module targeting syntax with the -submoduletargets option to weblogic.Deployer.

Default Submodule Targeting

When deploying from the WebLogic Server Administration Console, WebLogic Server selects default JMS Server targets for submodules in a JMS application module, as described in Targeting JMS Modules and Subdeployment Resources in Administering JMS Resources for Oracle WebLogic Server.

When deploying submodule using WLST, you can use the parent module's targets as default targets for JMS resources when all the following conditions are met:

The application contains one or more JMS mdoules.
There is exactly one JMS server instance associated with the module target.
The -submoduletargets option is not specified
The defaultSubmoduleTargets option is true.

See Deployment Commands in WebLogic Scripting Tool.

Sub-module Targeting for Standalone JMS Modules

For a standalone JMS module, the submodule targeting syntax is: -submoduletargets submodule_name@target_name. For example, to deploy a standalone JMS module on a single server instance, targeting the submodule myQueue to a JMS Server named JMSServer1, enter the command:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name myJMSModule
   -targets ManagedServer1 -submoduletargets myQueue@JMSServer1
   -deploy c:\localfiles\myJMSModule.xml

To undeploy the same JMS module, enter the following command, which, assuming myJMSModule contains more than one submodule, will undeploy only the myQueue submodule; all other submodules are unaffected.

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name myJMSModule
   -undeploy -submoduletargets myQueue@JMSServer1

Sub-module Targeting for Application-scoped JMS Modules

For an application-scoped JMS module in an EAR, use the syntax: submodule_name@module_name@target_name to target a submodule. For example, if the queue in the above example were instead packaged as part of an enterprise application, you would use the command:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name myEnterpriseApp
   -targets ManagedServer1 -submoduletargets myQueue@myJMSModule@JMSServer1
   -deploy c:\localfiles\myEnterpriseApp.ear

To undeploy the same JMS module, enter the following command, which, assuming myEnterpriseApp contains more than one submodule, will undeploy only the myQueue submodule; all other submodules are unaffected.

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name myEnterpriseApp
   -undeploy -submoduletargets myQueue@myJMSModule@JMSServer1

Note:

When you undeploy an application that contains application-scoped resources, the resources are deleted along with the application, which can potentially cause abandoned transactions or lost messages as a result of deleted JMS destinations. See Unregister Resource Grace Period in Developing JTA Applications for Oracle WebLogic Server.

You should only undeploy applications that you are certain you want to completely remove; to temporarily stop client access to applications, use the -stop command, described in weblogic.Deployer Command-Line Reference.

For more information on JMS subdeployments, see Targeting JMS Modules and Subdeployment Resources in Administering JMS Resources for Oracle WebLogic Server.

Controlling Deployment File Copying with Staging Modes

The deployment staging mode determines how deployment files are made available to target servers that must deploy an application or standalone module.

WebLogic Server provides three different options for staging files: stage mode, nostage mode, and external_stage mode.

Staging Mode Descriptions and Best Practices

The following table describes the behavior and best practices for using the different deployment staging modes.

Table 6-2 Application Deployment Staging Modes

Deployment Staging Mode Behavior When to Use

Deployment Staging Mode	Behavior	When to Use
stage	The Administration Server first copies the deployment unit source files to the staging directories of target servers. (The staging directory is named `stage` by default, and it resides under the target server's root directory.) The target servers then deploy using their local copy of the deployment files.	Deploying small or moderate-sized applications to multiple WebLogic Server instances. Deploying small or moderate-sized applications to a cluster.
nostage	The Administration Server does not copy deployment unit files. Instead, all servers deploy using the same physical copy of the deployment files, which must be directly accessible by the Administration Server and target servers. With nostage deployments of exploded archive directories, WebLogic Server automatically detects changes to a deployment's JSPs or Servlets and refreshes the deployment. (This behavior can be disabled if necessary.)	Deploying to a single-server domain. Deploying to a cluster on a multi-homed machine. Deploying very large applications to multiple targets or to a cluster where deployment files are available on a shared directory. Deploying exploded archive directories that you want to periodically redeploy after changing content. Deployments that require dynamic update of selected Deployment Descriptors via the WebLogic Server Administration Console.
external_stage	The Administration Server does not copy deployment files. Instead, the administrator must ensure that deployment files are distributed to the correct staging directory location before deployment (for example, by manually copying files prior to deployment). With external_stage deployments, the Administration Server requires a copy of the deployment files for validation purposes. Copies of the deployment files that reside in target servers' staging directories are not validated before deployment. You can use the `-noversion` option to turn off the requirement that deployment files be on the Administration Server, but the `-noversion` option causes versioning information to be ignored; therefore, you cannot use the `-noversion` option with versioned applications. See Common Arguments.	Deployments where you want to manually control the distribution of deployment files to target servers. Deploying to domains where third-party applications or scripts manage the copying of deployment files to the correct staging directories. Deployments that do not require dynamic update of selected Deployment Descriptors via the WebLogic Server Administration Console (not supported in external_stage mode). Deployments that do not require partial redeployment of application components.

stage

The Administration Server first copies the deployment unit source files to the staging directories of target servers. (The staging directory is named stage by default, and it resides under the target server's root directory.)

The target servers then deploy using their local copy of the deployment files.

Deploying small or moderate-sized applications to multiple WebLogic Server instances.
Deploying small or moderate-sized applications to a cluster.

nostage

The Administration Server does not copy deployment unit files. Instead, all servers deploy using the same physical copy of the deployment files, which must be directly accessible by the Administration Server and target servers.

With nostage deployments of exploded archive directories, WebLogic Server automatically detects changes to a deployment's JSPs or Servlets and refreshes the deployment. (This behavior can be disabled if necessary.)

Deploying to a single-server domain.
Deploying to a cluster on a multi-homed machine.
Deploying very large applications to multiple targets or to a cluster where deployment files are available on a shared directory.
Deploying exploded archive directories that you want to periodically redeploy after changing content.
Deployments that require dynamic update of selected Deployment Descriptors via the WebLogic Server Administration Console.

external_stage

The Administration Server does not copy deployment files. Instead, the administrator must ensure that deployment files are distributed to the correct staging directory location before deployment (for example, by manually copying files prior to deployment).

With external_stage deployments, the Administration Server requires a copy of the deployment files for validation purposes. Copies of the deployment files that reside in target servers' staging directories are not validated before deployment.

You can use the -noversion option to turn off the requirement that deployment files be on the Administration Server, but the -noversion option causes versioning information to be ignored; therefore, you cannot use the -noversion option with versioned applications. See Common Arguments.

Deployments where you want to manually control the distribution of deployment files to target servers.
Deploying to domains where third-party applications or scripts manage the copying of deployment files to the correct staging directories.
Deployments that do not require dynamic update of selected Deployment Descriptors via the WebLogic Server Administration Console (not supported in external_stage mode).
Deployments that do not require partial redeployment of application components.

A server's staging directory is the directory in which the Administration Server copies deployment files for stage mode deployments. It is also the directory in which deployment files must reside before deploying an application using external_stage mode.

Most deployments use either stage or nostage modes, and the WebLogic Server deployment tools use the appropriate default mode when you deploy an application or module. For example, when deploying applications in WebLogic Server using weblogic.Deployer or WLST, if you do not specify a stage mode, the default stage mode is used; on the Administration Server, the default stage mode is nostage and on Managed Servers, it is stage.

The sections that follow explain how to explicitly set the deployment staging mode when deploying an application or module.

Using Nostage Mode Deployment

In nostage mode, the Administration Server does not copy the archive files from their source location. Instead, each target server must access the archive files from a single source directory for deployment. The staging directory of target servers is ignored for nostage deployments.

For example, if you deploy a Java EE application to three servers in a cluster, each server must be able to access the same application archive files (from a shared or network-mounted directory) to deploy the application.

Note:

The source for the deployment files in nostage mode is the path provided by the user at deployment time (as opposed to stage mode, where the source is the path in each server's staging directory). However, even in nostage mode, WebLogic Server copies out parts of the deployment to temporary directories. This enables users to update entire archived deployments or parts of archived deployments.

In nostage mode, the Web application container automatically detects changes to JSPs and servlets. Nostage also allows you to later update only parts of an application by updating those parts in one file system location and then redeploying.

The WebLogic Server Administration Console uses nostage mode as the default when deploying only to the Administration Server (for example, in a single-server domain). weblogic.Deployer uses the target server's staging mode, and Administration Servers use nostage mode by default. You can also select nostage mode if you run a cluster of server instances on the same machine, or if you are deploying very large applications to multiple machines that have access to a shared directory. Deploying very large applications in nostage mode saves time during deployment because no files are copied.

Syntax for Nostage Mode

To use nostage mode, specify -nostage as an option to weblogic.Deployer, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name mydeploymentname 
   -targets myserver1,myserver2,myserver3 -nostage 
   -deploy c:\localfiles\myapp.ear

Using Stage Mode Deployment

In stage mode, the Administration Server copies the deployment files from their original location on the Administration Server machine to the staging directories of each target server. For example, if you deploy a Java EE application to three servers in a cluster using stage mode, the Administration Server copies the deployment files to directories on each of the three server machines. Each server then deploys the Java EE application using its local copy of the archive files.

When copying files to the staging directory, the Administration Server creates a subdirectory with the same name as the deployment name. So if you deployed using the command:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name mytestear -stage -targets mycluster

   -deploy c:\Oracle\Middleware\wlserver_12.1\samples\server\medrecd\dist\physicianEar

a new directory, mytestear, would be created in the staging directory of each server in mycluster. If you do not specify a deployment name, a default deployment name (and staging subdirectory) is used:

For exploded archive deployments, the deployment name and staging subdirectory are the name of the directory you deployed (physicianEar in the example above).
For archived deployments, the default deployment name is the name of the archive file without the extension. For example, if you deploy physicianEar.ear, the deployment name and staging subdirectory are physicianEar.

The WebLogic Server Administration Console uses stage mode as the default mode when deploying to more than one WebLogic Server instance. weblogic.Deployer uses the target server's staging mode as the default, and Managed Servers use stage mode by default.

Stage mode ensures that each server has a local copy of the deployment files on hand, even if a network outage makes the Administration Server unreachable. However, if you are deploying very large applications to multiple servers or to a cluster, the time required to copy files to target servers can be considerable. Consider nostage mode to avoid the overhead of copying large files to multiple servers.

Syntax for Stage Mode

To use stage mode, specify -stage as an option to weblogic.Deployer, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
   -password weblogic -name mydeploymentname 
   -targets myserver1,myserver2,myserver3 -stage 
   -deploy c:\localfiles\myapp.ear

Using External_stage Mode Deployment

External_stage mode is similar to stage mode, in that target servers deploy using local copies of the deployment files. However, the Administration Server does not automatically copy the deployment files to targeted servers in external_stage mode; instead, you must copy the files to the staging directory of each target server before deployment. You can perform the copy manually or use automated scripts.

Within each target server's staging directory, deployment files must be stored in a subdirectory that reflects the deployment name. This can either be the name you type in for the deployment, or the default deployment name (the name of the exploded archive directory, or the name of the archive file without its file extension).

External_stage mode is the least common deployment staging mode. It is generally used only in environments that are managed by third-party tools that automate the required copying of files. You may also choose to use external_stage mode when you are deploying very large applications to multiple machines and you do not have a shared file system (and cannot use nostage mode). Using external_stage in this scenario decreases the deployment time because files are not copied during deployment.

You can use the -noversion option to turn off the requirement that deployment files be on the Administration Server, but the -noversion option causes versioning information to be ignored so you cannot use the -noversion option with versioned applications. See Common Arguments.

Syntax for external_stage Mode

To deploy an application in external_stage mode:

Make sure that the deployment files are accessible to the Administration Server. (See Uploading Deployment Files from a Remote Client.)
On each target server for the deployment, create a subdirectory in the staging directory that has the same name as the deployment name. For example, if you will specify the name myEARExternal for the deployment name, create a myEARExternal subdirectory in the staging directories for each target server.

Note:

If you do not specify a deployment name at deployment time, WebLogic Server selects a default name. See Understanding Default Deployment Names for more information.
If you are deploying a versioned application for use with production redeployment, create a subdirectory beneath the application directory for the version of the application you are deploying. For example, if you are deploying myEARExternal at version level 2.0Beta, the deployment files must reside in a subdirectory of each target server's staging directory named myEARExternal\2.0Beta.
Copy the deployment files into the staging subdirectories you created in Step 2 or 3 above.
Deploy the application or module using the weblogic.Deployer utility. For example:

java weblogic.Deployer -adminurl http://localhost:7001 -name weblogic
   -password weblogic -external_stage -name myEARExternal 
   -deploy c:\myapps\myear

Changing the Default Staging Behavior for a Server

The server staging mode specifies the default deployment mode for a server if none is specified at deployment time. For example, the server staging mode is used if you deploy an application or standalone module using weblogic.Deployer and you do not specify a staging mode. On the Administration Server, the default staging mode is nostage and on Managed Servers, it is stage.

Note:

You can only change the server staging mode by using the WebLogic Server Administration Console or by directly changing the ServerMBean via JMX.

Changing the server staging mode does not affect existing applications. If you want to change the staging mode for an existing application, you must undeploy the application deployment and then redeploy it with the new staging mode.

To set the server staging mode using the WebLogic Server Administration Console, follow the steps described in Set a server staging mode in Oracle WebLogic Server Administration Console Online Help. For detailed information on staging modes, see Table 6-2.

Staging Deployment Plans

An application's deployment plan can be staged independently of the application archive, allowing you to stage a deployment plan when the application is not staged. WebLogic Server provides three options for staging deployment plans using weblogic.Deployer:

-planstage—Copies the deployment plan to target servers' staging directories.
-plannostage—Does not copy the deployment plan to target servers, but leaves it in a fixed location.
-planexternal_stage—Does not copy the deployment plan to target servers. Instead, you must ensure that the deployment plan has been copied to the correct subdirectory in the target servers' staging directories. You can manually copy the deployment plan or use a third-party tool or script.

If you do not specify a staging mode, the deployment plan uses the value specified for application staging as the default.

For example, if deployment plan staging is not specified and application staging is set to stage, the deployment plan staging mode is set to planstage.

If both deployment plan staging and application staging are not specified, then the server setting is used as the default application staging mode. For example, if the server setting is to not stage, then the deployment plan staging mode is set to plannostage. In this case, if deployment plan staging is required, it must be specified.

Distributing Applications to a Production Environment

Distributing an application prepares it for deployment by copying its deployment files to all target servers and validating it. After you distribute an application, you can start it in administration mode, which restricts access to the application to a configured administration channel and allows you to distribute the application to a production environment (or distribute a new version of an application) without opening the application to external client connections.

While in administration mode, you can connect to an application only via a configured administration channel. This allows you to perform final ("sanity") checking of the application directly in the production environment without disrupting clients. After performing final testing, you can either undeploy the application to make further changes, or start the application to make it generally available to clients.

You can use the -adminmode option application in administration mode. See Starting a Distributed Application in Administration Mode.

When deploying across WebLogic domains, the CrossDomainConnector role allows you to make inter-domain calls from foreign domains. For a complete listing of all security roles, see Default Global Roles in Securing Resources Using Roles and Policies for Oracle WebLogic Server.

Distributing an Application

To distribute an application, use the weblogic.Deployer -distribute command, as in:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
     -password weblogic -distribute -name myTestDeployment
     /myDeployments/myApplication/

Starting a Distributed Application in Administration Mode

After WebLogic Server distributes the deployment files, you can start the application in administration mode so that you can access and test it via a configured administration channel. To configure an administration channel, see Configuring Network Resources in Administering Server Environments for Oracle WebLogic Server.

To start a distributed application in administration mode, use the -start command with the -adminmode option:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
     -password weblogic -start -adminmode -name myTestDeployment
     /myDeployments/myApplication/

Starting a Distributed Application

After performing final testing of a distributed application using a configured administration channel, you can open the application to new client connections by using the weblogic.Deployer -start command without the -adminmode option:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
     -password weblogic -start -name myTestDeployment

Deploying Shared Java EE Libraries and Dependent Applications

Java EE library support in WebLogic Server provides an easy way to share one or more Java EE modules or JAR files among multiple enterprise applications.

A Java EE library is a standalone Java EE module, multiple Java EE modules packaged in an enterprise application (EAR), or a plain JAR file that is registered with the Java EE application container upon deployment. After a Java EE library has been registered, you can deploy enterprise applications that reference the library. Each referencing application receives a copy of the shared Java EE library module(s) on deployment, and can use those modules as if they were packaged as part of the application itself.

Note:

Oracle documentation and WebLogic Server utilities use the term library to refer to both Java EE libraries and optional packages. Optional packages are called out only when necessary.

Understanding Deployment Behavior for Shared Libraries

WebLogic Server supports shared Java EE libraries by merging the shared files with a referencing application when the referencing application is deployed.

You first register a Java EE library or optional package with one or more WebLogic Server instances or clusters by deploying the library and indicating that the deployment is a library (see Registering Libraries with WebLogic Server). Deploying a library or package does not activate the deployment on target servers. Instead, WebLogic Server distributes the deployment files to target servers (if nostage deployment mode is used) and records the location of the deployment files, the deployment name, and any version string information for the library or package.

When an application that references a shared library or package is deployed, WebLogic Server checks the names and version string requirements against the libraries registered with the server. If an exact match for a library or package name is not found, or if the version requirements are not met, the application deployment fails.

If WebLogic Server finds a name and version string match for all of the libraries referenced in the application, the server adds the libraries' classes to the classpath of the referencing application and merges deployment descriptors from both the application and libraries in memory. The resulting deployed application appears as if the referenced libraries were bundled with the application itself.

The contents of a Java EE library are loaded into classloaders in the same manner as any other Java EE modules in an enterprise application. For example, EJB modules are loaded as part of the referencing application's classloader, while Web application modules are loaded in classloaders beneath the application classloader. If a shared Java EE library consists of an EAR, any classes stored in the EAR's APP-INF/lib or APP-INF/classes subdirectory are also available to the referencing application.

You cannot undeploy any Java EE libraries or optional packages that are referenced by a currently deployed application. If you need to undeploy a shared library or package, you must first undeploy all applications that use the shared files. For regular application maintenance, you should deploy a new version of a shared library or package and redeploy referencing applications to use the newer version of the shared files. See Editing Manifest Entries for Shared Libraries in Developing Applications for Oracle WebLogic Server for more information.

Registering Libraries with WebLogic Server

A shared Java EE library is a standard Java EE module or enterprise application that is registered with a WebLogic Server container as a library. To register a Java EE library with a WebLogic Server container, perform the following steps:

Ensure that the deployment file(s) you are working with represent a valid Java EE library or optional package. See Creating Shared Java EE Libraries in Developing Applications for Oracle WebLogic Server.
Select the WebLogic Server targets to which you will register the library or package. Shared libraries must be registered to the same WebLogic Server instances on which you plan to deploy referencing applications. (You may consider deploying libraries to all servers in a domain, so that you can later deploy referencing applications as needed.)

Register the library or package by deploying the files to your selected target servers, and identifying the deployment as a library or package with the -library option. For example:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
     -password weblogic -deploy -targets myserver1,myserver2
     -library /deployments/myLibraryApplication/

Specifying Library Versions at Deployment

As a best practice, your development team should always include version string information for a library or optional package in the manifest file for the deployment. See Editing Manifest Entries for Shared Libraries in Developing Applications for Oracle WebLogic Server for more information.

If you are deploying a library or package that does not include version string information, you can specify it at the command line using one or both of the following options:

libspecver—Defines a specification version for the library or package.
libimplver—Specifies an implementation version for the library or package.

For example:

java weblogic.Deployer -adminurl http://localhost:7001 -username weblogic
     -password weblogic -deploy -targets myserver1,myserver2
     -library -libspecver 700 -libimplversion 7.0.0.1Beta 
     /deployments/myLibraryApplication/

Note:

If both the manifest file and the weblogic.Deployer command line specify version information, and the values do not match, the deployment fails.

If you initially registered a library without providing a specification or implementation version, you must undeploy the library before registering a newer version and specifying version string information.

You can register multiple versions of a library or package, but each version must use the same version strings. For example, you cannot register a library having only a specification version, and then register a new version of the library having both a specification and an implementation version.

Deploying Applications That Reference Libraries

After you deploy the required library and package versions, you can deploy enterprise applications and modules that reference the libraries. Successfully deploying a referencing application requires that two conditions are met:

All referenced libraries are registered on the application's target servers.
Registered libraries meet the version requirements of the referencing application.

There is no special syntax for deploying a referencing application. Deploy the application as you would a standard enterprise application or Java EE module.

Note:

Referencing applications can be configured with varying levels of version requirements for shared libraries.

An application might be configured to require on of the following:

The latest version of a shared library or package (the latest registered version), or
A minimum version of a library or package (or a higher version), or
An exact version of a library or package.

If you cannot deploy a referencing application because of version requirements, try registering the required version of the conflicting library or package. Or, consult with your development team to determine whether the version requirements of the application can be relaxed. See Referencing Libraries in an enterprise application in Developing Applications for Oracle WebLogic Server for more information.

Note:

If you have an EAR library that contains Web application components, you cannot deploy multiple applications that reference the library because attempting to do so will result in a context path conflict. This is because context-root cannot be set for individual Web applications in EAR libraries; it can only be set for an entire library.

See Overview of Java EE Libraries and Optional Packages in Developing Applications for Oracle WebLogic Server for more information.

Best Practices for Deploying Applications

Follow Oracle-recommended best practices when deploying applications.

The Administration Server in a multiple-server domain should be used only for administration purposes. Although you can deploy to the Administration Server in a multiple-server domain, this practice is not recommended except during development.
Package deployment files in an archive format (.ear, .jar, .war, and so forth) when distributing files to different users or environments.
Check the scenarios described under Packaging Files for Deployment before deploying. In many cases it is more convenient to deploy applications in exploded format rather than archive format.
The WebLogic Server Administration Console, weblogic.Deployer tool, wldeploy Ant task, and WLST all provide similar functionality for deploying applications:
- Use the WebLogic Server Administration Console for interactive deployment sessions where you do not know the exact location of deployment files, or the exact names of target servers or deployed applications.
- Use weblogic.Deployer to integrate deployment commands with existing administrative shell scripts or automated batch processes.
- Use wldeploy in conjunction with the split development directory for developing and deploying new applications. wldeploy can also be used in place of weblogic.Deployer in administration environments that use Ant, rather than shell scripts.
- Use WLST when you want to create automated scripts that perform deployment tasks.
Use wldeploy, rather than the autodeploy directory, to deploy your own applications during development. The autodeploy directory is best used for quickly running new applications in a test or temporary environment. For example, if you download a sample application and want to evaluate its functionality, the autodeploy directory provides a quick way to deploy the application to a development server.