This tool can be used to upgrade an existing Payara Server installation to a newer version. The Upgrade Tool is bundled in Payara Server by default and is maintained as a separate JAR artifact under the fish.payara.extras:payara-upgrade-tool GAV coordinates.
The upgrade tool can be manually upgraded to a newer version in case it is needed. To do so, download the latest 2.x JAR release from Nexus using this link and then replace the older version into your Payara Server installation under the ${PAYARA_SERVER_INSTALL}/glassfish/lib/asadmin folder.
|
Upgrading to Payara Server 7
It is possible to upgrade a Payara Server 6.x domain to version 7.x. The process should not be any different as to upgrading between different Payara 6 minor versions, though with the following caveats:
-
When performing an upgrade from Payara 6 to Payara 7, make sure that you’re using JDK 21 as this is the minimum JDK version required to run Payara Server 7.
| It is recommended that users should run the latest version of Payara Server 6.x before attempting to upgrade to version 7.x. |
Asadmin CLI Commands
The following are the Asadmin CLI commands available to the upgrade tool.
Upgrade Server Command
- Usage
-
asadmin> upgrade-server - Aim
-
This command can be used to upgrade Payara Server to the specified distribution along with all SSH nodes in the
domain.xmlconfiguration file.
The command will also back up the old version and domains in the default location (payara7/glassfish/domains) or the location specified using the --domaindir option to allow for rolling back.
Command Options
| Option | Type | Description | Default | Mandatory |
|---|---|---|---|---|
|
String |
The username for the Payara Nexus server. |
Yes, unless |
|
|
String |
Specifies the version number of the new version of Payara to use. |
Yes, unless |
|
|
Enum |
Specifies the distribution of Payara Server to download. This can payara, payara-web, payara-ml, or payara-web-ml. |
payara |
No |
|
Boolean |
Determines if the upgrade should be installed in-place, or staged into "x.new" directories. Scripts are provided that can be used to apply and rollback the staged install. This option is automatically enabled when running the command on Windows. |
False on Unix, True on Windows |
No |
|
String |
The directory containing the domains. The domains in this directory are backed up, and their config is used to determine the nodes which will also be upgraded. |
|
No |
|
String |
The path to the local Payara Server zip archive to use for upgrading instead of downloading from the Payara Enterprise repository. When this parameter is specified, the |
No |
|
|
String |
Specifies the nodes to upgrade if you want to selectively upgrade certain nodes. Provide as a comma-separated list of node names. |
All nodes in the cluster |
No |
Example
This example upgrades a Payara Web distribution to version 7.1.0
asadmin> upgrade-server --username example-user --distribution web --version 7.1.0To selectively upgrade specific nodes, use the --nodes option with a comma-separated list of node names.
This example upgrades the domain administration server and one remote node, leaving other nodes to be upgraded later:
asadmin> upgrade-server --username example-user --version 7.1.0 --nodes localhost-domain1,remotehost1-node1Rollback Server Command
- Usage
-
asadmin> rollback-server - Aim
-
This command can be used to rollback Payara Server to the point before the upgrade-server command was run, restoring the most recent backup of the domain (expected to be the backup created during execution of the
upgrade-servercommand).
This command is not supported on Windows OS, please use the rollbackUpgrade.bat script instead.
|
Command Options
| Option | Type | Description | Default | Mandatory |
|---|---|---|---|---|
|
String |
The directory containing the domains. The domains in this directory are backed up, and their config is used to determine the nodes which will also be upgraded. |
|
No |
|
String |
Specifies the nodes to rollback if you want to selectively rollback certain nodes. Provide as a comma-separated list of node names. |
All nodes in the cluster |
No |
Staged Upgrades
When the upgrade-server command is either used on Windows or with the --stage option enabled, the new server files are installed next to the current installation in various .new directories (e.g. payara7/glassfish/bin.new). The following helper scripts are available to interact with staged upgrades.
Apply Staged Upgrade Script
- Usage
-
> ./payara7/glassfish/bin/applyStagedUpgrade - Aim
-
This script is used to apply an upgrade staged using the
upgrade-servercommand. It will move the current installation into .old directories, and the staged .new installation into the expected "current" location. It will then upgrade the nodes of the domains in the default domain dir, or the domains in the directory provided using--domaindir
Command Options
| Option | Type | Description | Default | Mandatory |
|---|---|---|---|---|
|
String |
The directory containing the domains. The config of the domains in this directory are used to determine the nodes which will also be upgraded. |
${as-install}/domains |
No |
|
String |
Specifies the nodes to upgrade if you want to selectively upgrade certain nodes. Provide as a comma-separated list of node names. |
All nodes in the cluster |
No |
Rollback Upgrade Script
- Usage
-
> ./payara7/glassfish/bin/rollbackUpgrade - Aim
-
This script is used to rollback a server upgrade applied using the
applyStagedUpgradescript. It will move the .old installation back into the expected "current" location, and the applied upgrade back into .new directories. It will then rollback the nodes of the domains in the default domain dir, or the domains in the directory provided using--domaindir
Command Options
| Option | Type | Description | Default | Mandatory |
|---|---|---|---|---|
|
String |
The directory containing the domains. The config of the domains in this directory are used to determine the nodes which will also be rolled back. |
|
No |
|
String |
Specifies the nodes to rollback if you want to selectively rollback certain nodes. Provide as a comma-separated list of node names. |
All nodes in the cluster |
No |
Configure Logging Levels
The upgrade tool commands and helper scripts will print a set of minimum details of the operations executed (upgrade, staging, rollback). For troubleshooting scenarios, or if wanting to review in detail all executed actions, the following 2 environment variables are available to control the level of logging done by the Upgrade tool:
AS_DEBUG-
Set to
trueto configure the Upgrade Tool’s logging level toFINER. AS_TRACE-
Set to
trueto configure the Upgrade Tool’s logging level toFINESET.
These variables can also be configured as system properties in the Asadmin CLI script file located in the {as-install}/bin folder like this:
AS_INSTALL=`dirname "$0"`/../glassfish
AS_INSTALL_LIB="$AS_INSTALL/lib"
. "${AS_INSTALL}/config/asenv.conf"
JAVA=java
#Depends upon Java from ../config/asenv.conf
if [ ${AS_JAVA} ]; then
JAVA=${AS_JAVA}/bin/java
fi
exec "$JAVA" -DAS_DEBUG=true -XX:+IgnoreUnrecognizedVMOptions -jar "$AS_INSTALL_LIB/client/appserver-cli.jar" "$@"| Remember to turn off these logger level settings after executing a server upgrade, as this setting will affect all future executions of any Asadmin CLI commands, which will cause them to print out more information than usual. |
Zero Downtime upgrade
| This feature requires payara-upgrade-tool.jar from Payara v5.83.0 or v6.34.0 and above and assumes you are running a minimum of two SSH nodes. |
By default, upgrading Payara requires that the domain and all SSH nodes are stopped. This feature allows the upgrading of individual SSH nodes, eliminating downtime. Only upgrades in the same major version are supported 6.x to 6.x, 7.x to 7.x. Zero Downtime upgrades between 6.x and 7.x are not supported however it is possible to achieve if you can avoid restarting any of the 6.x nodes while running 7.x DAS.
Steps to upgrade:
stop the DAS
asadmin> stop-domainupgrade the domain
asadmin> upgrade-server --username example-user --distribution web --version 7.1.0 --nodes localhost-domainStop one SSH node to upgrade
asadmin> stop-node-ssh node1Upgrade one SSH node
asadmin> upgrade-server --username example-user --distribution web --version 7.1.0 --nodes node1Start the upgraded SSH node
asadmin> start-node-ssh node1Repeat the last 3 steps with the remaining SSH nodes to upgrade. Start the DAS
asadmin> start-domain
Use the _list-node-versions subcommand to help keep track of the current version of each node, including staged and rollback versions.
|
| the upgrade can cause issues if the nodes are forming a cluster with Hazelcast. When 2 versions of Payara use different versions of Hazelcast, the upgraded node will fail to start as long as nodes using the older versions are running. If the upgraded node/DAS fails to start, you may have to upgrade everything else before restarting the nodes and the DAS. Alternatively, you can avoid these issues by disabling the data grid for every nodes. Below are the known combinations causing issues: |