Deploying Applications

Use the deploy subcommand in remote mode to deploy an assembled application or module to Payara Server. If an error occurs during deployment, the application or module is not deployed. If a module within an application contains an error, the entire application is not deployed.

These failures prevent a partial deployment that could leave the server in an inconsistent state.

By default, the deployment target is the default server instance, server. To deploy only to the default server instance, specify no target. If you deploy the application or module only to the domain target, it exists in the domain central repository, but no server instances or clusters can reference the component unless you add references.

You can also deploy a component to a specific stand-alone server instance or cluster. When you deploy to server instances or clusters, the application or module exists in the domain’s central repository and is referenced by any clusters or server instances that you deployed to. For a cluster, the preselected deployment target is server.

If the component is already deployed or already exists, you can forcefully redeploy if you set the --force option of the deploy subcommand to true. The redeploy subcommand also accomplishes this. See this example.

You can see the enabled or disabled status of an application or module by using the show-component-status subcommand.

For information about how the application or module name is derived, see Naming Standards.

Use the --altdd or --runtimealtdd options of the deploy (and redeploy) subcommand to deploy an application or module using a top-level alternate deployment descriptor. The --altdd option specifies a top-level alternate Jakarta EE standard deployment descriptor.

The --runtimealtdd option specifies a top-level alternate Payara Server runtime deployment descriptor. See this example for more information.

For more information about deployment descriptors associated with Payara Server, see Deployment Descriptors and Annotations.

You can also specify the deployment order of an application by using the --deploymentorder option of the deploy (and redeploy) subcommand. This is useful for applications that must be loaded in a certain order at server startup. Applications with lower deployment order numbers are loaded first. See this example for more information.

If a deployment order is not specified at the time an application is deployed, the default deployment order of 100 is assigned. If two applications have the same deployment order, the application that was deployed first is loaded first at server startup.

After deployment, the deployed application or module exists in the central repository and can be referenced by the server instances or clusters that you deployed to as targets.

The asadmin create-application-ref and asadmin delete-application-ref subcommands enable you to add or delete targets for a deployed component.

Because the application or module itself is stored in the central repository, adding or deleting targets adds or deletes the same version of the component on different targets.

There are a number of commands that can be used to list deployed applications or modules and their subcomponents. Use the commands in this section in remote mode.

Use the redeploy subcommand in remote mode to overwrite a previously-deployed application or module. You can also accomplish this task by using the --force option of the deploy subcommand. Whenever a redeployment is done, the HTTP and SFSB sessions in transit at that time, and the EJB timers, become invalid unless you use the --keepstate=true option of the redeploy subcommand.

Before You Begin
You must remove a preconfigured resource before it can be updated.

Use the disable subcommand in remote mode to immediately deactivate a deployed application or module without removing it from the server.

Disabling a component makes the component inaccessible to clients. However, the component is not overwritten or uninstalled, and can be enabled by using the asadmin enable subcommand.

An application or module is enabled by default.

An enabled application or module is runnable and can be accessed by clients if it has been deployed to an accessible server instance or cluster. An application or module is enabled by default.

Use the enable subcommand in remote mode to enable an application or module that has been disabled.

An application or module that is deployed to more than one target can be enabled on one target and disabled on another. If a component is referenced by a target, it is not available to users unless it is enabled on that target.

Use the undeploy subcommand in remote mode to uninstall a deployed application or module and remove it from the repository. To reinstate the component, you must deploy the component again using the deploy subcommand.

Dynamic reloading enables you to change the code or deployment descriptors of an application or module without needing to perform an explicit redeployment.

Instead, you can copy the changed class files or descriptors into the deployment directory for the application or module. The server checks for changes periodically and automatically redeploys the changes if the timestamp of the .reload file in the root directory for the application or module has changed.

Automatic deployment involves copying an archive file into a special auto-deploy directory where the archive is automatically deployed by Payara Server at predefined intervals.

This method is useful in a development environment because it allows new code to be tested quickly. Automatic deployment is enabled by default, and is available only on the default server instance.

In the deployment plan for an EAR file, the glassfish-application.xml file is located at the root. The deployment descriptor for each module is stored according to this syntax: module-name.gf-dd-name, where the gf-dd-name depends on the module type.

If a module named MyModule contains a CMP mappings file, the file is named MyModule.sun-cmp-mappings.xml. A .dbschema file is stored at the root level. Each / (forward slash) is replaced by a # (pound sign).

An expanded directory, also known as an exploded directory, contains an un-assembled (un-packaged) application or module. To deploy a directory format instead of an archive, file, use the asadmin deploy subcommand in remote mode and specify a path to a directory instead of to an archive file.

The contents of the directory must be the same as the contents of a corresponding archive file, with one exception.

An application archive file contains archive files for its modules, for example myUI.war and myEJB.jar.

The expanded application directory contains expanded directories for the modules, for example myUI_war and myEJB_jar, instead.

You can change deployment descriptor files directly in the expanded directory.

If your environment is configured to use dynamic reloading, you can also dynamically reload applications or modules that are deployed from the directory. For instructions, see To Reload Changes to Applications or Modules Dynamically.

Unlike archive file deployment, directory deployment does not copy the directory contents to the remote hosts.

This means that for deployment to a cluster, the directory path may exist for both the DAS and the remote server instances but may not actually correspond to the same physical location. If any target server instance cannot see the deployed directory, or finds that it contains different files from those detected by the DAS, deployment fails.

Integrated development environments (IDEs) typically use directory deployment, so you do not need to deal directly with the expanded format.

Before You Begin

On each cluster or stand-alone server instance to which the application or module is deployed, the directory must be accessible and must contain the same files as found by the DAS.

On Windows, if you are deploying a directory on a mapped drive, you must be running Payara Server as the same user to which the mapped drive is assigned. This enables Payara Server to access the directory.

As described in To Deploy an Application or Module Automatically Payara Server has the ability to automatically deploy applications on server start using the autodeploy directory. While acceptable in development environments, the internal scanner used to deploy files in this directory is a security risk for production environments.

To introduce the capability of deploying an application on server startup without the risk of enabling the deployment scanner, Payara Server has the ability to run asadmin commands at startup via command scripts, either before or after the server’s boot sequence has been completed.

To enable this feature, the start-domain Asadmin command accepts two extra options: --prebootcommandfile and --postbootcommandfile which can be used as follows:

To deploy an application at startup time, simply create a command script that deploys the application like so:

And use this script file with the --postbootCommandFile option:

Payara Server also has the ability to deploy applications whose archives are hosted on a remote location. To deploy an application archive that can be reached via its URL, use the deploy-remote-archive subcommand, which works similarly to the standard deploy command, and can be used in the same way.

The only difference in the command is that it takes a valid URL instead of a file location in the host’s filesystem.

Payara Server also has the ability to deploy applications whose archives are hosted as Maven artifacts on remote repositories. To deploy an application archive in this manner, use the deploy-remote-archive subcommand, which works similarly to the standard deploy command, and point it to a set of Maven GAV (Group ID/Artifact ID/Version) coordinates where the artifact is located.

By default, the command will search for the artifact in Maven Central, but specific Maven repositories can be added as search locations by using the additionalRepositories option, which accepts a comma separated list of repository URLs.

Use the set-web-context-param subcommand in remote mode to change the configuration of a deployed application without the need to modify the application’s deployment descriptors and repackage and redeploy the application. By using this subcommand, you are either adding a new parameter that did not appear in the original web module’s descriptor, or overriding the descriptor’s setting of the parameter.

If the --ignoreDescriptorItem option is set to true, then the server ignores any setting for that context parameter in the descriptor, which means you do not need to specify an overriding value on the set-web-context-param subcommand.

The server behaves as if the descriptor had never contained a setting for that context parameter.

This subcommand sets a servlet context-initialization parameter of one of the following items:

Before You Begin

The application must already be deployed. Otherwise, an error occurs.

Use the unset-web-context-param subcommand in remote mode to unset an environment entry for a deployed web application or module that has been set by using the set-web-env-entry subcommand. There is no need to modify the application’s deployment descriptors and repackage and redeploy the application.

This subcommand unsets an environment entry for one of the following items:

When an entry is unset, its value reverts to the value, if any, that is set in the application’s deployment descriptor. This subcommand cannot be used to change the value of an environment entry that is set in an application’s deployment descriptor.

Instead, use the set-web-context-param subcommand for this purpose.

Before You Begin

The application must already be deployed, and the entry must have previously been set by using the set-web-env-entry subcommand. Otherwise, an error occurs.

Use the list-web-context-param subcommand in remote mode to list the parameters that have previously been set by using the set-web-context-param subcommand.

The subcommand does not list parameters that are set only in the application’s deployment descriptor. For each parameter, the following information is displayed:

An application uses the values of environment entries to customize its behavior or presentation. Use the set-web-env-entry subcommand in remote mode to change the configuration of a deployed application without the need to modify the application’s deployment descriptors and repackage and redeploy the application.

By using this subcommand, you are either adding a new parameter that did not appear in the original web module’s descriptor, or overriding the descriptor’s setting of the parameter.

If you the --ignoreDescriptorItem option is set to true, then the server ignores any setting for that environment entry in the descriptor, which means you do not need to specify an overriding value on the set-web-env-entry subcommand. The server behaves as if the descriptor had never contained a setting for that environment entry.

This subcommand sets an environment entry for one of the following items:

Before You Begin

The application must already be deployed. Otherwise, an error occurs.

Use the unset-web-env-entry subcommand in remote mode to unset an environment entry for a deployed web application or module.

Use the list-web-env-entry subcommand to list environment entries for a deployed web application or module. For each entry, the following information is displayed:

As an alternative to Step 3 through Step 6, you can define application-scoped resources in the glassfish-resources.xml or payara-resources.xml deployment descriptor.

For more information, see Application-Scoped Resources.

Redeployment of a connector module maintains all connector connection pools, connector resources, and administered objects defined for the previously deployed connector module. You do not need to reconfigure any of these resources.

However, you should redeploy any dependent modules. A dependent module uses or refers to a connector resource of the redeployed connector module. Redeployment of a connector module results in the shared class loader reloading the new classes. Other modules that refer to the old resource adapter classes must be redeployed to gain access to the new classes.

For more information about class loaders, see "Class Loaders" in the Application Development section.

During connector module redeployment, the server log provides a warning indicating that all dependent applications should be redeployed.

Client applications or application components using the connector module’s resources may throw class cast exceptions if dependent applications are not redeployed after connector module redeployment.

To disable automatic redeployment, set the --force option to false. In this case, if the connector module has already been deployed, Payara Server provides an error message.

A connector module can be deployed as a Jakarta EE component in a Jakarta EE application. Such connectors are only visible to components residing in the same Jakarta EE application. Deploy this application as you would any other Jakarta EE application.

You can create new connector connection pools and connector resources for a connector module embedded within a Jakarta EE application by prefixing the connector name with app-name#.

For example, if an application appX.ear has jdbcra.rar embedded within it, the connector connection pools and connector resources refer to the connector module as appX#jdbcra.

An embedded connector module cannot be un-deployed using the name app-name#connector-name. To undeploy the connector module, you must undeploy the application in which it is embedded.

The association between the physical JNDI name for the connector module in Payara Server and the logical JNDI name used in the application component is specified in the Payara Server-specific XML descriptor glassfish-ejb-jar.xml.

For more detailed information about creating application clients, see "Developing Java Clients" in the Application Development section. This chapter includes information on the following topics:

If the context-root or module-id is not specified during deployment, the name of the EAR or JAR file without the .ear or .jar extension is used. For an application, the relative path to the application client JAR file is also included. If the application or module is not in EAR or JAR file format, a context-root or module-id is generated.

For details about naming, see Naming Standards.

Before You Begin
This task applies if you want to use the appclient script to run the application client on a system other than where the server runs.

After application clients are downloaded, they remain on the client until they are manually removed.

If you undeploy an application client, you can no longer download that application client because it might be in an inconsistent state. If you try to launch an application client that was previously downloaded (even though the server side of the application client is no longer present), the results are unpredictable unless the application client has been written to tolerate such situations.