Upgrade Deploy 8.0.x and higher to current
This topic describes the prerequisites, considerations and process for upgrading Deploy from version 8.0 or higher to the current version.
Prerequisites
Before you upgrade:
- Carefully read the release manual and note any changes that may apply to your situation.
- Review any files that you have customized, such as
conf/deployit-security.xml
orconf/logback.xml
. You will need to redo these changes in the new files. - Check whether there are any hotfixes installed in the
hotfix
directory. If hotfixes are installed, contact the Digital.ai Support team before upgrading.
Upgrade overview
Upgrading Deploy includes the following tasks:
- Obtain a new version of the Deploy software and, if necessary, a new license from XebiaLabs.
- Read the release manual so you are aware of the new functionality and possible upgrade considerations.
- Stop the current version of Deploy if it is running and ensure that there are no active tasks.
- Extract the new Deploy release into a directory for the new version of Deploy (so the old version will still be available in case of problems).
- Copy data from the old installation directory to the new installation directory.
- Redo custom changes that you made to configuration files and startup scripts.
- Start the new version of Deploy so that automatic upgraders can run.
You can find release notes for each version here: Release notes.
Considerations
Review the following considerations before upgrading.
Upgrading from a version earlier than 8.0.x
If you are upgrading from a version of prior to Deploy 8.0.x, the data stored in Deploy must be converted from the JackRabbit (JCR) format to SQL format. In this scenario, upgrade using the procedure described in Migrate Deploy data storage to an SQL database.
Masters, workers and satellite
You can use the procedures in this topic to upgrade Deploy masters, workers and satellites that exist in a typical production environment. Make sure that all masters, workers and satellites are upgraded to share the same version.
Upgrading and downgrading
After you upgrade to a new version of Deploy, 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 Deploy.
Skipping versions
When upgrading, you can skip Deploy versions. Deploy will sequentially apply upgrades for the intermediate versions. However, you may be required to take manual actions for the intermediate versions; you can find these in the release manual.
Upgrading the repository
If a repository upgrade is required, Deploy 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.
Important: New functionality in Deploy or plugins may require database schema changes. As a result, the application requires additional privileges to perform the changes to the schema. These privileges include:
- ALTER, CREATE, and DROP privileges for tables, views, indexes, and triggers
- REFERENCES privilege (if applicable)
- INSERT, SELECT, UPDATE, and DELETE privileges (like in a normal operation)
Upgrading plugins
A plugin version is related to the version of Deploy with which it is compatible. For example, the Kubernetes plugin version 9.5.0 requires Deploy 9.5.0 or later, unless otherwise specified in the release manual.
The new version of Deploy may not be compatible with the current version of your plugins. If this is the case, you must download and install updated versions of the plugins. Upgrading to a new plugin version may require you to take manual actions; you can find these in the release manual.
Deploy will not prevent you from downgrading a plugin to an older version, but doing so is not recommended.
Deprecations
Each new version may deprecate some functionality or features in favor of newer ways of working. If functionality is marked as deprecated for a specific version, the old functionality is still available (so you can still upgrade hassle-free), but it will be removed in the next version.
The release manual may include information about how to migrate to the new way of working. This gives you the time and opportunity to migrate to the new situation before upgrading to a still newer version that will no longer have the old functionality. Be sure to read the deprecation information for each release you’re upgrading to, so you know what will change in upcoming versions.
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 Deploy version 8.0.x or higher to a current version using the -previous-installation
option:
- Extract the server archive for the new version of Deploy. It creates an installation directory called, for example,
xl-deploy-9.5.0-server
. -
Log in to your existing Deploy instance as an administrator, click Explorer, expand Monitoring, double click Deployment tasks, and select All Tasks.
- If there are any tasks with a state of Failing or Failed, cancel them.
- If there are any tasks with a state of Executing, wait for them to complete or cancel them.
- To open a task from Monitoring, double-click it.
- Ensure that no new tasks are started by enabling maintenance mode.
-
Shut down the existing Deploy server.
Note: If you are running the Deploy server as a service and you want to use it after the upgrade, you must uninstall the existing Deploy service. You must re-install the Deploy as a service from the new location after the upgrade.
-
From the
XL_DEPLOY_SERVER_HOME/bin
location of the new installation (e.g.,xl-deploy-9.5.0-server/bin
), run one of the following commands, depending on your operating system:For Unix-based systems:
./run.sh -setup -previous-installation `XL_DEPLOY_SERVER_HOME_EXISTING`
For Microsoft Windows:
run.cmd -setup -previous-installation `XL_DEPLOY_SERVER_HOME_EXISTING`
Note:
XL_DEPLOY_SERVER_HOME_EXISTING
is the path of the old installation directory. For example: For Unix-based systems:"/home/.../xl-deploy-8.5.0-server"
For Microsoft Windows:"C:......\xl-deploy-8.5.0-server"
The following message displays:
Going to copy configuration from previous installation [XL_DEPLOY_SERVER_HOME_EXISTING]. Do you want to copy files to the new installation? Files to be copied [conf/deployit-license.lic, conf/deployit.conf, conf/deployit-defaults.properties, conf/repository-keystore.jceks]
-
Type
yes
. Your response is registered. Files listed in theconf
directory will be copied the new installation. The following prompt displays:Do you want to copy directory [XL_DEPLOY_SERVER_HOME_EXISTING/ext] to the new installation?
- Type
yes
. Your response is registered. The contents of theext
directory will be copied to the new installation. -
The
plugins
directory is parsed. Depending on the differences between the existingplugins
and the newplugins
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 orno
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.
- 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
-
The following message displays:
Going to copy configuration from previous installation [XL_DEPLOY_SERVER_HOME_EXISTING] User response was: [yes]. Copying files [conf/deployit-license.lic, conf/deployit.conf, conf/deployit-defaults.properties, conf/repository-keystore.jceks].
A status for each of the copied files in the
conf
directory is provided. For example:File [conf/deployit.conf] was copied to the new installation.
- The contents of the
ext
directory are copied to the new installation. -
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. - You should adapt and copy [xl-deploy.conf] to the new installation manually.
- Copy the
repository
directory from the old installation directory to the new installation directory. - Assuming 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. - If you have changed other files in the
conf
directory, such asxl-deploy.conf
,deployit-security.xml
orlogback.xml
, do not copy the changed files to the new installation directory. Instead, manually reapply the changes to the files that were provided in the new version of Deploy. - Copy the contents of the
importablePackages
directory from the old installation directory to the new installation directory. - If you have changed the Deploy 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 Deploy. Note: There are alsoinstall-service.sh
andinstall-service.cmd
scripts for running Deploy as a service. If you customized therun
orinstall-service
scripts in the old installation, you must redo these changes in theinstall-service
script in the new installation. - Start the Deploy server interactively (instead of starting as a background process or service) to allow automatic repository upgraders to run. Note: The upgrade process may ask questions or ask for confirmation.
- If you normally run the Deploy server as a service, shut it down and restart it as you normally do.
Upgrade by manually copying files
To upgrade from Deploy version 8.0.x or higher to a current version, manually copying files from the old installation to the new installation:
- Extract the server archive for the new version of Deploy. It creates an installation directory called, for example,
xl-deploy-9.5.0-server
. -
Log in to your existing Deploy instance as an administrator, click Explorer, expand Monitoring, double click Deployment tasks, and select All Tasks.
- If there are any tasks with a state of Failing or Failed, cancel them.
- If there are any tasks with a state of Executing, wait for them to complete or cancel them.
- To open a task from Monitoring, double-click it.
- Ensure that no new tasks are started by enabling maintenance mode.
- Shut down the Deploy server. Note: If you are running the Deploy server as a service and you want to use it after the upgrade, you must uninstall the existing Deploy service. You must re-install the Deploy as a service from the new location after the upgrade.
- Copy the
repository
directory from the old installation directory to the new installation directory. - Copy the contents of the
importablePackages
directory from the old installation directory to the new installation directory. -
Copy the contents of the
plugins
directory from the old installation directory to the new installation directory (unless new versions of your plugins were provided with the new Deploy version).Tip: Check the release manual for information about plugin incompatibility.
- Copy the contents of the
ext
directory from the old installation directory to the new installation directory. - If you added libraries to Deploy’s
lib
directory (such as database drivers), copy the additional libraries from the old installation directory to the new installation directory. -
Verify that libraries in the
lib
directory do not also appear in theplugins
directory, even if their versions are different.For example, if
lib
containsguava-27.1.jar
, then theplugins
directory should not contain anyguava-x.x.jar
file (such asguava-20.0.jar
). In this case, you must remove the library from theplugins
directory. - Copy the
conf/deployit-license.lic
file from the old installation directory to the new installation directory. -
Copy the following files from existing
conf
directory to the new installation’sconf
directory:deployit.conf
deployit-defaults.properties
repository-keystore.jceks
file (if it exists) from the old installation directory to the new installation directory.
- If you have changed other files in the
conf
directory, such asxl-deploy.conf
,deployit-security.xml
orlogback.xml
, do not copy the changed files to the new installation directory. Instead, manually reapply the changes to the files that were provided in the new version of Deploy. - If you have changed the Deploy 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 Deploy. Note: There are alsoinstall-service.sh
andinstall-service.cmd
scripts for running Deploy as a service. If you customized therun
orinstall-service
scripts in the old installation, you must redo these changes in theinstall-service
script in the new installation. - Start the Deploy server interactively (instead of starting as a background process or service) to allow automatic repository upgraders to run. Note: The upgrade process may ask questions or ask for confirmation.
- If you normally run the Deploy server as a service, shut it down and restart it as you normally do.
Upgrade the Deploy CLI
To upgrade a Deploy command-line interface (CLI) installation:
- Create a directory for the new Deploy CLI installation, including the new Deploy CLI version number in the directory name.
- Extract the CLI archive in this directory.
- Copy the contents of the
plugins
directory from the previous installation to the new installation directory (unless new versions of your plugins were provided with the new Deploy version). -
Copy the contents of the
ext
directory from the previous installation to the new installation directory.Note: Do not copy the content of the
hotfix
directory unless instructed to do so (because hotfixes are version-specific). - If you have made any changes to the Deploy CLI startup scripts (
cli.sh
orcli.cmd
), copy these from thebin
directory in the previous installation to the new installation directory.