Upgrade From SwaggerHub On-Premise 1.21 to 1.29.2
This guide explains how to upgrade an instance of SwaggerHub On-Premise v. 1.21.0-34 (this specific version) 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.21 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.21 (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 scripts
Download the pre-upgrade check script:
https://s3.amazonaws.com/onprem-files/pre-upgrade-check.encRun 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.
Download this maintenance script:
https://onprem-files.s3.amazonaws.com/1.21_to_1.22_pre_upgrade.encRun this script on the System tab in the Admin Center.
3. Upgrade to 1.22
If performing an offline upgrade:
Download the image bundle for the offline upgrade to v. 1.22:
https://s3.amazonaws.com/onprem-files/offline-images/1.22.0-38_swaggerhub-offline-images.zipUnzip 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.
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.
Download the upgrade script for upgrading to v. 1.22:
https://s3.amazonaws.com/onprem-files/1.22.0-38_upgrade-swaggerhub.encIn the Admin Center, select System Upgrade on the left.
Click Browse and upload the
1.22.0-38_upgrade-swaggerhub.encfile.Confirm you have backed up SwaggerHub and click Backed Up and Ready.
Click Upgrade.
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.2
If performing an offline upgrade:
Download the image bundle for the offline upgrade:
https://s3.amazonaws.com/onprem-files/swaggerhub-offline-images.zipUnzip 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.
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.
Download the upgrade script:
https://s3.amazonaws.com/onprem-files/upgrade-swaggerhub.encOpen the Admin Center (if not already open).
Select System Upgrade on the left.
Click Browse and upload the upgrade script (.enc file).
Confirm you have backed up SwaggerHub and click Backed Up and Ready.
Click Upgrade.
Wait until the upgrade is finished. If everything is OK, you will see a success message:
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:
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:
Copy the upgrade script output or take a screenshot.
Download the system logs from the System page of the Admin Center (use the Download logs button).
Open a support ticket, attach the logs and provide other relevant information.
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.