Deploying Applications to WebLogic Server
The sections that follow organize common deployment tasks 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.
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:
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.
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:
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:
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.
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:
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.
Because preStart application lifecycle listeners are invoked during the prepare phase of an application—which occurs when an edit session is activated—JNDI lookup of system resources will fail 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 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 Administration Console), JNDI lookup of the JDBC system resource will fail because the preStart application lifecycle listeners were invoked before the system resource was activated. To look up system resources from JNDI in your preStart lifecycle listeners, BEA 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, you could:
Deploy the application that uses the system resource you created in step 2. For information on deploying applications from the Administration Console, see Deploy applications and modules in Administration Console Online Help.
See Overview of J2EE Libraries and Optional Packages in Developing Applications with WebLogic Server for more information.
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.
Deployment targets are the servers or groups of servers on which you deploy an application or stand-alone 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.
A configured host name that routes requests for a particular DNS name to a WebLogic Server instance or cluster. See Configuring Virtual Hosting in Designing and Configuring WebLogic Server Environments for more information.
A stand-alone 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.
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:
If you specify a cluster target (using
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 servers), 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 Using WebLogic Server Clusters for more information.
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.
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.
Warning: 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.
-DClusterConstraintsEnabled=trueenforces strict cluster deployment for servers in a domain.
-DClusterConstraintsEnabled=falseensures 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.
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 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.
Stand-alone JDBC, JMS, and WLDF application modules can be deployed similar to stand-alone J2EE modules. For a stand-alone 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 stand-alone 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, Configuring WebLogic JDBC Resources, and Configuring Diagnostic System Modules.
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. For more information, see Understanding JMS Resource Configuration.
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:
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:
During deployment, WebLogic Server selects default JMS Server targets for submodules in a JMS application module, as described in Targeting JMS Modules and Subdeployment Resources . 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
For a stand-alone JMS module, the submodule targeting syntax is:
target_name. For example, to deploy a stand-alone JMS module on a single server instance, targeting the submodule
myQueue to a JMS Server named JMSServer1, enter the command:
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.
For an application-scoped JMS module in an EAR, use the syntax:
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:
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.
Warning: 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. For more information, see Unregister Resource Grace Period.
Warning: 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.
The deployment staging mode determines how deployment files are made available to target servers that must deploy an application or stand-alone module. WebLogic Server provides three different options for staging files: stage mode, nostage mode, and external_stage mode.
The Administration Server first copies the deployment unit source files to the staging directories of target servers. (The staging directory is named
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.)
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
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. The sections that follow explain how to explicitly set the deployment staging mode when deploying an application or module.
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 J2EE 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 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.
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 J2EE 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 J2EE Application using its local copy of the archive files.
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:
physicianEarin the example above).
physicianEar.ear, the deployment name and staging subdirectory are
The 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.
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. For information, see Common Arguments.
myEARExternalfor the deployment name, create a
myEARExternalsubdirectory 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.
myEARExternalat version level 2.0Beta, the deployment files must reside in a subdirectory of each target server's staging directory named
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 stand-alone module using
weblogic.Deployer and you do not specify a staging mode.
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 Administration Console, follow the steps described in Set a server staging mode in Administration Console Online Help. For detailed information on staging modes, see Table 5-2.
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. For information, see 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. See Configuring Network Resources in Designing and Configuring WebLogic Server Environments.
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
J2EE library support in WebLogic Server provides an easy way to share one or more J2EE modules or JAR files among multiple Enterprise Applications. A J2EE library is a stand-alone J2EE module, multiple J2EE modules packaged in an Enterprise Application (EAR), or a plain JAR file that is registered with the J2EE application container upon deployment. After a J2EE library has been registered, you can deploy Enterprise Applications that reference the library. Each referencing application receives a copy of the shared J2EE library module(s) on deployment, and can use those modules as if they were packaged as part of the application itself.
You first register a J2EE 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 J2EE library are loaded into classloaders in the same manner as any other J2EE 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 J2EE library consists of an EAR, any classes stored in the EAR's
APP-INF/classes subdirectory are also available to the referencing application.
You cannot undeploy any J2EE 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 with WebLogic Server for more information.
A shared J2EE library is a standard J2EE module or Enterprise Application that is registered with a WebLogic Server container as a library. To register a J2EE library with a WebLogic Server container, perform the following steps:
-libraryoption. For example:
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 Attributes for Shared Libraries in Developing Applications with WebLogic Server for more information about version string requirements and best practices.
libspecver—Defines a specification version for the library or package.
libimplver—Specifies an implementation version for the library or package.
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.
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:
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 with 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 J2EE Libraries and Optional Packages in Developing Applications with WebLogic Server for more information.
Notes: Auto-deployment is a method for quickly deploying an application to a stand-alone server (Administration Server) for evaluation or testing. It is recommended that this method be used only in a single-server development environment. Use of auto-deployment in a production environment or for deployment to Managed Servers is not recommended.
BEA recommends that you use the WebLogic Server split development directory and
wldeploy ant task, rather than auto-deployment, when developing an application. See Creating a Split Development Directory in Developing Applications with WebLogic Server.
If auto-deployment is enabled, when an application is copied into the
\autodeploy directory of the Administration Server, the Administration Server detects the presence of the new application and deploys it automatically (if the Administration Server is running). If WebLogic Server is not running when you copy the application to the
\autodeploy directory, the application is deployed the next time the WebLogic Server Administration Server is started. Auto-deployment deploys only to the Administration Server.
Notes: Due to the file locking limitations of Windows, if an application is exploded, all the modules within the application must also be exploded. In other words, you cannot use auto-deployment with an exploded application or module that contains a JAR file.
Auto-deployment is intended for use with a single server target in a development environment. If you use other tools, such as the Administration Console, to add targets to an auto-deployed, exploded application, redeploying the application does not propagate changes to the new target servers.
Development mode enables a WebLogic Server instance to automatically deploy and update applications that are in the
domain_name/autodeploy directory (where
domain_name is the name of a WebLogic Server domain). In other words, development mode lets you use the auto-deployment feature. Production mode disables the auto-deployment feature and prevents any applications you place in the
autodeploy directory after you switch to production mode from being deployed. When you switch from development mode to production mode, any applications that were previously deployed via the
autodeploy directory remain deployed; if you wish to undeploy or redeploy such applications after you have switched to production mode, you must undeploy or redeploy them manually (for instance, with the
weblogic.Deployer command and the
-redeploy options, as described in weblogic.Deployer Command-Line Reference).
By default, a WebLogic Server domain runs in development mode. To specify the mode for a domain, see Creating and Configuring Domains Using the Configuration Wizard.
A deployment unit that was auto-deployed can be dynamically redeployed while the server is running. To dynamically redeploy, copy the new version of the archive file over the existing file in the
Note: If you delete an application from the
/autodeploy directory when the server is not active, WebLogic Server will not detect that the application was deleted even when the server is again in an active state. In order to prevent an out-of-sync domain tree, BEA recommends that you only remove applications from the
/autodeploy directory when the server is in an active state.
To auto-deploy an application in exploded archive format, copy the entire exploded archive directory to the
/autodeploy directory. WebLogic Server automatically deploys exploded archive applications using the nostage deployment mode.
Notes: Due to Windows file locking limitations, if you deploy an exploded EAR directory that contains archived modules (JAR files), the JAR files are locked during the deployment and you will not be able to remove them. Therefore, if an application you plan to auto-deploy is exploded, all of the modules it contains must also be exploded.
Auto-deployment will fail if you attempt to deploy an application in exploded archive format when the contents of the entire exploded archive directory are not in the
/autodeploy directory. Because large applications in exploded archive format can take a long time to copy into the
/autodeploy directory, BEA recommends that you copy the exploded archive directory into the
/autodeploy directory while the server is in an inactive state. After the entire exploded archive directory has been copied in the
/autodeploy directory, you can return the server to an active state and the application will be autodeployed. Alternatively, BEA recommends that you deploy large applications with
weblogic.Deployer, described in weblogic.Deployer Command-Line Reference.
When an application has been auto-deployed in exploded archive format, the Administration Server periodically looks for a file named
REDEPLOY in the exploded application directory. If the timestamp on this file changes, the Administration Server redeploys the exploded directory.
REDEPLOY, and place it in the WEB-INF or
META-INFdirectory, depending on the application type you are deploying:
REDEPLOY file works only for an entire deployed application or stand-alone module. If you have deployed an exploded Enterprise Application, the
REDEPLOY file controls redeployment for the entire application—not for individual modules (for example, a Web application) within the Enterprise Application. If you deploy a Web application by itself as an exploded archive directory, the
REDEPLOY file controls redeployment for the entire Web application.
Note: You must
REDEPLOY file (alter its timestamp) any time you wish to trigger redeployment of an auto-deployed application. Even if you modify an application while a server is shut down, you must
REDEPLOY to ensure that changes are applied when the server next starts up.
To undeploy an application that was auto-deployed in exploded format, use the
-undeploy command, or use the Administration Console to remove the deployment configuration. Then remove the application files from the
Note: If you delete application files from the
/autodeploy directory when the server is not active, WebLogic Server will not detect that the application files were deleted even when the server is again in an active state. In order to prevent an out-of-sync domain tree, BEA recommends that you only remove application files from the
/autodeploy directory when the server is in an active state.
.war, and so forth) when distributing files to different users or environments.
wldeployAnt task, and WLST all provide similar functionality for deploying applications:
weblogic.Deployerto integrate deployment commands with existing administrative shell scripts or automated batch processes.
wldeployin conjunction with the split development directory for developing and deploying new applications.
wldeploycan also be used in place of
weblogic.Deployerin administration environments that use Ant, rather than shell scripts.
wldeploy, rather than the
autodeploydirectory, to deploy your own applications during development. The
autodeploydirectory 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
autodeploydirectory provides a quick way to deploy the application to a development server.