LGTM Enterprise 1.19.2

Upgrading LGTM Enterprise

Use the upgrade.sh script supplied with each new release to upgrade your system.

You must upgrade to each version in turn. This ensures that any data migration required by each upgrade is completed successfully before you begin the upgrade to the next version. This does not include patch versions so, for example, you can upgrade from any version of 1.18 to any version of 1.19.

If you have made any manual changes to the configuration of LGTM, beyond editing the cluster configuration file, upgrading may overwrite these changes. We recommend that you back up your system before upgrading.

Before proceeding with an upgrade, read the relevant "points to note" section below. When you're ready to upgrade, run the script on the coordinator server, as described in the Upgrade process section below. When you run the script, you will be prompted to perform any required actions on remote servers.

For information about the servers referred to in this topic, see Server overview.

Points to note for upgrading from 1.18 to 1.19

After you upgrade to 1.19

All repository providers, other than those for Subversion and simple Git, must now specify a user name and password. This was strongly recommended in version 1.18 of LGTM Enterprise, but is now mandatory in 1.19. The reasons behind this change are described in security advisory SSA-2018-004.

After upgrading you must ensure that the settings for all repository providers (except Subversion and simple Git) include a valid user name and password. Check the Administration interface page for the error message: "No new commits will be analyzed for projects hosted on repository provider <name>. Please add credentials to its configuration page."

The account is used by LGTM Enterprise:

  • to determine a variety of metadata about repositories—for example, whether the repository name has changed

  • to post comments and set statuses on the pull requests of projects for which automated code review integration has been set up

For more information about repository providers, see Adding repository providers.

Points to note for upgrading from 1.17 to 1.18

After you upgrade to 1.18

After upgrading to 1.18, you should make the following changes:

  • Define accounts for repository providers—this release adds user account fields to the configuration forms for all external repository providers. Specifying user account details is optional in this release but is strongly advised, and is mandatory in 1.19. Doing so ensures that LGTM will analyze the correct code for a project following a rename or a change to the clone protocol or default branch. For more information, see Adding external repository providers.

  • Update links to LGTM Enterprise logs—the URL for job logs has changed in this release. A jobs directory has been added to the URL. Any saved links containing paths such as /admin/logs/3504840010 should be updated to add jobs after the logs directory—for example, https://<LGTM-server>/admin/logs/jobs/3504840010/stdout. A URL redirection in this release ensures that links that use the old path will still work for now. However, this redirection will be removed at the next release so it's a good idea to advise users to update any links they have saved now.

  • Make the 1.18 IDE plugins available to users—from 1.17.1 onward, the LGTM IDE plugins use a new method to authorize access to LGTM Enterprise. Users can only download alerts from LGTM 1.18 if they upgrade to at least version 1.17.1 of the plugin.

Points to note for upgrading from 1.16 to 1.17

Before you upgrade to 1.17

Before you upgrade from 1.16.x to 1.17.x, you should consider the following changes:

  • Export of business intelligence (BI) data will stop—there is a new database format for 1.17.
  • If your system is set to export LGTM data to a database, this is automatically disabled by upgrading to 1.17. After upgrading you need to prepare a database before you restart export.For more information, see Re-exporting BI data from scratch.

  • Dedicated search service is required—this was introduced in 1.16. If you originally installed 1.15 and have not enabled this service manually, you'll be prompted to do this as part of the upgrade.

After you upgrade to 1.17

After upgrading to 1.17, you may want to make the following changes:

  • Configure an empty database and re-enable BI export—if you export data from LGTM for use with BI tools, you need to make an empty database available for the new data and set up BI export in the administration pages of the application.For more information, see Re-exporting BI data from scratch.
  • Add on-demand workers—consider updating the cluster configuration to include some of the new on_demand workers. For more information, see Worker types.
  • Configure workers for Team Foundation Version Control (TFVC) analysis—if your organization stores code in TFVC repositories, you may want to configure some or all of the worker hosts to checkout code from these repositories. For more information, see Installing a command-line client for TFVC.

Points to note for upgrading from 1.15 to 1.16

Before you upgrade to 1.16

If you haven't upgrade to 1.16.x yet, you should also consider the following changes:

  • Different ports required—workers now download jobs from the job dealer service via port 8443. Previously they accessed the message queue (an instance of RabbitMQ) in the control pool directly via port 5671. Also, the web application communicates with the new search component via TCP on port 8983. You need to review your firewall and network configurations and ensure that these communication paths are available. For the full architecture diagram, see Network connections.
  • New format for the cluster configuration file—your cluster configuration file is updated automatically to the new format during the upgrade process.
  • If your system uses an SSL certificate that wasn't generated by LGTM, you should back up the certificate and key files before you upgrade. The upgrade process from 1.15 to 1.16 will overwrite your certificate with an autogenerated certificate.

  • Additional worker host requirements—JavaScript analysis is extended to include TypeScript (in .ts and .tsx files). If any analyzed project includes TypeScript files, JavaScript analysis will fail unless the additional requirements are available. For information about configuring the work pool for TypeScript analysis, see Setting up a host for JavaScript and TypeScript analysis.

After you upgrade to 1.16

After upgrading to 1.16, you should plan to:

  • Add your SSL certificate to the cluster configuration—update the cluster configuration file to specify the location of the SSL certificate files to use. This will ensure that the correct SSL certificate is automatically used and maintained through future upgrades. For more information, see the revised topic on installing SSL certificates.
  • Make the IDE plugins available to users—users can uses these to download alerts from LGTM Enterprise and display the alongside the code in their IDE. You can download the installers from the customer wiki and make them available to your users. For more information, see Making IDE plugins available to users.

Upgrade process

LGTM Enterprise will be unavailable during the upgrade. However, you don't need to take the system down yourself, the upgrade script does this for you. If LGTM's manifest.xml file was encrypted with a custom password when the system was installed, you need to know the password to upgrade the system (if you've lost the password, see Changing or resetting a manifest password).

  1. Open a command console for the coordinator server.

    The host name of the coordinator server is specified in the <LGTM releases directory>/state/lgtm-cluster-config.yml file—where <LGTM releases directory> is the directory into which the installation package for the current release was unpacked (for example, /home/adminuser/lgtm-releases/).

  2. Display the version of the currently running LGTM system by entering:

    sudo lgtm-cli version

  3. Make a note of the version number. You will use this later to confirm that the system was upgraded.

  4. Download the lgtm-<version>.tar.gz file for the new release to the coordinator server.

  5. Put this file in your LGTM releases directory alongside the state subdirectory.
  6. Unpack the file:

    tar -xvf lgtm-<version>.tar.gz

    This creates an lgtm-<version> directory.

  7. Change to the lgtm-<version>/lgtm directory.

  8. Run the upgrade.sh script in this directory:

    sudo ./upgrade.sh

    • The script expects to find a cluster configuration file called lgtm-cluster-config.yml within a state directory located in the same directory as the lgtm-<version> directory—for example, /home/adminuser/lgtm-releases/lgtm-n.nn/state/lgtm-cluster-config.yml. If the cluster configuration file is located elsewhere, give the path to this file as an argument to the script.
    • The script must be run using sudo, or as the root user.
  9. Enter the password that was used to encrypt the manifest file when LGTM Enterprise was originally installed.

  10. Follow the remaining on-screen prompts.

  11. When the upgrade is complete, check the version number again by entering:

    sudo lgtm-cli version

  12. Check the status of your license by entering:

    sudo lgtm-cli license

    If there are less than three months left before expiry, we recommend that you make a reminder to upload a new license before this date to avoid disruption to users. If the license is due to expire soon and you haven't received a new license from your LGTM support team, contact them now. New licenses can be uploaded via the administration pages, or using the license CLI action, at any time.

  13. Check the relevant After you upgrade to... section above for any additional steps you need to take to finish configuring the new version.

Housekeeping

If you use the directory structure suggested here, after upgrading you'll have the following directories:

  • lgtm-releases/lgtm-<old-version>
  • lgtm-releases/lgtm-<current-version>

The <lgtm-old-version> directory can safely be deleted. It's not used after you've upgraded. For example, you might delete the lgtm-1.17.2 directory after upgrading to LGTM Enterprise 1.18.0.

Related topicsRelated topics