Portal 5 Upgrade Procedure

This document tells what to do when you have an instance of the EDRN Portal that's ready for upgrading, including at the production site, https://edrn.nci.nih.gov.

Background

The EDRN portal uses the Plone content management system which itself is made of a large number of Python software components, Plone add-ons (more Python components), as well as content database. Upgrading Plone is another process not described here; what we're talking about is upgrades to the custom software that the Informatics Center has developed to turn a Plone site into the EDRN site.

Because the EDRN-custom software are just Plone add-ons, we use the same upgrade procedure as for any other Plone add-on—with a few bonus steps.

Procedure

The process to upgrade an EDRN site generally takes three steps:

1. Upgrade Plone.
2. Upgrade add-ons
3. Ingest RDF

Upgrade Plone.

Note that not every upgrade to the EDRN Portal includes an upgrade to Plone. For those cases when it does (such as 5.0.3), Plone must be upgraded first before the add-ons are. To do so, you generally just need to visit https://edrn.nci.nih.gov/ and log in with an account with "Manager" privileges; visit the Site Setup control panel, and follow the upgrade prompts.

However, sometimes the Plone upgrade produces pages that aren't usable, including the Site Setup control panel. In that case, you may need to visit the Zope Management Interface at https://edrn.nci.nih.gov/manage_main and follow the prompts at the top of the page.

In rare cases, though, even logging in will be impossible until the Plone upgrade is complete. When this happens, you can still upgrade Plone by using a curl command similar to the following:

curl -v --user 'USERNAME:PASSWORD' -H 'Content-Type: application/x-www-form-urlencoded' --data 'form.submitted%3Aboolean=True&submit=Upgrade' 'https://edrn.nci.nih.gov/@@plone-upgrade' 

Replace USERNAME and PASSWORD with the credentials for someone with a Manager-level account (a member of the Super User group, for example). The Plone upgrade should proceed normally at this point.

🕰 Certain Plone upgrades can take a long time. You may get the web server reporting a proxy timeout before it completes. You can always check the server logs to see how it's going and if it's done.

Upgrading Add-ons

When new EDRN software is installed (or a Docker image created), and started, the Plone add-ons control panel will list that upgrades are available to the EDRN add-ons. The following tells how to upgrade an instance of the EDRN Portal:

1. Log in as a user with Manager privileges to the EDRN site (such as one in the "Super User" group or the Zope "Manager" user).
2. Click "Site Setup".
3. Click "Add Ons".
4. Click the "Upgrade" button for any Plone add-on that's available, one at a time.

In general, you may see upgrades for several EDRN add-ons dependencies, such as eea.facetednavigation or collective.js.jqueryui. Do these first. Then do the EDRN-specific add-ons, if available in the following order:

1. edrn.theme
2. edrnsite.portlets
3. eke.knowledge ⚠️ This one may take a long time as it usually—but not always—reindexes the entire content database.
4. edrnsite.policy ⚠️ Ditto.

Note that if your browser shows a timeout waiting for an add-on upgrade to complete, it doesn't mean the process has failed. It just takes a long time. Check the server's log file to see if it's going well.

Ingesting RDF

Much of the content in the EDRN portal comes from data distributed in RDF. After upgrading, you'll need to manually run a fresh ingest of that RDF data so the latest content is available on the site.

To do so:

1. Log in as a user with Manager privileges to the EDRN site (such as one in the "Super User" group or the Zope "Manager" user).
2. Click "Site Setup".
3. Click "EKE Controls".
4. Check the box by "Enable Ingest" and click Save.

Then trigger the ingest by visiting the root of the site and appending /@@ingestRDF to the URL.

🕰 Note: this process takes a long time—well over an hour—and your browser will show a timeout before you see any results. Don't fret, though. Just check the server's logs to see if it's going OK.