How to Upgrade Payara Server 5

This is an update of the article "How to Upgrade Payara Server."

Since Payara Server is on a regular and frequent release cycle, we get a lot of questions on how to upgrade to the latest version while maintaining existing domain configurations.

The answer to the question of “how do I upgrade?” is always “it depends”, because everyone’s situation is going to be slightly different. This blog will cover some of the most straightforward ways which should apply in the majority of cases. I'm not going to cover upgrading from Payara Server 4 to 5, as that's a more complicated topic that we're currently working on to make easier - no point writing a guide for it to be outdated in two months time!

Back on topic, either of the following two methods would work in most circumstances:

• Backing up and restoring the existing configuration to a new installation
• Maintaining completely separate domain and node directories and pointing the new version to the existing directories 

Method 1: Backup and Restore

There are detailed instructions on backup and restore already in this blog post by Mike Croft, so I won’t go over all the details of it here. In summary though, this method would involve the following steps:

• Stop the running domain: asadmin stop-domain ${domainName}
• The backup-domain command will only work if the domain is not running so there would need to be an arranged period of downtime (particularly for production environments!)
• Run the backup-domain command from the existing Payara Server installation: asadmin backup-domain --backupdir ${directoryToBackupTo} ${domainName}
• Once the domain has been backed up, restore the domain to the newly downloaded Payara Server installation by running the restore-domain command from the new Payara Server installation: asadmin restore-domain --backupdir ${directoryThatYouBackedUpTo} ${domainName}

After following those steps, you should be left with a similar directory structure to the following (in my examples I've renamed the payara5 folder to better match the actual version):

/opt/payara/183/glassfish/domains/myDomain
/opt/payara/184/glassfish/domains/myDomain
/opt/payara/backups/myDomain/myDomain_2018_12_14_v00001.zip

It’s important to note that this only backs up the domain directory and its contents. Any instances you have in node directories will need to regenerated by using the --sync=full option of the start-local-instance command:

asadmin start-local-instance --sync=full myInstance

This will recreate the instance from scratch. Be aware, though, that this will not recreate things stored in the instance directory which are outside of the configuration like JMS filestores. If there is any JMS persistence which does not use a database, these must be handled manually.

Method 2: Store the Domain and Node Directories Separately

An alternative to backing up and restoring the domain & recreating the instances, would be to create the domain and node directories in a location separate to the installation. For example, if I downloaded Payara 183, created my domain, then wanted to use Payara 184, I would use the following process:

/opt/payara/183/bin/asadmin create-domain --domaindir /tmp myTempDomain
/opt/payara/184/bin/asadmin start-domain --domaindir /tmp myTempDomain

This will use the 183 installation to create a new domain, and then run it with the 184 installation.

You can do the same thing with nodes too:

/opt/payara/183/bin/asadmin create-node --nodedir /tmp myLocalNode

This methodology keeps the user configuration separate to the installation, making rolling back as simple as using the previous installation directory.

You could also take advantage of symbolic links to make life easier. When your domain directory is in a non-standard location, it means that you need to specify its location with each start/stop/restart command - annoying if you're manually typing out the commands each time. If you were to create a symbolic link to the domain directory inside the default domains directory, then you can bypass having to specify the location (particularly useful if using scripts).

You could even extend this further to create a symbolic link to whichever Payara Server installation was currently used in production, for example:

/opt/payara/live/payara5/...

This means that any rollback is as simple as stopping the server, updating a symbolic link and starting it again.

Without the use of symbolic links, things get a bit more manual (though still quite straightforward). As previously alluded to, the asadmin start-domain command has a --domaindir option which allows you to specify the location of a domain directory. So you could have a directory structure like this:

/opt/payara/183/....
/opt/payara/184/....
/opt/payara/191/....
/opt/payara/domains/myDomain
/opt/payara/nodes/myLocalNode

Then you could start your domain with whatever version of Payara you wanted:

/opt/payara/183/bin/asadmin start-domain --domaindir /opt/payara/domains myDomain
/opt/payara/184/bin/asadmin start-domain --domaindir /opt/payara/domains myDomain

Note: the --domaindir option specifies the parent directory for your domain, not the actual path to the domain: You specify the name of the domain to start separately.

You can start nodes in the same way:

/opt/payara/183/bin/asadmin start-local-instance --nodedir /opt/payara/nodes myLocalNode

So those are the two main methods of upgrading Payara Server. I'd personally recommend the second method as it's a lot less work and keeps things tidy, though you do have to plan it out ahead of time which is less convenient. As mentioned at the start of this blog, upgrading from Payara Server 4 to 5 is a bit trickier than just doing one of the above due to the differences between the two versions (such as how they do clustering), but we'll be releasing the complete "How to Upgrade from Payara Server 4 to Payara Server 5 Guide"  soon to make the transition easier.