Upgrade Tool V1.3 in Payara Server Enterprise

Photo of Debbie Hoffman by Debbie Hoffman

In January 2021 we introduced the Upgrade Tool as a minimally viable product (MVP) for Payara Server Enterprise users to make the process of upgrading from one version of Payara Server Enterprise to the next faster and easier.  Each release since then has offered improvements to the tool. 

In this April Release, Upgrade Tool V1.3 is no longer an MVP and is a full feature of Payara Server Enterprise. Upgrade Tool V1.3 adds the ability to specify a local distribution of Payara Server to upgrade to for users with no internet access or access to Nexus. 

Request the Payara Platform Enterprise 5.27.0 release  here.

Payara Server Enterprise Upgrade Tool

Until the January Payara Enterprise 5.24.0 release, upgrading from one version of Payara Server Enterprise to the latest release required a bit of manual effort and the creation of scripts. Starting with Payara Server Enterprise 5.24.0 the process of upgrading from one version of Payara Server Enterprise to the next became faster and easier. 

The traditional way of upgrading the Payara Server involves downloading the updated version of the product, unzipping it, and copy the domain configuration through the backup and restore commands, for example.  In the case of Payara Community, you need to execute the Asadmin CLI commands to configure the environment again, as there is no upgrade guarantee of the domain.

With this Upgrade tool, all these steps are no longer required and a single Asadmin CLI command is sufficient to upgrade to another version. And you have the added benefit of going back to the previous version by executing a single command in case there is an unexpected issue.

Upgrade Tool 1.0 was offered in January 2020 as a minimum viable product (MVP) that can be used right away - but we've continued to develop the feature in each of our releases since then.

How Does the Payara Server Upgrade Tool Work?

The Upgrade Tool can update your Payara Server installation from one version to another using an asadmin command.

./asadmin upgrade-server --username <nexus_username> --version <target_version>

The password to access the Nexus repository will be asked interactively on the command line when the command is launched. An alternative is that the password is specified in a password file and this file is referenced on the command line.

Suppose you have a file passwd with the content:


you can use it like this:

./asadmin upgrade-server .... --passwordfile passwd

When performing the upgrade on a Windows machine, an additional step is required due to the file locking mechanisms of the Operating System.  A running program cannot be moved and thus a 2-step process is required.  The asadmin CLI command prepares the new version and after the command finishes, the following script needs to be executed.


This will activate the prepared staged environment.  You can use this 2-step process also in other environments if you like, in that case, specify the --stage option of the upgrade-server command.

./asadmin upgrade-server .... --stage true

In the release of this month, we have added support for using a pre-downloaded version of the Payara binaries.  Some customers are running Payara Server on an environment that doesn't have access to our Nexus Server. When the new version is downloaded manually and placed on the server, the location of the zip file can be specified through the --usedownloaded option.

./asadmin upgrade-server  --usedownloaded /path/to/payara/payara-5.27.0.zip

In the above case, the --username and --version are ignored if they are specified.

The first release of the Upgrade Tool required that you connect to the Payara Nexus repository when upgrading. Now, the Upgrade Tool will also allow you to upgrade to a local distribution of Payara Server which is ideal for users with no internet access or access to Nexus. 

Going Back to the Previously Installed Version

In case an issue is detected with the upgraded version of Payara Server, you can go easily back to the previously installed version using the rollback-server command

./asadmin rollback-server

In case you are running on a Windows machine, you need to use the following rollback script.


Upgrade Tool V1.1 Improvements 

In February, Upgrade Tool V1.1 added the ability to restore the domain configuration from the backup using the rollback-server command. 

Upgrade Tool V1.2 Improvements

In March, the Upgrade Tool was updated to make it possible to use the tool with Windows.

Upgrade Tool V1.3 Improvements

In April, the option to use a pre-downloaded binary is added to the Upgrade Tool.

You can request Payara Platform Enterprise 5.27.0 here.

And the documentation about the Upgrade Tool is on our documentation site.