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:
- 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.