A new era in the story of Apereo uPortal is dawning: the era of uPortal 5. This new chapter brings many profound changes to uPortal. From my perspective, this new major version (version 5) is significantly more different from its precursor (version 4) than version 4 was from version 3. In fact, I would say this change (from 4 to 5) is more significant than any new major version since version 2.
I hope to catalog these differences more effectively in other articles, as well as to update important discussions like "What even is uPortal?" and, "Why should my organization adopt uPortal?" For now, the "main takeaway" in this area is that (its developers believe) uPortal 5 is a sea change: you must reevaluate what you think you know about what uPortal can do, and what working with it is like.
This article is a reboot of a series that has appeared on unicon.net for a long time. The most recent previous installment is Build, Install, & Run uPortal 4.1 (from back in 2013). The articles in this series describe how to set up a local development uPortal deployment; this kind of deployment is suitable for making configuration and/or skinning changes to your portal, as well as for developing content (e.g. portlets) for your portal. I hope that audiences who have worked with uPortal 4 (and maybe even read that article) and audiences who are looking at uPortal for the first time now (with version 5) are both well represented.
Prerequisites
To run uPortal 5 on any machine, you must install a few software packages first:
- A Java 8 Development Kit (JDK)
- An appropriate distribution of Git for your operating system
Those of you who have worked with previous versions of uPortal should recognize one thing immediately: this list is quite a bit shorter than it was in the past. As adopters of uPortal 5, we do our work through a new component called uPortal-start (more on this item below). uPortal-start shifts several installation tasks from "individually-managed" activities to "community-managed" activities. uPortal-start allows the uPortal community to handle several tedious, potentially confusing, error-prone tasks on your behalf.
Install a Java 8 Development Kit (JDK)
Installing a Java 8 JDK is easy. Most uPortal deployments use the Oracle Corporation's JDK, but OpenJDK is a viable alternative. Choose the most recent update (release) for your operating system and CPU. A GUI-based installer package is available for Windows.
Warning!
There is one special detail you need to handle in setting up your JDK: you must properly define a JAVA_HOME environment variable. Here are some comprehensive instructions for Windows as well as instructions for Linux operating systems.
To verify that your JDK is set up properly, open a command prompt and run $ java -version (without typing the $). You should get a response like the following:
Install Git
Installing Git on your machine is also very easy. Choose the Git download option that is appropriate for your operating system and CPU. You can find very thorough instructions for installing on Linux, Mac, and Windows on the Git website.
When you finish installing Git, verify that it is working by running the $ git --version command (again without the $). You should see output something like this:
Once you have a JDK and Git installed and working, you are ready to set up uPortal 5. Depending on network speed, etc., the entire process should take about 5 minutes (I timed it myself on a fresh Windows machine).
Introducing uPortal-start
Perhaps the most important innovation of uPortal 5 is uPortal-start. The reason that performing tasks on uPortal 5 is both significantly easier and significantly speedier than previous versions is because working with uPortal 5 is significantly different. uPortal-start is the mechanism for adopting and implementing uPortal 5.
Previous to version 5, as an adopter of uPortal you were obligated to clone (from GitHub) and build almost the entire universe of uPortal technology. At the present moment, there are 3375 files in the rel-4-3-patches branch of uPortal (the latest pre-version 5 code). By contrast, there are currently 419 files in uPortal-start... about 87.5% fewer! (The contrast in the number of .java files is even more stark: 1771 in uPortal 4 vs. almost none at all in uPortal-start.)
uPortal-start contains only the components that transform uPortal into your portal; it provides support for...
- Your uPortal configuration
- Your uPortal skin
- Your uPortal data
- And your uPortal deployments through an integrated suite of CLI tools
Beginning with uPortal version 5 (and uPortal-start), it is no longer necessary for adopters to build the core uPortal source code with each deployment... or ever! The community of uPortal developers cuts releases of uPortal 5; uPortal-start knows how to combine a community-provided release of uPortal with your implementation choices. The new process is clearer, cleaner, and quite a bit faster than the old process.
How to Set Up uPortal-start the First Time
Open a command prompt. Use the following four commands to get a complete uPortal 5 deployment up and running the first time:
Windows Example:
> get clone https://github.com/Jasig/uPortal-start.git
> cd uPortal-start
> gradlew.bat portalInit
> gradlew.bat tomcatStart
*nix Example:
$ get clone https://github.com/Jasig/uPortal-start.git
$ cd uPortal-start
$ ./gradlew portalInit
$ ./gradlew tomcatStart
NOTE: Startup of the servlet container (Tomcat) is not instantaneous. Typically, you will need to wait almost a minute for this process to complete.
That's it! (You are done.)
Point your browser to http://localhost:8080/uPortal (or use the $ ./gradlew portalOpen task included with uPortal-start to open a browser window to the correct location).
Next Steps
Now that you're up & running with uPortal 5, here are some things you can do right away to deepen your understanding of uPortal and learn how to implement uPortal for your institution/organization efficiently and effectively:
- Review the README file for uPortal-start; it contains clear and useful information about the tools uPortal-start provides
- Contact Unicon for a demo of uPortal 5, information on services for uPortal, and/or to get your uPortal questions answered
- View the Introducing uPortal-start webinar presented by the uPortal Steering Committee on 2017/09/14
- Join the uPortal-user mailing list; introduce yourself
- Plan to attend Open Apereo 2018 starting June 3rd in Montreal, Quebec (Open Apereo is the best place to learn about uPortal and meet others who are using it!)
