New Upgrade Tool in the Payara Server Enterprise 5.24.0 Release

The January Payara Platform Enterprise Edition release (request here) includes 6 bug fixes and 1 component upgrade along with the introduction of a new CLI Upgrade Tool. You can see a more detailed overview of the fixes and improvements in the Payara Platform Enterprise Edition 5.24.0 in teRelease Notes here.

Payara Server Enterprise Upgrade Tool

Until now, upgrading from one version of Payara Server Enterprise to the latest release required a bit of manual effort and the creation of scripts. We’re happy to announce that an Upgrade Tool is included starting with Payara Server Enterprise 5.24.0 to make the process of upgrading from one version of Payara Server Enterprise to the next faster and easier. 

This first release offers a stable and tested Upgrade Tool 1.0 for Enterprise users as a minimum viable product (MVP) that can be used right away - but please note the Upgrade Tool will be further developed and improved upon to offer a richer feature set in the future Enterprise releases.

Request the Payara Enterprise Edition via this form.

(Watch 5 min demo video).

How Does the Payara Server Upgrade Tool Work?

You 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 command also asks for the Payara Nexus repository password associated with the username parameter as the tool looks in that repository for the requested target version.

More on that password later on. But first, a few words on the mechanics of how this command works. These are the steps performed by the command:

1. Download the ZIP file corresponding to the new version from the Payara Nexus repository.
2. Make a backup of the domain, similar to what the asadmin command backup-domain would do. The generated ZIP with the backup is placed in the backup folder of the domain directory.
3. Make a copy (actually it moves files) of all Payara Java code files (like modules and lib folders).
4. Unpack the downloaded ZIP file.
5. Check if the domain.xml can still be parsed with this new version of Payara Server.

So when you run the upgrade-server command, the binaries of the target version are installed, but enough safety measures (copy of files and domain) are created so that you can revert back to the previous version in case something doesn't work out as expected.

It doesn't touch the current configuration in the domain, so all configuration and deployed applications are still available after the command has run.

If your domain contains SSH nodes, those are also updated. So the tool covers many scenarios already in its first release.

The target version must be one of the Enterprise versions that are available in the Payara Nexus repository. So any Enterprise version numbered from 5.20.0 and onward is supported as the target version. Note that it doesn't need to be an upgrade in the strict sense. You can use the command to go from version 5.24.0 to 5.22.0 for example.

The Nexus password can't be specified on the command line, as that would expose the password in the bash history, and thus is requested interactively when the command starts. 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:

AS_ADMIN_NEXUSPASSWORD=<nexus-password>

you can use it like this:

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

Upgrade from Older Versions

You can use the Upgrade Tool to upgrade an older version of Payara Enterprise with the following steps: 

1. Download the Upgrade Tool from our Payara Nexus repository.
   
2. Copy the file into the glassfish/lib/asadmin/ directory of the Payara Enterprise installation that you want to upgrade.
3. Perform the upgrade as described above with the upgrade-server asadmin command.

rollback-server Command

As already mentioned, a backup is created in case something goes wrong. And there is also a corresponding command to perform the rollback.

./asadmin rollback-server

This removes the code of the current version (also for SSH nodes if you have them) and places the files created as a backup during upgrade-server command back into their original places. The backup of the domain is not restored automatically, so if you need that, you need to perform a restore-domain command manually pointing to the ZIP created during the upgrade-server process.

Some limitations of the current version:

• Windows Operating System is not supported yet.
• Domain needs to be stopped in order to perform the upgrade-server command.