Payara Server Upgrade Tool

Can be installed manually to Payara Platform 5.20.0 and newer.

This tool can be used to upgrade a Payara Server installation to a newer version. The Upgrade Tool is bundled in Payara Server versions from version 5.24.0. It can also be obtained from Payara Nexus as the payara-upgrade-tool artifact (groupId: fish.payara.extras, artifactId: payara-upgrade-tool). If obtained from the Payara Nexus, drop the JAR artifact into your Payara Server installation under payara5/glassfish/lib/asadmin. The version 1.0 of the standalone upgrade tool can be installed into Payara Server Enterprise 5.20.0 or newer and supports upgrading to any newer Payara Server Enterprise version.

This feature is currently released as a Minimum Viable Product (MVP) and will gradually recieve additional enhancements in future Payara Enterprise releases.

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.xml. The command will also back up the old version and domains in the default location (payara5/glassfish/domains) or the location specified using the --domaindir option to allow for rolling back. The command can also be used to downgrade to an older Payara version although this is not encouraged.

Command Options

Option Type Description Default Mandatory

Option	Type	Description	Default	Mandatory
`--username`	String	The username for the Payara Nexus server.		Yes
`--version`	String	Specifies the version number of the new version of Payara to use.		Yes
`--distribution`	Enum	Specifies the distribution of Payara Server to download. This can payara, payara-web, payara-ml, or payara-web-ml.	payara	No
`--stage`	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
`--domaindir`	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.	${as-install}/domains	No

--username

String

The username for the Payara Nexus server.

Yes

--version

String

Specifies the version number of the new version of Payara to use.

Yes

--distribution

Enum

Specifies the distribution of Payara Server to download. This can payara, payara-web, payara-ml, or payara-web-ml.

payara

--stage

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

--domaindir

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.

${as-install}/domains

Example

This example upgrades a Payara Web distribution to version 5.24.1

asadmin> upgrade-server --username example-user --distribution web --version 5.24.1

Rollback 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-server command).

This command is not supported on Windows, please use the rollbackUpgrade.bat script.

Command Options

Option Type Description Default Mandatory

Option	Type	Description	Default	Mandatory
`--domaindir`	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.	${as-install}/domains	No

--domaindir

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.

${as-install}/domains

Staged Upgrades

When the upgrade-server command is used on Windows, or with the --stage option enabled, the new server install is installed next to the current one in various .new directories (e.g. payara5/glassfish/bin.new).

Apply Staged Upgrade Script

Usage: > ./payara5/glassfish/bin/applyStagedUpgrade
Aim: This script is used to apply an upgrade staged using the upgrade-server command. 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

This script should not be run repeatedly without restaging a release, doing so can leave you with no "current" installation. Checks to help prevent this will be added in a future release.

Command Options

Option Type Description Default Mandatory

Option	Type	Description	Default	Mandatory
`--domaindir`	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

--domaindir

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

Rollback Upgrade Script

Usage: > ./payara5/glassfish/bin/rollbackUpgrade
Aim: This script is used to rollback a server upgrade applied using the applyStagedUpgrade script. 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

This script should not be run repeatedly, doing so can leave you with no "current" installation. Checks to help prevent this will be added in a future release.

Command Options

Option Type Description Default Mandatory

Option	Type	Description	Default	Mandatory
`--domaindir`	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.	${as-install}/domains	No

--domaindir

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.

${as-install}/domains

Cleanup Upgrade Script

Usage: > ./payara5/glassfish/bin/cleanupUpgrade
Aim: This script is used to clean up any leftovers from a staged upgrade: any .old folders and any .new folders will be deleted.

Use of this script will prevent you from rolling back or applying a staged upgrade.

This script cannot be used to clean up upgrades from releases prior to 5.26.0, as it uses a config file to determine the directories to delete which is only generated by the upgrade-server command from 5.26.0 onwards.