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.

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 my recent blog post, so I won’t go over all the details of it here.

In summary, the method would involve the following steps:

• Stop the running domain
  • The asadmin backup-domain subcommand will only work if the domain is not running so, if this method is chosen for a production system, there would need to be an arranged period of downtime
• Run asadmin backup-domain from the existing Payara Server installation
• Once the domain has been backed up, restore the domain to the newly downloaded Payara Server installation by running asadmin restore-domain from the bin directory of the new Payara Server installation

After following those steps, you should be left with a similar directory structure to the following:

/opt/payara/161/payara41/glassfish/domains/myDomain
/opt/payara/162/payara41/glassfish/domains/myDomain
/opt/payara/backups/myDomain/myDomain_2016_05_27_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 subcommand:

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: Move the domain directory and node directories

An alternative to backing up and restoring the domain, then 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 154, created my domain, then wanted to use Payara 162, I would use the following process:

➜  /opt/payara/payara-4.1.154/payara41 bin/asadmin create-domain --domaindir /tmp myTempDomain
➜  /opt/payara/payara-4.1.154/payara41 cd ../../payara-4.1.162/payara41 
➜  /opt/payara/payara-4.1.162/payara41 bin/asadmin start-domain --domaindir /tmp myTempDomain

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

You can do the same thing with nodes too:

➜  /opt/payara/payara-4.1.154/payara41 bin/asadmin create-node --nodedir /tmp myLocalNode

In this way, the user configuration is always kept separate to the installation, and rollback is as simple as using the previous installation directory.

If you are using Payara Server on Linux, you could 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. If you were to create a symbolic link to the domain directory inside the default domains directory, then all of your existing scripts will carry on as normal.

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/payara41/....

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). The asadmin start-domain subcommand 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/154/payara41/....
/opt/payara/161/payara41/....
/opt/payara/162/payara41/....
/opt/payara/domains/myDomain
/opt/payara/nodes/myLocalNode

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

/opt/payara/154/payara41/bin/asadmin start-domain --domaindir /opt/payara/domains myDomain
      ...or:
/opt/payara/162/payara41/bin/asadmin start-domain --domaindir /opt/payara/domains myDomain

Note: the --domaindir option specifies the parent directory for your domain...so where you would store all of your domains. There is then a space and then the name of the domain you want to start - domain1 is still the default

You can start nodes in the same way:

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

So those are the two main methods of upgrading Payara Server. Personally, I find the second method is a lot less work and, as a support engineer who needs to maintain lots of versions concurrently, that is the way I’ve found the easiest. I’ve even created a Payara Server within Netbeans which points to the “live” symlink, meaning I can always quickly deploy and test applications on the latest version without changing any configuration.