Upgrade From SwaggerHub On-Premise 1.19-1.20 to 1.29.2

This guide explains how to upgrade an instance of SwaggerHub On-Premise v. 1.19.x–1.20.x to 1.29.2.

If you are running another version of SwaggerHub On-Premise, see the upgrade guide for your version:

Key points

The upgrade from SwaggerHub On-Premise 1.19/1.20 to 1.29.2 is a multi-hop upgrade through version 1.22. The last part of the upgrade is migrating the operating system to Ubuntu 20 as required to properly run the latest version of SwaggerHub On-Premise.

The upgrade path is as follows:

Version 1.19/1.20 (Ubuntu 16) --> Version 1.22 --> Version 1.29.2 (Ubuntu 16) --> Ubuntu 20 migration --> Version 1.29.2 (Ubuntu 20)

Detailed instructions and download links are provided below.

Important

Migration to Ubuntu 20 is mandatory. Ubuntu 16-based instances of SwaggerHub On-Premise are not eligible for technical support.

Important

As part of the Ubuntu 20 migration, you will need to activate your SwaggerHub On-Premise license again. You should have the license file in a prior email from SmartBear or saved locally. If you do not have a local copy of the license file, contact SmartBear Support.

Online vs offline upgrade

The upgrade can be performed online or offline depending on where the upgrades are downloaded from.

  • Online upgrade requires that your SwaggerHub VM be able to connect, either directly or through a proxy, to the following domains over HTTPS (TCP port 443):

    auth.docker.io
    hub.docker.com
    index.docker.io
    registry-1.docker.io

    Note

    These domains do not have fixed IP addresses, you need to use the domain names in your firewall rules.

  • Offline upgrade does not require outbound Internet connection from your SwaggerHub VM. Instead, you will need to download the upgrade bundle manually and point your SwaggerHub VM to the location of these files on your network. The VM must be able to access this location directly (not through a proxy).

1. Before the upgrade

Create a VM snapshot for backup

Before upgrading, create a snapshot of your SwaggerHub On-Premise instance. If you encounter problems during the upgrade, you can use the snapshot to restore the instance to the previous state.

Note: Make sure no other backup processes will be running during the upgrade timeframe as they would conflict with the upgrade activities.

Take the instance offline

Another important thing is to take your SwaggerHub On-Premise instance offline so that it is inaccessible to users. This ensures that no unexpected traffic (such as user activities or external API calls) will hit the instance during the upgrade.

2. Run pre-upgrade script

Download the pre-upgrade check script:

go.gifhttps://s3.amazonaws.com/onprem-files/pre-upgrade-check.enc

Run this script on the System tab in the Admin Center.

Important

If the check completes with no error messages, you can proceed with the upgrade. If it completes with errors, please contact your Sales representative as the errors indicate an issue with the license.

3. Upgrade to 1.22

  1. If performing an offline upgrade:

    • Download the image bundle for the offline upgrade to v. 1.22:

      go.gifhttps://s3.amazonaws.com/onprem-files/offline-images/1.22.0-38_swaggerhub-offline-images.zip

    • Unzip the bundle. You will get multiple smaller ZIP files named like this:

      activemq-<ver>.zip
      installation-service-<ver>.zip
      notifications-server-<ver>.zip
      smartbear-licensing-api-<ver>.zip
      ...

      Leave these smaller ZIP files as is, do not unzip them.

    • Put these ZIP files on a web server that is accessible from your SwaggerHub VM. All the files must be in the same folder on the web server. The URL path can be HTTP or HTTPS, and should not require authentication.

      Important

      FTP and network shares (\\server\share) are not supported.

    • Open the Admin Center.

    • Select Settings on the left.

    • In the Software update URL field, specify the URL path to the folder that contains SwaggerHub upgrades. Use the following format:

      http(s)://server(:port)/path/to/files/ 

      Important

      Your SwaggerHub VM must have access to the specified URL.

    • Click Save Changes and Restart.

  2. Download the upgrade script for upgrading to v. 1.22:

    go.gifhttps://s3.amazonaws.com/onprem-files/1.22.0-38_upgrade-swaggerhub.enc

  3. In the Admin Center, select System Upgrade on the left.

  4. Click Browse and upload the 1.22.0-38_upgrade-swaggerhub.enc file.

  5. Confirm you have backed up SwaggerHub and click Backed Up and Ready.

    Uploading the upgrade script
  6. Click Upgrade.

    Upgrading SwaggerHub
  7. Wait until the upgrade is finished. If everything is OK, you will see the following message in the Server Status area:

    Upgrade file successfully received - applying upgrade
    
    ...
    Upgrade from version 1.21 to 1.22 completed with a status of SUCCESSFUL
    
    Restarting SwaggerHub - this may take a while
    
    Upgrade successfully applied

Important

At this point, create another VM snapshot of your instance so that you can restore the working state of the system if you encounter issues during subsequent upgrades.

4. Upgrade to 1.29.1

  1. If performing an offline upgrade:

    1. Download the image bundle for the offline upgrade:

      go.gifhttps://s3.amazonaws.com/onprem-files/swaggerhub-offline-images.zip

    2. Unzip the bundle. You will get multiple smaller ZIP files named like this:

      activemq-<ver>.zip
      installation-service-<ver>.zip
      notifications-server-<ver>.zip
      smartbear-licensing-api-<ver>.zip
      ...

      Leave these smaller ZIP files as is, do not unzip them.

    3. Put these ZIP files on a web server that is accessible from your SwaggerHub VM. All the files must be in the same folder on the web server. The URL path can be HTTP or HTTPS and should not require authentication.

      Important

      FTP and network shares (\\server\share) are not supported.

    4. Open the Admin Center.

    5. Select Settings on the left.

    6. In the Software update URL field, specify the URL path to the folder that contains SwaggerHub upgrades. Use the following format:

      http(s)://server(:port)/path/to/files/ 

      Important

      Your SwaggerHub VM must have access to the specified URL.

    7. Click Save Changes and Restart.

  2. Download the upgrade script:

    go.gifhttps://s3.amazonaws.com/onprem-files/upgrade-swaggerhub.enc

  3. Open the Admin Center (if not already open).

  4. Select System Upgrade on the left.

  5. Click Browse and upload the upgrade script (.enc file).

  6. Confirm you have backed up SwaggerHub and click Backed Up and Ready.

    Uploading the upgrade script
  7. Click Upgrade.

    Upgrading SwaggerHub
  8. Wait until the upgrade is finished. If everything is OK, you will see a success message:

    Successful upgrade

At this point, the SwaggerHub application has been updated to the latest version, but the VM’s underlying operating system is still Ubuntu 16.

5. Upgrade to Ubuntu 20 (Required)

The last step is to migrate your SwaggerHub On-Premise instance to Ubuntu 20. This is required to properly run the latest version of SwaggerHub On-Premise.

Follow the instructions in this guide:

Upgrade to Ubuntu 20

Important

Migration to Ubuntu 20 is mandatory. Ubuntu 16-based instances of SwaggerHub On-Premise are not eligible for technical support.

If the upgrade fails

If any of the upgrade steps fail, you can restore your SwaggerHub instance from the latest snapshot. Follow these steps:

  1. Copy the upgrade script output or take a screenshot.

  2. Download the system logs from the System page of the Admin Center (use the Download logs button).

  3. Open a support ticket, attach the logs and provide other relevant information.

  4. Restore the system from the VM snapshot taken before the upgrade. To learn how to do that, please refer to the hypervisor documentation:

    AWS:

    Azure:

    VMware:

    VirtualBox:

The Support team will look into the logs to learn why the upgrade failed. Meanwhile, you can continue using SwaggerHub. You will be able to upgrade later when the Support team provides you with further instructions.

See Also

Publication date: