Upgrade Release - JVM

This topic describes the prerequisites, process and considerations for upgrading to the latest version of Release.

If you are running a Release cluster and want to upgrade your cluster to the latest Release version, see Cluster Mode.

Prerequisites

• Create a backup of your repository before you upgrade to a new version of Release. For more information, see backup Release.
• Ensure that the external database servers used to store Release data are supported. For a list of supported databases and versions, see Supported databases.
• Read the release manual for the version of Release you are upgrading to and note any changes that may apply to your situation.
• Check if there are any hotfixes installed in the hotfix directory. If hotfixes are installed, contact the Digital.ai Support before you upgrade.

Important:

• During upgrade to newer versions in Digital.ai Release, you must always upgrade to its latest patch release. To upgrade to a version that is not the latest patch release, please contact support.
• You must re-compile your custom plugins written in Java and Scala (no need to re-compile script-based plugins) when you upgrade to a newer version of Release.
• When compiling the utility libraries, you must always compile against the latest patch of the Release version that you will be using. For example, if you are on Release 10.1.x and plan to upgrade to Release 22.0.x, you must compile your utility libraries against the latest patch version available for Release 22.0.
• From Digital.ai Release 22.1, if you install the Digital.ai Release license on one of the Release nodes within a cluster, the licenses are automatically updated on all the other nodes of that cluster. For more information, see Renewal of Cluster Licenses.

Upgrade Procedure

You can use a new setup option (-previous-installation) to automate copying of files from the existing installation to the new installation from Digital.ai Release 9.5 and later. Choose which option you want to use:

• Prerequisites
• Upgrade Procedure
  • Upgrade Using the Automated File Copy Option
  • Upgrade by Manually Copying Files
• Post Upgrade Task—LDAP Authentication Changes

Upgrade Using the Automated File Copy Option

1. Log on to the Digital.ai Software Distribution Site and download a new version of the Release software and, if necessary, a new license. Customer log in is required to access this URL.

2. Ensure that there are no active tasks, then shut down Release:

   Operating system	Shortcut
   Microsoft Windows	Ctrl + c
   Unix-based systems	Ctrl + c

note

All nodes must be stopped in a hot-standby setup.

4. From the XL_RELEASE_SERVER_HOME/bin location of the new installation, run one of the following commands, depending on your operating system:

   For Unix-based systems:

   ./run.sh -setup -previous-installation `XL_RELEASE_SERVER_HOME_EXISTING`

   For Microsoft Windows:

   run.cmd -setup -previous-installation `XL_RELEASE_SERVER_HOME_EXISTING`

   The following message displays:

   Going to copy configuration from previous installation [XL_RELEASE_SERVER_HOME_EXISTING]
   Do you want to copy files to the new installation?
   Files to be copied [conf/deployit-defaults.properties, conf/logback-access.xml, conf/logback.xml, conf/logging.properties, conf/wrapper-daemon.vm, conf/xl-release-license.lic, conf/xl-release-security.xml, conf/xl-release-server.conf, conf/xl-release.conf, and conf/xl-release.policy]

5. Type yes. Your response is registered. Files listed in the conf directory will be copied the new installation.

note

The script.policy, xlr-wrapper-linux.conf, and xlr-wrapper-win.conf files will not be automatically copied, as you must use the new version of the files in the new installation. You should manually replicate changes made to the existing files to the new ones.

6. The following prompt displays:

   Do you want to copy directory [XL_RELEASE_SERVER_HOME_EXISTING/reports] to the new installation?

7. Type yes. Your response is registered. Saved audit reports stored in the reports directory will be copied to the new installation. The following prompt displays:

   Do you want to copy directory [XL_RELEASE_SERVER_HOME_EXISTING/ext] to the new installation?

8. Type yes. Your response is registered. The contents of the ext directory will be copied to the new installation.

9. The following message displays:

   Going to copy configuration from previous installation [XL_RELEASE_SERVER_HOME_EXISTING]
   User response was: [yes]. Copying files [conf/deployit-defaults.properties, conf/logback-access.xml, conf/logback.xml, conf/logging.properties, conf/wrapper-daemon.vm, conf/xl-release-license.lic, conf/xl-release-security.xml, conf/xl-release-server.conf, conf/xl-release.conf, conf/xl-release.policy]

   A status for each of the copied files in the conf directory is provided. For example:

   File [conf/xl-release.conf] was copied to the new installation.

10. The contents of the reports and ext are copied to the new installation.

11. The plugins directory is parsed. Depending on the differences between the existing plugins and the new plugins directory, the following behavior occurs:

    • If a plugin exists in the previous installation, but is not found in the new installation, you are prompted to copy it to the new installation. Type yes to copy the plugin to the new installation or no to not copy it.
    • If a plugin exists in the previous installation but a new version of it is available in the new installation, the following output is provided for each plugin: Plugin [plugin-name] has been updated [9.0.0 -> 9.5.0]. Not copying it.

12. Once all copying is successful, the following message displays:

    Copy from previous installation completed.
    Please note the following:- You should copy the database driver to the new installation manually.

13. If you are using an external database for your repository, copy your database driver to the new installation. Typically, the database driver is stored in your lib directory. For more information, see Configure the SQL repository.

14. If you changed the Release server startup script(s) in the bin directory of the source installation, do not copy the changed script(s) to the target installation. Manually reapply the changes to the files that were provided in the new version of Release.

15. Start the new version of Release interactively so that automatic upgraders can run. Open a command prompt or terminal, point to the XL_RELEASE_SERVER_HOME/bin directory, and depending on your OS platform, run one of the following commands:

    Operating system	Command
    Microsoft Windows	run.cmd
    Unix-based systems	run.sh

Upgrade by Manually Copying Files

To upgrade from Release version 9.7.x or higher to a current version, manually copying files from the old installation to the new installation:

1. Log on to the Digital.ai Software Distribution Site and download a new version of the Release software and, if necessary, a new license. Customer log in is required to access this URL.

2. Ensure that there are no active tasks, then shut down Release:

   Operating system	Shortcut
   Microsoft Windows	Ctrl + c
   Unix-based systems	Ctrl + c

note

All nodes must be stopped in a hot-standby setup.

3. If you have implemented any custom plugins, copy them from the plugins directory of the existing Release installation to the plugins directory of the target installation.

4. If you are using an external database for your repository, copy your database driver to the new installation. Typically, the database driver is stored in your lib directory as described in Configure the SQL repository.

5. Copy the contents of the ext directory from the source installation to the ext directory of the target installation.

6. Copy the contents of the conf directory from the source installation to the conf directory of the target installation.

important

Do not overwrite the script.policy, xlr-wrapper-linux.conf, and xlr-wrapper-win.conf files in the conf directory. You must use new versions of the files and manually apply any changes done to the existing files.

7. Copy the reports directory from the source installation to the same directory of the target installation or from the custom folder defined in Audit report configuration.

8. If you changed the Release server startup script(s) in the bin directory of the source installation, do not copy the changed script(s) to the target installation. Manually reapply the changes to the files that were provided in the new version of Release.

9. Start the new version of Release interactively so that automatic upgraders can run. Open a command prompt or terminal, point to the XL_RELEASE_SERVER_HOME/bin directory, and depending on your system, execute one of the following commands:

   Operating system	Command
   Microsoft Windows	run.cmd
   Unix-based systems	run.sh

Post Upgrade Task—LDAP Authentication Changes

The com.xebialabs.deployit.security.authentication.XlAuthenticationProvider class is no longer supported. As a result, if you are upgrading to 22.0.x or later and if you have been using the internalAuthenticationProvider bean in your xl-release-security.xml file, you must:

1. Remove the internalAuthenticationProvider bean.

   <bean id="internalAuthenticationProvider" class="com.xebialabs.deployit.security.authentication.XlAuthenticationProvider"/>

2. Change the <security:authentication-provider ref="internalAuthenticationProvider" /> to <security:authentication-provider ref="xlAuthenticationProvider" />.

For more information and example LDAP connection strings, see LDAP Security.