Skip navigation.
Downloads | Product Documentation | Support

Deploying WebLogic Server Applications

# Deployment Tools Reference

The following sections describe tools for deploying applications and standalone modules to WebLogic Server:

- weblogic.Deployer Utility
- wldeploy Ant Task
- WebLogic Builder
- Deployment Management API

# weblogic.Deployer Utility

The weblogic.Deployer utility replaces the earlier weblogic.deploy utility, which has been deprecated. The weblogic.Deployer utility is a Java-based deployment tool that provides a command-line interface to the WebLogic Server Deployment Management API on page 5-11. This utility was developed for administrators and developers who need to initiate deployment from the command line, a shell script, or any automated environment other than Java.

## Using weblogic.Deployer Utility

To use the weblogic.Deployer utility:

1. Set up your local environment so that WebLogic Server classes are in your system CLASSPATH and the JDK is available. You can use the setenv script located in your server's /bin directory to set the CLASSPATH.
2. Use the following command syntax:

>     % java weblogic.Deployer [options] [actions] [file(s)]

You can also list specific files in the archive that are to be deployed (or redeployed, or undeployed). The file list can include file names and directories relative to the root of the application. If you specify a directory, its entire subtree is deployed or redeployed.

## weblogic.Deployer Actions and Options

The following table lists weblogic.Deployer options.

Note: The `activate` and `deactivate` actions have been deprecated. Use `deploy` or `start` instead of `activate`. Use `undeploy` or `stop` instead of `deactivate`.

Table 5-1 weblogic.Deployer Options

Option | Description
--- | ---
`-adminurl <protocol>://<server>:<port>` | The URL of the Administration Server. Default is `http://localhost:7001`.
`-username <user>` | The Administrator username. If you supply the `-username` option but you do not supply a corresponding `-password` option, `weblogic.Deployer` prompts you for the password.
`-password <password>` | The password of the Administrator user. To avoid having the plain text password appear in scripts or in process utilities such as `ps`, first store the username and encrypted password in a configuration file using the `STOREUSERCONFIG` command with `weblogic.Admin`. Omit both the `-username` and `-password` options to `weblogic.Deployer` to use the values stored in the default configuration file. See STOREUSERCONFIG in the weblogic.Admin Command-Line Reference for more information on storing and encrypting passwords. If you want to use a specific configuration file and key file, rather than the default files, use the `-userconfigfile` and `-userkeyfile` options to `weblogic.Deployer`.
`-name <deployment name>` | Specifies the deployment name for the application or standalone module. This can be the name of an existing, configured application or the name to use when creating a new configuration.
`-targets <target list>` | A comma-separated list of the target servers and/or cluster names (<server1>,<cluster1>,...). Each target may be qualified with a J2EE module name (<module1>`@`<server1>). This enables different modules of the archive to be deployed on different servers. For an application that is currently deployed, `-targets` defaults to all current targets. For an application that you are deploying for the first time, `-targets` defaults to the Administration Server.
`-delete_files <file list>` | Used after the `-redeploy` action, this option removes static files from a server's staging directory. `delete_files` is valid only for unarchived deployments, and only for applications deployed using stage mode. You must specify target servers when using this option, as shown in the following example: `java weblogic.Deployer -adminurl http://myserver:7001 -username weblogic -password weblogic -name myapp -targets myapp@myserver -redeploy -delete_files myapp/tempindex.html` `delete_files` only removes files that WebLogic Server copied to the staging area during deployment. If you use the `delete_files` option with an application that was deployed using either nostage or external_stage mode, the command does not delete the files. `delete_files` can only be used in combination with the `redeploy` action.
`-userconfigfile <path to file>` | Specifies the location of a user configuration file to use for the administrative username and password. Use this option, instead of the `-user` and `-password` options, in automated scripts or in situations where you do not want to have the password shown on-screen or in process-level utilities such as `ps`. Before specifying the `-userconfigfile` option, you must first generate the file using the `weblogic.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference.
`-userkeyfile <path to file>` | Specifies the location of a user key file to use for encrypting and decrypting the username and password information stored in a user configuration file (the `-userconfigfile` option). Before specifying the `-userkeyfile` option, you must first generate the key file using the `weblogic.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference.
`-verbose` | Displays additional progress messages, including details about the prepare and activate phases of the deployment.
`-output <raw>` | Specify either `raw` or `formatted` to control the appearance of `weblogic.Deployer` output messages. Both output types contain the same information, but `raw` output does not contain embedded tabs. By default, `weblogic.Deployer` displays `raw` output.
`-debug` | Display debug messages in the standard output.
`-help` | Prints command-line help text for the most commonly-used `weblogic.Deployer` actions and options.
`-advanced` | Prints full command-line help text for all `weblogic.Deployer` actions and options.
`-examples` | Display example command lines for common tasks.
`-upload` | Transfers the specified source file(s) to the Administration Server. Use this option when you are on a different machine from the Administration Server and you cannot copy the deployment files by other means. The application files are uploaded to the WebLogic Server Administration Server's upload directory prior to deployment.
`-remote` | Indicates that `weblogic.Deployer` is not running on the same machine as the Administration Server, and that source paths specified in the command are valid for the Administration Server machine itself. If you do not use the `-remote` option, `weblogic.Deployer` assumes that all source paths are valid paths on the local machine.
`-nostage` | Does not copy the deployment files to target servers; instead, deploys them from the fixed location specified using the `-source` option. `nostage` is the default when you deploy to the Administration Server (for example, in a single-server domain).
`-stage` | Copies deployment files to target servers' staging directories before deployment. stage is used as the default when deploying to Managed Server targets.
`-external_stage` | Does not copy the deployment files to target servers; instead, you must ensure that deployment files have been copied to the correct subdirectory in the target servers' staging directories before deployment. You can manually copy the files or use a third-party tool or script.
`-nowait` | `weblogic.Deployer` prints the task ID and exits without waiting for the action to complete. This option is used to initiate multiple tasks and then monitor them later with the `-list` action.
`-timeout <seconds>` | Specifies the maximum time, in seconds, to wait for the deployment task to complete. After the time expires, `weblogic.Deployer` prints out the current status of the deployment and exits.
`-source <archive file or exploded archive directory>` | Specifies the location of the archive file or exploded archive directory to deploy.
`-altappdd` | Specifies the name of an alternate J2EE deployment descriptor (`application.xml`) to use for deployment.
`-altwlsappdd` | Specifies the name of an alternate WebLogic Server deployment descriptor (`weblogic-application.xml`) to use for deployment.
`-id <task identifier>` | Specifies the task identifier of a running deployment task. You can specify an identifier with the `-deploy`, `-redeploy,` or `-undeploy` actions, and use it later as an argument to the `-cancel` or `-list` actions. Make sure that the identifier is unique to all other running deployment tasks. The system automatically generates a unique identifier if you do not specify one.
`-version` | Prints version information.

Table 5-2 weblogic.Deployer Actions

Action | Description
--- | ---
`-deploy` | Deploys or redeploys an application.
`-undeploy` | Stops the deployment unit and removes staged files and deployment information from all target servers. (You may also use `-remove` as an alias.) Note: An application becomes unavailable to clients during an undeployment. WebLogic Server doesn't guarantee the operation of the application and deployment task if there is an access from the client at this time.
`-redeploy` | Replaces a running application or part of a running application. Note: An application becomes unavailable to clients during redeployment. WebLogic Server doesn't guarantee the operation of the application and deployment task if there is an access from the client at this time. For this reason, redeployment is not recommended for use in a production environment.
-stop | Makes an application inactive and unavailable to clients on target servers. The deployment information and staged files remain available on target servers for subsequent `-start`, `-deploy`, `-redeploy`, or `-undeploy` actions.
-start | Makes an inactive application available to clients on target servers. `-start` does not redistribute deployment files to target servers; the files must already be available via an earlier `-deploy` or `-distribute` action.
-distribute | Perform only the activate stage of a deployment by copying deployment files to target server staging directories (if necessary) and registering the deployment name. The application is ready for deployment, but is unavailable to clients on the target server. You can later use the `-start` action to make the application available to clients.
`-cancel` | Attempts to cancel the task identified by -id if it is not yet completed.
`-list` | Lists the status of the task identified by `-id`.
-listtask | Lists running deployment tasks in the domain.
-listapps | Lists all deployment names for applications and standalone modules deployed in the domain.

# wldeploy Ant Task

The `wldeploy` Ant task enables you to perform `weblogic.Deployer` functions using attributes specified in an Ant XML file. You can use `wldeploy` along with other WebLogic Server Ant tasks to create a single Ant build script that:

- Builds your application from source, using `wlcompile`, `appc`, and the Web Services Ant tasks.
- Creates, starts, and configures a new WebLogic Server domain, using the `wlserver` and `wlconfig` Ant tasks.
- Deploys a compiled application to the newly-created domain, using the `wldeploy` Ant task.

See Using Ant Tasks to Configure a WebLogic Server Domain in the WebLogic Server Command Reference for more information about `wlserver` and `wlconfig`. See Programming Topics in Developing WebLogic Server Applications for information about `wlcompile`.

## Basic Steps for Using wldeploy

To use the `wldeploy` Ant task:

1. Set your environment.

On Windows NT, execute the `setWLSEnv.cmd` command, located in the directory `WL_HOME\server\bin`, where `WL_HOME` is the top-level directory of your WebLogic Server installation.

On UNIX, execute the `setWLSEnv.sh` command, located in the directory `WL_HOME/server/bin`, where `WL_HOME` is the top-level directory of your WebLogic Server installation.

2. In the staging directory, create the Ant build file (`build.xml` by default). If you want to use an Ant installation that is different from the one installed with WebLogic Server, start by defining the `wldeploy` Ant task definition:

>     <taskdef name="wldeploy" classname="weblogic.ant.taskdefs.management.WLDeploy"/>

3. If necessary, add task definitions and calls to the `wlserver` and `wlconfig` tasks in the build script to create and start a new WebLogic Server domain. See Using Ant Tasks to Configure a WebLogic Server Domain in the WebLogic Server Command Reference for information about `wlserver` and `wlconfig`.
4. Add a call to `wldeploy` to deploy your application to one or more WebLogic Server instances or clusters. See Sample build.xml Files for wldeploy and wldeploy Ant Task Reference.
5. Execute the Ant task or tasks specified in the `build.xml` file by typing `ant` in the staging directory, optionally passing the command a target argument:

>     prompt> ant

## Sample build.xml Files for wldeploy

The following sample shows a `wldeploy` target that deploys an application to a single WebLogic Server instance:

>     <target name="deploy">
>        <wldeploy action="deploy"
>           source="${build}/ejb11_basic_statelessSession.ear" name="ejbapp"
>           user="a" password="a" verbose="true" adminurl="t3://localhost:7001"
>           debug="true" targets="myserver"/>
>     </target>

The following sample shows a more advanced `wldeploy` target that redeploys a single file in an exploded Web Application:

>     <target name="redeploy">
>        <wldeploy action="redeploy"
>           source="c:\myapps\myWebApp\" name="myWebApp"
>           user="weblogic" password="weblogic" verbose="true"
>           adminurl="t3://localhost:7001"
>           debug="true" targets="examplesServer">
>          <files file="index.jsp"/>
>        </wldeploy>
>     </target>

## wldeploy Ant Task Reference

The following table describes the attributes of the `wldeploy` Ant task. For more information about the definition of various terms, see weblogic.Deployer Actions and Options

Table 5-3 Attributes of the wldeploy Ant Task

Attribute | Description | Data Type | Required?
--- | --- | --- | ---
action | The deployment action to perform. Valid values are `deploy`, `cancel`, `undeploy`, `redeploy`, `distribute`, `start`, and `stop`. | String | No
adminurl | The URL of the Administration Server. | String | No
altappdd | Specifies the name of an alternate J2EE deployment descriptor (`application.xml`) to use for deployment. | String | No
altwlsappdd | Specifies the name of an alternate WebLogic Server deployment descriptor (`weblogic-application.xml`) to use for deployment. | String | No
debug | Enable `wldeploy` debugging messages. | boolean | No
external_stage | Specifies whether the deployment uses external_stage deployment mode. | boolean | No
files | Specifies a file or list of files on which to perform a deployment action (for example, a list of JSPs to redeploy). See Sample build.xml Files for wldeploy. | FileSet | No
id | Identification used for obtaining status or cancelling the deployment. | String | No
name | The deployment name for the deployed application. | String | No
nostage | Specifies whether the deployment uses nostage deployment mode. | boolean | No
nowait | Specifies whether wldeploy returns immediately after making a deployment call (by deploying as a background task). | boolean | No
password | The administrative password. To avoid having the plain text password appear in the build file or in process utilities such as `ps`, first store a valid username and encrypted password in a configuration file using the `weblogic.Admin STOREUSERCONFIG` command. Then omit both the `username` and `password` attributes in your Ant build file. When the attributes are omitted, `wldeploy` attempts to login using values obtained from the default configuration file. If you want to obtain a username and password from a non-default configuration file and key file, use the `userconfigfile` and `userkeyfile` attributes with `wldeploy`. See STOREUSERCONFIG in the weblogic.Admin Command-Line Reference for more information on storing and encrypting passwords. | String | No
remote | Specifies whether the server is located on a different machine. This affects how filenames are transmitted. | boolean | No
source | The source file to deploy. | File | No
stage | Specifies whether the deployment uses stage deployment mode. | boolean | No
targets | The list of target servers to deploy to. | String | No
timeout | The maximum time to wait for a deployment to succeed. | int | No
upload | Specifies whether the source file(s) are copied to the Administration Server's upload directory prior to deployment. | boolean | No
user | The administrative username. | String | No
userconfigfile | Specifies the location of a user configuration file to use for obtaining the administrative username and password. Use this option, instead of the `user` and `password` attributes, in your build file when you do not want to have the plain text password shown in-line or in process-level utilities such as `ps`. Before specifying the `userconfigfile` attribute, you must first generate the file using the `weblogic.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference. | String | No
userkeyfile | Specifies the location of a user key file to use for encrypting and decrypting the username and password information stored in a user configuration file (the `userconfigfile` attribute). Before specifying the `userkeyfile` attribute, you must first generate the key file using the `weblogic.Admin` `STOREUSERCONFIG` command as described in STOREUSERCONFIG in the weblogic.Admin Command-Line Reference. | String | No
verbose | Specifies whether `wldeploy` displays verbose output messages. | boolean | No
failonerror | This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. This attribute is set to true by default. | Boolean | No

.

# WebLogic Builder

WebLogic Builder is a WebLogic Server tool for generating and editing deployment descriptors for J2EE applications. It can also deploy applications to single servers.

See the WebLogic Builder Online Help.

# Deployment Management API

A deployment task is initiated through a DeployerRuntimeMBean—a singleton (an object for which only one instance exists) that resides on an Administration Server. DeployerRuntimeMBean provides methods for activating, deactivating, and removing an application. These methods return a DeploymentTaskRuntimeMBean that encapsulates the request and provides the means for tracking its progress. DeploymentTaskRuntimeMBean provides ongoing status of the request through TargetStatus objects, one per target.

The WebLogic Server deployment management API is defined by the following WebLogic Server MBeans:

- DeployerRuntimeMBean—programmatic interface to deployment requests. Deployment requests provided through the DeployerRuntimeMBean manifest the configuration state into the application and appropriate component configuration MBeans. These MBeans persist the deployment state of applications in the WebLogic Server domain.
- DeploymentTaskRuntimeMBean—interface for encompassing deployment tasks.

The deployment management API is asynchronous. The client must poll the status or utilize ApplicationMBean notifications to determine when the task is complete.

For more information about WebLogic Server deployment management APIs, see the weblogic.management.deploy Javadoc.