While working with one of my friends, he asked that we go over upgrading uPortal between minor versions. He has done it before, so this was more of a refresher, though he needs to teach his back up soon. I offered to write the instructions in a narrative to pass along. We thought it would make for an excellent chance to share the process in a blog, so here it is!
uPortal 5 saw the introduction of the uPortal-start repo, where configuration and customization could be captured without the need to carry around all the uPortal source code. It has proved helpful for adopters seeking to separate local changes from the community codebase.
Even with uPortal-start being such a minimal repo, there are changes that should be monitored. As part of the upgrade process, changes between the community version of “uPortal-start” and your own should be compared. Sometimes, community changes are minimal and can be skipped. In this case, upgrading is a simple version change. In other cases, a merge and clean-up effort is required.
Comparing Your uPortal-start
The first step entails connecting your repo to the community version, followed by a comparison.
Clone your repo locally or in a dev server if you haven’t yet:
$ git clone git@github.com:<my-github-account>/uPortal-start $ cd uPortal-start
Be aware that you should already have a repo set up in a service and SSH keys installed in your related account. This varies from public services, like GitHub and BitBucket, to a local institution service. Given this prerequisite, it seems silly to note the `git clone`; however, we are covering the base case where someone unfamiliar with uPortal is stepping in to assist with the upgrade.
Next, we need to add a reference to the community version, if missing:
$ git remote -v
origin git@github.com:<my-github-account>/uPortal-start (fetch)
origin git@github.com:<my-github-account>/uPortal-start (push)
$ git remote add upstream git@github.com:uPortal-project/uPortal-start.git
$ git remote -v
origin git@github.com:<my-github-account>/uPortal-start (fetch)
origin git@github.com:<my-github-account>/uPortal-start (push)
upstream git@github.com:uPortal-project/uPortal-start.git (fetch)
upstream git@github.com:uPortal-project/uPortal-start.git (push)
If you see the “upstream” to the uPortal-project repo for the first `git remote -v`, then you are set up and do not need to run the `git remote add`.
Next comes a step that requires institutional knowledge of what branch is considered the “master” branch in your repo. The usual default is “master” or “main.” If you have worked with us, you may have heard our suggestion to have a main branch named something other than these two default branches, with a preference for your mascot or abbreviation of your institution.
To see what branches are in your repo, run the following:
$ git branch
Identify your main branch and check it out. Let’s assume your main branch is named “mascot-edu.”
$ git checkout mascot-edu
Next, we need to fetch the community commit history, which is basically a copy of the community repo:
$ git fetch upstream
Expect to see a lot of output as Git pulls down information on that uPortal-start repo.
Once that completes, it is time to start looking at what the changes entail and to decide if we want to simply adopt a new version of uPortal and portlets, or merge in build/configuration changes. I start with a list of files that have changed:
$ git diff upstream/master –name-only
This produces a list of the files that differ between your main branch and the community version of uPortal-start. (Note that “name-only” is preceded by double-dashes.) File changes in `data/quickstart/` do not directly impact your service; however, these changes could indicate new datafile requirements or other import changes that may need to be applied to your dataset. Gradle file changes can certainly be important to capture. Overlay changes fall in the middle and often are useful but not always required.
$ git diff upstream/master <file>
The above will give you the differences in detail. At least check a few files to get a feel for the extent of the update.
Also, check the uPortal and portlet release notes in GitHub. We capture changes between releases on each repository. Once you have a high-level understanding of differences, you can now make a sound decision to follow one of two upgrade paths:
- Change the uPortal/portlet versions to the latest version in `gradle.properties` or
- Merge all the changes into your uPortal-start repo
Upgrading Versions Only
If you feel the configuration, dataset, and Gradle changes are unnecessary, you can easily upgrade uPortal, portlets, and web components without additional Git commands. I may opt for this approach if I am upgrading a portlet to a newer patch release or if I have recently performed a uPortal-start merge. Here, we are simply going to edit `gradle.properties` to update the version, then perform testing.
Please be mindful of the comments in `gradle.properties`. There are versions for some larger dependencies, such as CAS, that do not change with uPortal versions. Some dependencies are driven by Tomcat, as another example.
Here is how easy it is to upgrade uPortal. Let’s say you are running uPortal 5.11.0 and want to upgrade to 5.13.1, the latest patch release at this time. You would change the “uPortalVersion” value from “5.11.0” to “5.13.1” around line 24 in gradle.properties. That’s it! You do want to run “./gradle clean” before you follow your normal deployment process.
During testing, if you run into issues, you may have to revisit the above section to check if some Gradle or other changes are needed for this upgrade, but usually upgrading patch releases can be done this way.
Or, Merging In Changes
You have reviewed the differences and decided that all the uPortal-start changes need to be merged into your main branch, whether it is an important Gradle task change or some new overlay configuration file that is now used. In any case, it is time to get in sync with the community version once again.
Let’s create a working branch to merge in changes and correct any conflicts.
$ git checkout -b upstream-<vers>-merge
Replace the “<vers>” with the version or some other identifier for this effort. It is up to you. Since your last checkout was your local main branch, this new branch is a copy of that. We only fetched the upstream, which only pulled down the community commits into a type of local cache. So, let’s get the upstream changes into this new working branch.
$ git merge upstream/master
WARNING: You are likely to see some conflicts and have to revise the code in your branch. Run the following to see the status of files, especially the “Unmerged paths” that need to be edited:
$ git status
This is the primary effort of this upgrade flow – working through the conflicts and testing. I wish I could provide more guidance and tips, but this effort really depends on what local changes have transpired and how often your repo has kept in sync with the community version. Test, test, test!
Note that we now have integration with Playwright. While the tests assume the default QuickStart dataset, most of the tests should run. Those that do not run because of your customizations should be updated for your configuration. The Playwright test files are in the tests/ directory. You can run them via Gradle.
$ ./gradlew playwrightRun
Once you are happy with the branch and everything looks ready for production, it’s time to merge the working branch into your main branch.
$ git checkout mascot-edu $ git merge upstream-<vers>-merge
At this point, all the changes are now merged into your branch and you are ready to deploy!
I hope this helps sort out how to pick up changes as you need to keep your uPortal service running on the latest versions.
If you need additional help, Unicon has support services for uPortal and also offers custom engagements depending on your needs and budget
