This guide describes the procedure for upgrading an existing SwaggerHub On-Premise instance to a later version. Please go through the pre-upgrade checklist and requirements before upgrading. To learn about new features in the current and previous releases of SwaggerHub, see the Release Notes.

Before you upgrade

Important: To upgrade to v. 1.26, you must be running v. 1.22.0-38 or later. If you use an earlier version, contact your sales representative for assistance with the upgrade process.

Requirements

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 (introduced in v. 1.18.1) does not require outbound Internet connection from your SwaggerHub VM. Instead, you will need to download the upgrades manually by a SmartBear-supplied link 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).

Pre-upgrade maintenance scripts

Before upgrading your SwaggerHub On-Premise instance, make sure to run the following maintenance scripts. These scripts need to be run on the System page of the Admin Center, as explained here.

https://s3.amazonaws.com/onprem-files/pre-upgrade-check.enc
If upgrading from v. 1.21.0-34 (this specific version) to 1.22.0-38:

https://s3.amazonaws.com/onprem-files/1.21_to_1.22_pre_upgrade.enc

Note: Upon completion, this script will restart the system. Please wait for the restart to complete before you proceed with the actual upgrade.

Pre-upgrade checklist

Contact SmartBear Support to get the following files:
- an upgrade script for your SwaggerHub instance
- (if you require an offline upgrade) a download link for SwaggerHub upgrades
Important: Back up your SwaggerHub instance:
- Create a VM snapshot.
- (Optional) Back up the SwaggerHub database and download the backup to your computer or to a remote location.
If you run SwaggerHub in AWS, make sure you have access to the AWS console at https://console.aws.amazon.com/ec2.
If you run SwaggerHub in Azure, make sure you have access to the Azure Management Portal at https://portal.azure.com.
Review the upgrade instructions below to understand the process. If you have questions about any steps, discuss them with SmartBear Support.
Inform your users about the planned upgrade time frame.

Considerations for upgrading from version 1.18.0 or earlier

VirtualBox and VMware users who created a SwaggerHub VM using v. 1.18.0 or an earlier version need to increase the disk space for disk 5 before the upgrade. This should be done to ensure the upgrade scripts will work properly. Refer to the following articles for step-by-step instructions:

Upgrade procedure

Note:

The offline upgrade is supported starting from v. 1.18.1.

If performing an offline upgrade:
- Download the swaggerhub-offline-images.zip bundle by the link you were given.
- 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.
  
  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 http(s)://server(:port)/path/to/files/ format.
  
  Your SwaggerHub VM must have access to the specified URL.
- If you use SwaggerHub On-Premise 1.19.2 or later, click Save Changes and Restart.
  
  In earlier versions, click Save Changes, then switch to the System page and click Restart SwaggerHub.
- Wait a few minutes for the system to restart completely.
Open the Admin Center (if not already open).
Select System Upgrade on the left.
Click Browse and upload the upgrade script (.enc file) you got from SmartBear.
Confirm you have backed up SwaggerHub and click Backed Up and Ready.

Click the image to enlarge it.
Click Upgrade.

Click the image to enlarge it.
Wait until the upgrade is finished. If everything is OK, you will see the following message:

Click the image to enlarge it.

If the upgrade fails

If the upgrade fails, you can restore your SwaggerHub instance from the backup. 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:
- Restoring an Amazon EBS Volume from a Snapshot
- How do I launch an EC2 instance from a custom Amazon Machine Image (AMI)?
Azure:
- Restore Azure VMs
VMware:
- Restoring Snapshots
VirtualBox:
- Importing and exporting virtual machines

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.

Upgrading SwaggerHub On-Premise