Prerequisites

Overview

Zenhub Enterprise (ZHE) 2.42, the latest release that also includes Zenhub Roadmaps, includes new software binaries that are not compatible with the legacy OS Ubuntu 14.04 (Trusty). While Zenhub has been releasing for Ubuntu 16.04 (Xenial) for some time now, we understand that some customers who have been with us since the Ubuntu 14.04 days are still on this platform. Moving forward as of ZHE 2.42 onward, Ubuntu 14.04 will not be supported.


To upgrade to Ubuntu 16.04 (and then ZHE 2.42), please follow the steps listed below:

Note: this is not an exhaustive list of steps. Please see the detailed steps below for further instruction.

  1. Deploy a new Ubuntu 16.04 ZHE appliance that is running your current version of ZHE
  2. Take a backup of your existing appliance
  3. (For customers on ZHE 2.39 only) Upload the new zhe-raptor script
  4. Restore your backup to the new appliance
  5. Upgrade to ZHE 2.42

Pre-upgrade steps

  1. Schedule a maintenance window with your users to do the upgrade
  2. Review the entire list of upgrade steps below
    1. You may want to complete the first section of the upgrade steps, Deploy a new Ubuntu 16.04 ZHE Appliance, before your maintenance window.

Upgrade steps

Deploy a new Ubuntu 16.04 ZHE Appliance

(For AWS Users)

  1. For AWS Users, go to AMIs in EC2 and enter the search shown in the image below. You should be able to see Zenhub Enterprise AMIs that have been shared with your AWS account. Ensure you are in the same AWS Region where your existing Zenhub Enterprise appliance is deployed.

    https://s3-us-west-2.amazonaws.com/secure.notion-static.com/182d1d95-816d-4864-96bf-54719d7305c8/Screen_Shot_2020-05-05_at_10.38.13_AM.png

  2. Deploy the Zenhub Enterprise <version> (Ubuntu 16.04) AMI, where <version> matches your current version of ZenHub Enterprise, using the same VPC, subnet, and security groups as your original appliance.

    1. For more detailed steps of how to deploy ZenHub Enterprise, see the installation guides: 2.34, 2.36, 2.39.

  3. Navigate to the setup page of the new appliance and set up the following configuration:

    1. Create an admin password
    2. Upload your Zenhub Enterprise license
    3. Add your SSH public key (this will be used for restoring the backup) and click the button Add key. Leave the rest of the configuration for now (this will be restored by the backup)

(For VMware Users)

  1. Refer to the VMware installation guide for your current version to download the Ubuntu 16.04 OVA: 2.34, 2.36, 2.39
  2. Deploy the OVA as a new virtual machine
    1. Note: If you do not have the hardware resources to deploy this in parallel with your existing virtual machine, proceed to the next section first to take a backup, then stop the existing machine
  3. Navigate to the setup page of the new appliance and set up the following configuration:
    1. Create an admin password
    2. Upload your Zenhub Enterprise license
    3. Add your SSH public key (this will be used for restoring the backup) and click the button Add key. Leave the rest of the configuration for now (this will be restored by the backup)

Take a backup of your existing Ubuntu 14.04 ZHE Appliance

  1. Enable maintenance mode on your Ubuntu 14.04 ZHE appliance
    1. sudo zhe-maintenance enable
  2. Follow the backup guide to take a backup of your Ubuntu 14.04 ZHE Appliance

(Customers on ZHE 2.39 only) Replace the zhe-raptor script

For customers on ZHE 2.39, you will need to replace the zhe-raptor script on the new appliance to avoid a problem with Docker during the restoration of your backup.

  1. SSH to your new Ubuntu 16.04 appliance using the SSH key you added
  2. Download the new zhe-raptor script
    1. curl -O https://zenhub.s3.amazonaws.com/enterprise/enterprise-patches/2.39/zhe-raptor.sh
  3. Make the script executable
    1. chmod +x /home/admin/zhe-raptor.sh
  4. Make a copy of your existing script for recording purposes
    1. sudo mv /data/zhe-utils/zhe-raptor.sh /data/zhe-utils/zhe-raptor.sh.bak
  5. Move the new script into place
    1. sudo mv /home/admin/zhe-raptor.sh /data/zhe-utils/zhe-raptor.sh

Restore the 14.04 backup to the 16.04 appliance

  1. Follow the backup/restore guide to restore your 14.04 backup to your 16.04 appliance

  2. Your 16.04 appliance should now have all of the data from your 14.04 appliance and be configured with the same hostname, DNS servers, NTP servers, and GitHub connection settings.

  3. Go to the setup page of your 16.04 appliance and confirm that all of the settings match your 14.04 appliance.

  4. At this point, your new appliance should be fully configured and running Zenhub.

Resolve any outstanding DNS/hostname configuration

When you performed the restoration, it changes the hostname of the new appliance to that of the old appliance. Since the old appliance is still running, they may interfere with each other if GitHub Enterprise or your users have line of sight to both appliances.

The next steps depend on how your network is configured.

Now would be the time to update the DNS record for Zenhub Enterprise to match the IP address of the new appliance, and/or shut down the old virtual machine.

Test the new appliance

  1. Once the restore is complete and DNS/hostname configuration is updated, it's time to test! Can you load the Zenhub webapp and see all of your Workspaces and data?
  2. If so, congratulations! You can now upgrade to Zenhub Enterprise 2.42.
  3. If not, please proceed to the backout plan and collect the support bundle with sudo zhe-support from the appliance and send it to enterprise@zenhub.com.

Backout Plan

If the restore fails, or if there are other issues and the upgrade must be backed out, simply start the old 14.04 appliance if it wasn't already running and disable maintenance mode sudo zhe-maintenance disable if it is still in maintenance mode.