Upgrade XL Release 7.5.x and higher to current

This topic describes the prerequisites, process and considerations for upgrading XL Release version 7.5.x and higher to a current version.

Prerequisites

Starting with version 7.5.0, XL Release uses a new SQL relational database backend which replaced the JackRabbit (JCR) repository used in previous releases. This procedure assumes that you have successfully upgraded to version 7.5.x or higher and are no longer using a JCR repository.

To prepare for the upgrade:

  • Create a backup of your repository before you upgrade to a new version of XL Release. For more information, see backup XL Release.
  • Ensure that the external database servers used to store XL Release data are supported. For a list of supported databases and versions, see Supported databases.
  • Carefully read the release manual for your destination version 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 XebiaLabs support team before upgrading.

Upgrade procedures

As of version 9.5, you can use a new setup option (-previous-installation) to automate copying of files from the existing installation to the new installation. Choose which option you want to use:

Upgrade using the automated file copy option

To upgrade from XL Release version 7.5.x or higher to a current version using the -previous-installation option:

  1. Go to the XebiaLabs software distribution site and obtain a new version of the XL 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 XL Release:

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

    Note: In a hot-standby configuration, all nodes must be stopped.

  3. 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, conf/xl-release.policy, conf/xlr-wrapper-linux.conf, conf/xlr-wrapper-win.conf]
  4. Type yes. Your response is registered. Files listed in the conf directory will be copied the new installation.

    Note: The script.policy file will not be automatically copied, as you must use the new version of the file in the new installation. You should manually replicate changes made to the existing file to the new one.

  5. The following prompt displays:

    Do you want to copy directory [XL_RELEASE_SERVER_HOME_EXISTING/reports] to the new installation?
  6. 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?
  7. Type yes. Your response is registered. The contents of the ext directory will be copied to the new installation.

  8. 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, conf/xlr-wrapper-linux.conf, conf/xlr-wrapper-win.conf]

    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.
  9. The contents of the reports and ext are copied to the new installation.

  10. 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.
  11. 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.
  12. 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.

  13. If you changed the XL 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 XL Release.

  14. Start the new version of XL 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

Upgrade by manually copying files

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

  1. Go to the XebiaLabs software distribution site and obtain a new version of the XL 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 XL Release:

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

    Note: In a hot-standby configuration, all nodes must be stopped.

  3. If you have implemented any custom plugins, copy them from the plugins directory of the source XL 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.

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

    Important: When upgrading XL Release, do not overwrite the script.policy file. You must use the new version of the file.

  8. If you changed the XL 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 XL Release.

  9. Start the new version of XL 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