If you are upgrading to XL Release 7.5.x or later, you need to execute a different migration procedure. Please refer to these instructions.

Briefly, the process of upgrading XL Release is:

  1. Obtain a new version of the XL Release software and, if necessary, a new license from XebiaLabs.
  2. Read the release manual so you are aware of the new functionality and possible upgrade considerations.
  3. Stop the current version of XL Release if it is running and ensure that there are no active tasks. In a hot-standby configuration, all nodes must be stopped.
  4. Make a backup of your current repository and archive database.
  5. Create a new installation directory for the new version of XL Release (so the existing version is still available in case of problems).
  6. Extract the new XL Release software release into the new installation directory.
  7. Copy the data from the previous XL Release installation directory into the new installation directory.
  8. Start the new version of XL Release interactively so that automatic upgraders can run. In a hot-standby configuration, you must start a single node first until all upgraders are executed, and only then proceed with starting other nodes.

About upgrading

Skipping versions

It is possible to skip XL Release versions when upgrading. XL Release will sequentially apply any upgrades for the intermediate (skipped) versions. However, you may be required to take manual actions for the intermediate versions; you can find these in the version-specific upgrade notes.

Upgrading and downgrading

After you upgrade to a new version of XL Release, you cannot downgrade to an older version. If you upgrade to a release candidate (RC), alpha, or beta version, you cannot upgrade to a newer version or downgrade to an older version. Ensure that you always create a backup of your repository before you upgrade to a new version of XL Release.

Upgrading the repository

If a repository upgrade is required, XL Release will detect that it is running against an old repository and will automatically execute an upgrade when it is first started. The server log will contain extensive logging of the repository upgrade process. Save this log for future reference.

Upgrading an existing hot-standby configuration to a new version

When upgrading a hot-standby configuration or an active/active configuration, all nodes must be stopped. You can copy the configuration data from the existing nodes. The node ID in the configuration must be unique for each node. You do not have to copy the data that is shared among all the nodes (this is normally stored on NFS), but ensure that you back up the data.

You can then proceed by starting a single node in the cluster. After starting the node, wait until all upgraders are executed and the node is fully started before starting the other nodes, one by one.

Before you upgrade

Before you upgrade:

Upgrade the server

When upgrading to XL Release 7.5, a database migration must be performed using a separate Migrator tool. Please follow the instructions in Upgrade to XL Release 7.5.

To upgrade an XL Release server installation:

  1. Extract the server ZIP file. It creates an installation directory called, for example, xl-release-7.0.0-server.

  2. Shut down the XL Release server.

  3. If you are using an embedded repository, copy the repository directory and the entire archive directory from the old installation directory to the new installation directory.

  4. If you have implemented any custom plugins, copy them from the plugins directory from the previous installation directory to the new installation directory. If you are upgrading from a previous version to XL Release version 8.0.0 or later, use the plugins/__local__/ folder for your custom plugins.

  5. Copy the contents of the ext directory from the old installation directory to the new installation directory.

  6. Copy the contents of the conf directory from the previous installation to the new installation directory.

    Important:

    1. As of version 8.0.0, the plugins are placed in a different location. When upgrading from version 7.5.3 to version 8.0.0, do not copy the xlr-wrapper-linux.conf or xlr-wrapper-win.conf files. You can compare the older version against the new version of the files and modify only the necessary lines.

    2. Some versions of XL Release require a new version of the license file. Refer to XL Release licensing to see if you need a new license. You can download all of your licenses from the XebiaLabs Software Distribution site.

    3. As of version 7.5.0, the content of the script.policy file has been modified. When upgrading to XL Release version 7.5.x or later, do not overwrite the script.policy file, you must use the new version of the file.

  7. If you have changed the XL Release server startup script(s) in the bin directory, do not copy the changed script(s) to the new installation directory. Instead, manually reapply the changes to the files that were provided in the new version of XL Release.

    Note: In XL Release 4.8.x and earlier, the startup scripts are called server.sh and server.cmd. In XL Release 5.0.0 and later, they are called run.sh and run.cmd; there are also install-service.sh and install-service.cmd scripts for running XL Release as a service. If you customized server.sh or server.cmd, you must redo these changes in install-service.sh or install-service.cmd.

  8. Start the XL Release server interactively to allow automatic repository upgraders to run.

    Note: If you are running XL Release in cluster mode, you must start a single XL Release server instance and run the upgraders only on that instance. After the upgraders have sucessfully finished you can boot up the rest of the cluster.

  9. If you normally run the XL Release server as a service, shut it down and restart it as you normally do.