It is strongly recommended that you migrate your Developer Portal to
the Ubuntu V16.04 base now because support for Debian V7 upgrades was withdrawn in May 2018. To
migrate your Developer Portal OVAs
from Debian V7 to Ubuntu V16.04, you need to upgrade your existing Debian OVAs, if not already on
the latest version, deploy and configure the new Ubuntu OVAs to replace them, and then shutdown all
the Debian OVAs.
Before you begin
Upgrade to the 5.0.8.3-APIConnect-Portal-Debian7-20180508-1349 Debian interim fix that is available from IBM® Support Fix Central: https://www-945.ibm.com/support/fixcentral/swg/selectFixes?parent=ibm~WebSphere&product=ibm/WebSphere/IBM+API+Connect&release=5.0.8.3&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 5.0.8.3-APIConnect-Portal-Ubuntu16-20180508-1349 Ubuntu
OVA file, and the latest 5.0.8.x fix pack/interim fix (to upgrade the Ubuntu servers after the
migration).
- Debian V7 upgrade file
-
5.0.8.3-APIConnect-Portal-Debian7-20180508-1349.bin
- Ubuntu V16.04 OVA file
-
5.0.8.3-APIConnect-Portal-Ubuntu16-20180508-1349.ova
It is recommended that you back up your Developer Portal
before you start this process. For more information, see Backing up and restoring the Developer Portal.
- Pre-migration checks
- Ensure that your Debian portal servers successfully upgraded to the most recent IBM API
Connect Version 5.0.8.3
interim fix 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.3-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.3-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_3_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 list_platforms and confirm that a platform that matches the
Distribution version from step 1 is listed; for example,
platform_devportal_7_x_5_0_8_3_yyyymmdd-hhmm =>
devportal-7.x-5.0.8.3-yyyymmdd-hhmm : Template Exists (default)
. Any older platforms can be
deleted by using the delete_platform command; deleting these platforms saves time
later when the portal replicates with other cluster members.
- Run the command check_site -a and confirm that all sites are up and are
returning
200
HTTP codes.
- Run the command ready_to_migrate to confirm that all sites are in a valid
state to migrate.
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 Debian 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 a Debian V7 base to an Ubuntu V16.04 base. Support for the Debian V7 OVA was withdrawn in
May 2018. The following steps describe how to upgrade your Developer Portal
platform software to upgrade your sites to use the new distribution, and then to migrate the OVA to
the Ubuntu base. After the Developer Portal is
migrated to Ubuntu, 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.Important: You can complete the migration
by using one of the following methods:
Procedure
- Migrating by clustering new Ubuntu nodes with the existing Debian nodes.
- Ensure that you complete the pre-migration
checks described previously, and that the Distribution version of your Debian nodes matches
that of the Ubuntu nodes that you are migrating to.
- If your Developer Portal is a stand-alone Debian machine, you must set that machine to be in a cluster of one member. Run the following command:
[[ $(dbstatus) == "Standalone" ]] && set_cluster_members -c
- Deploy the Ubuntu V16.04 OVAs. You must deploy as many Ubuntu OVAs as there are Debian OVAs in your Developer Portal cluster. Deploy the portal OVAs as described in Deploying the Developer Portal OVA file, and then configure them as described in Installing the Developer Portal; you must complete all the steps described, ensuring that the Management cluster that you specify is the same as that used by the Debian nodes.
- Ensure that the Ubuntu nodes report the same time and NTP server as the Debian nodes. All nodes must also have their operating system timezone set to UTC; this is the default setting so you need to change this only if it has been changed previously.
-
On the first configured Ubuntu portal node, run the following command:
touch /var/aegir/config/nginx.conf
and then add this node to the cluster
by running the following
command:
set_cluster_members IP_address_of_an_existing_Debian_7_ova
Repeat
the
set_cluster_members
command for every Ubuntu OVA that you are adding to the
cluster.
- Run the
status
command. Check that every server is marked as SUCCESS
. It might take several hours for large deployments to fully replicate across all servers.
-
If the sites on the Debian nodes are still being used, you need to restart nginx on the sites
so that they can use the updated nginx config file that was replicated from the Ubuntu node. To do
this, run
sudo service nginx restart
on all of the Debian nodes.
- Add the new Ubuntu OVAs into the existing load balancing configuration for the Developer Portal user interfaces, and for the SSH communication from the Cloud Manager. For more information, see Load balancing in IBM API Connect and Load balancing the requests the Cloud Manager sends to the Developer Portal.
If the configuration does not use a load balancer, edit the IP address for the Cloud Manager SSH communication to match one of the new Ubuntu OVAs (modify the Portal Management Address field in the Cloud Manager UI, see Installing the Developer Portal).
- Shut down all of the existing Debian V7 OVAs, by logging in to the CLI for each Debian machine and running the following command:
queue_run -qp && sudo halt -p
- Log in to one of the Ubuntu V16.04 machines, and run the following commands depending on whether you are configuring a cluster of machines, or a stand-alone machine.
To recluster with the currently visible Ubuntu machines, run the following
command:
set_cluster_members -v
For a stand-alone Ubuntu machine, run the following command to de-cluster the single machine and convert it to stand-alone mode:
set_cluster_members -v1
Your cluster of Ubuntu machines, or stand-alone machine, is set up.
-
Apply the latest 5.0.8.x fix pack/interim fix that is available on IBM Support Fix Central.
- Migrating by using a backup file. If you can have only one virtual
machine at a time in your environment, you must complete the following instructions to migrate your
Developer Portal
OVA from Debian V7 to Ubuntu V16.04. The backup file method should be done on a stand-alone Debian
node to a stand-alone Ubuntu node only.
-
Complete the pre-migration checks described previously.
- If the Debian deployment is part of a cluster, reduce it down to a single node by
using the
set_cluster_members -d
command.
-
Back up your Debian Developer Portal by
using the
backup_devportal
command, and then save the backup to a separate FTP/SFTP
server.
For more information, see
backup_devportal.
Important: You must save your backup to a separate server. Otherwise the backup is lost when
you delete your Debian Developer Portal in
the next step.
-
Delete your Debian Developer Portal
virtual machine.
-
Deploy the Ubuntu Developer Portal OVA
in place of the deleted Debian one, and set the same IP address and host name as the deleted Debian
OVA.
-
Configure the Ubuntu Developer Portal to
connect to the management server. For detailed steps, see Installing the Developer Portal.
-
Copy the Debian Developer Portal
backup that you created in Step 3 to the newly deployed Ubuntu server by using FTP, SFTP, or SCP. Then, restore the
site by using the
restore_devportal -scn
command.
For
example:
restore_devportal -scn backup_file_absolute_path
where
backup_file_absolute_path
is the location of your backup file.
For more information, see
restore_devportal.
-
Run the
status
command.
Check that the server is marked as SUCCESS
.
-
Apply the latest 5.0.8.x fix pack/interim fix that is available on IBM Support Fix Central.
Results
You have migrated your Developer Portal OVAs from Debian V7 to Ubuntu V16.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-Ubuntu16-yyyymmdd-hhmm.bin
upgrade file.