Migrating your Developer Portal OVAs from Ubuntu V16.04 to Ubuntu V18.04

It is strongly recommended that you migrate your Developer Portal to Ubuntu V18.04 because support for Ubuntu V16.04 is being withdrawn in March 2021. To migrate your Developer Portal OVAs from Ubuntu V16.04 to Ubuntu V18.04, you need to perform a backup and restore method of migration. This method involves backing up your current Ubuntu V16.04 Developer Portal content, standing up new OVAs on Ubuntu V18.04, and then restoring the Developer Portal content onto the new OVAs.

Before you begin

Ubuntu V18.04 is available from Developer Portal version 5.0.8.10 iFix 1, for example 5.0.8.10-iFix-APConnect-Portal-Ubuntu18-20201217-2319.ova. Note that the version number and time stamp will vary depending on the version that you download.

Ensure that your Developer Portal is at version 5.0.8.8 or later. This release and all later versions are available from IBM® Support Fix Central: https://www.ibm.com/support/fixcentral/swg/selectFixes?parent=ibm~WebSphere&product=ibm/WebSphere/IBM+API+Connect&release=5.0.8.8&platform=All&function=all.

For upgrade instructions, see Applying an IBM fix pack and upgrading all sites to use the new distribution.

Also, download the latest Developer Portal OVA file (minimum version 5.0.8.10 iFix 1), which will contain Ubuntu V18.04, and will be used to deploy onto the new OVAs.

Pre-migration checks

Verify that your Ubuntu V16.04 portal servers are at version 5.0.8.8 or later, by completing the following checks:

Run the status command, and confirm that everything is reported as up and that no errors are shown. The command returns the following values:
```
System version: 7.x-5.0.8.8-yyyymmdd-hhmm
```
The date and time of the System version should match that of the upgrade file that was installed.
```
Distribution version: 7.x-5.0.8.8-yyyymmdd-hhmm
```
The date in the Distribution version, but not the time, should be no more than one day older than the upgrade file that was installed. Make a note of this value.
Run the command list_sites -p. Confirm that all sites are listed as INSTALLED, and that all have the platform setting that matches the Distribution version from step 1; for example, platform_devportal_7_x_5_0_8_8_yyyymmdd-hhmm. If any sites are listed as being on an earlier platform, they should be upgraded to match the Distribution version, by using the upgrade_devportal command.
Run the command check_site -a and confirm that all sites are up and are returning 200 HTTP codes.

If you encounter any problems when you do the pre-migration checks, do not proceed with the migration. Instead, open a support request and state that your Ubuntu V16.04 nodes failed the pre-migration checks, and attach the output file from the generate_logs command.

About this task

The Linux® distribution for the Developer Portal OVA moved from an Ubuntu V16.04 base to an Ubuntu V18.04 base within Developer Portal V5.0.8.10 iFix 1. Support for the Ubuntu V16.04 OVA is being withdrawn in March 2021. The following steps describe how to backup your Developer Portal platform, and then to standup new OVAs on which to restore your Developer Portal content. After the Developer Portal is migrated to Ubuntu V18.04, future upgrades can be performed by using the standard instructions for applying an IBM fix pack, see Applying an IBM fix pack and upgrading all sites to use the new distribution.

Procedure

Complete the following steps for both single-node and multi-node migrations.

Ensure that you complete the pre-migration checks described previously.
Back up your entire Developer Portal by following the instructions in Backing up your whole Developer Portal. In a multi-node environment, you need to back up the Developer Portal only on one node.

Important: You must save your backup to a remote server, so that the backup can be restored onto the new Ubuntu V18.04 OVA.
Optional: If you want to keep the hostname details of your old OVAs, for each OVA run the following command and make a note of each hostname:
```
hostname -f
```
Then, before restoring the Developer Portal onto each OVA, you can use the returned values to set the hostname for each new Ubuntu V18.04 OVA.
You must now shut down all of the legacy Ubuntu V16.04 OVAs before continuing with the restore.
Deploy the Ubuntu V18.04 portal OVAs as described in Deploying the Developer Portal OVA file. You must deploy as many Ubuntu V18.04 OVAs as there are Ubuntu V16.04 OVAs in your Developer Portal cluster.

Warning: Upon deployment, if you are experiencing trouble with a static IP configuration where your machine is not being assigned the given static IP address, then this can be resolved by flushing the DNS cache and restarting your Developer Portal Machine.
On the new Ubuntu V18.04 OVA, download the backup from the remote server that you created earlier. In a multi-node deployment, download the backup onto one machine only.
On each new OVA, set the hostname of the machine by running the following command:
```
set_hostname hostname
```
Where hostname is either the value that you saved from the equivalent Ubuntu V16.04 node, or a new hostname for this upgraded machine.
If you are using a static IP configuration for each Developer Portal machine, then ensure that the IP details are correctly set before you continue. If you are using a DHCP IP configuration, ensure that your DHCP server correctly allocated an IP address for each Developer Portal Machine. If the IP address is incorrect, you might find that your Developer Portal sites are restored, but they are not accessible by the API Manager or through a web browser. For more information, see Installing the Developer Portal.
If you didn't use the same hostname details for the new OVAs, and you're using a load balancer to manage traffic between the Cloud Manager and the Developer Portal, then you must ensure that your load balancer points to the new set of hostnames. You can obtain the hostnames for each of the new OVAs by running hostname -f.
If you're not using a load balancer, then ensure that the Cloud Manager configuration for the Developer Portal is changed to the new hostname. For detailed instructions, see Step 2 in Installing the Developer Portal.
Note:
For Developer Portal version 5.0.8.10-iFix or later, on a Ubuntu18.04 base, if you did not change your Developer Portal IP address, but now want to, ensure that you sync your new IP address with the API Manager. Use the command:
```
resubscribe_webhooks
```
If you do not run this command, you might not receive webhooks from the API manager as its configuration is set to be the old Developer Portal IP address.
Restore the Developer Portal by running the following command on the new Ubuntu V18.04 OVA. In a multi-node deployment, run the command on the machine that you downloaded the backup onto.
```
restore_devportal -c -s backup_file_absolute_path
```
where backup_file_absolute_path is the location of your backup file. For more information about this command, see restore_devportal.
Note: If you're not reusing the old hostnames for the new OVAs, but these old hostnames are used within the URL of your Portal sites, then it's best practice to update the Developer Portal site URLs for each site within the API Manager to use the new hostnames.
Optional: For standalone environments only, turn on SSL for MySQL.
For some V5 standalone environments, you might get an SSL error when you try to upgrade to later releases post-migration to Ubuntu18. This error is because SSL is not turned on for MySQL for standalone, and the MySQL server was not configured correctly. Run these commands:
```
mysql_certs -fgl
stop_db
start_db
```
For a single-node migration, the migration procedure is now complete.

For a multi-node migration, you need to create the cluster membership by continuing with the following steps.
On the OVA that you just restored the Developer Portal onto, run the following command to create the cluster membership:
```
set_cluster_members -c
```
After the command has completed, run the status command and check that the server is marked as SUCCESS.
When the cluster membership has been successfully created, add the remaining machines to the cluster by running the following command on each of the other new OVAs:
```
set_cluster_members hostname_of_first_member
```
Where hostname_of_first_member is the hostname of the first OVA that you ran set_cluster_members -c on.
It's recommended that you wait for each invocation of set_cluster_members to finish successfully, before running the command on the next machine. You should run the status command on each OVA to check that the server is marked as SUCCESS before moving on to the next machine.
Note that it might take several hours for large deployments to fully replicate across all servers.

Results

You have migrated your Developer Portal OVAs from Ubuntu V16.04 to Ubuntu V18.04.

What to do next

When you next upgrade to Developer Portal releases in the API Connect Version 5.0.x stream, you must use the version-APIConnect-Portal-Ubuntu18-yyyymmdd-hhmm.bin upgrade file.