This article is the latest in a long-running series on Unicon.net that covers basic uPortal installation for a local development environment. Its content is pretty close to previous versions, but has been edited and updated to reflect changes in the newest version.
NOTE: uPortal 4.1 Is Not Yet Released
This article is about the next exciting version of uPortal: version 4.1. At the present time, uPortal 4.1 has not yet been released. No certain release date has been chosen or proposed; based on recent progress, uPortal 4.1 might be available in the early part of 2014.
Introduction
This article is geared toward installation of a local portal, such as you might use to develop portlets that adhere to the 2.0 (JSR-286) Java Portlet Specification. This exercise is also a great way to learn the platform in greater depth. Examples and screenshots are given for a Windows platform, but the concepts are applicable to other operating systems, including MacOS and *nix platforms.
The steps covered in this article are also documented online in the uPortal Manual Be sure to check out that fabulous resource! There you will find coverage of more comprehensive installation options, as well as information on more advanced topics like integrating with LDAP, CAS, Shibboleth and/or Grouper.
Getting Started
To begin, create a directory in which we will put all our work. To prevent possible issues down the road, we will choose a directory (1) with a short, space-free name and (2) at the root of the file system. File paths with spaces in them (e.g. 'My Documents') can cause poorly-written programs to break. Also, Windows systems support a limited number of characters (255) in file paths; since some of the technologies we will be working with contain many nested subfolders, it's best not to tempt fate by adding too many characters at the beginning.
The final name choice is arbitrary, but 'portal' seems sensible.
C:\portal\
Java Development Kit (JDK)
uPortal 4 requires Java Development Kit (JDK) version 1.6 (Update 21 or later) or JDK version 1.7. We recommend the latest JDK 1.7. NOTE: A Java Virtual Machine (JVM) is not sufficient for building and running uPortal; you need the full JDK, which includes important platform tools like the compiler!
For this tutorial, we will be using the following JDK download (v. 1.7 Update 45): jdk-7u45-windows-x64.exe
Double-click this file to begin the installation process. Change the 'Install to:' directory to simply 'C:\jdk1.7.0_45\' (again, it's best to avoid paths with spaces).
Some java applications -- including several we're about to install -- require an environment variable called JAVA_HOME to be set with the value equal to the location of the JDK directory. To finish the installation, please create the following environment variable:
JAVA_HOME = C:\jdk1.6.0_27
Environment variables on Windows 7 can be set with the following procedure
- Right-click on the Computer icon and select Properties
- Select the Advanced system settings option (left-hand side)
- Click the Environment Variables... button
- Use the New... and Edit... buttons in the System variables section
- After the JAVA_HOME environment variable is created, you will need to update the Path environment variable. The following text should be ADDED to the beginning of the Path environment variable.
%JAVA_HOME%\bin;{existing path}
NOTE: Command windows that were open on your desktop previously will not be affected by these changes; they will need to be closed and re-opened.
To make sure the installation was successful, open a command prompt and type:
>java -version
The system should respond with information about the J2SE installation. For more information about J2SE, please visit http://java.sun.com/javase/.
Apache Ant
The next prerequisite we will install is Apache Ant a popular and mature Java build tool. uPortal 4 .1.0 requires Ant version 1.8.2, which can be obtained from the Ant downloads page. Once you have the apache-ant-1.8.2-bin.zipfile, unzip it into your C:\portal directory. You should now have the following directory, which contains Ant:
C:\portal\apache-ant-1.8.2
Next, we need to create an environment variable specifying the location of the Ant installation (refer to instructions for JAVA_HOME above):
ANT_HOME = C:\portal\apache-ant-1.8.2
We need to be able to invoke Ant on the command line from anywhere in the file system. To make this possible, modify the Path environment variable once more, appending the location of the ant.bat file:
PATH = {existing path};%ANT_HOME%\bin
Test your Ant installation by invoking the following command (REMINDER: always open a new command prompt after changing environment variables):
ant -version
The system should respond with information about your ant installation.
Apache Maven
The next prerequisite is Apache Maven, another build tool from Apache. "But wait," you astutely observe, "isn't that what we have Ant for?" Well, yes & no. As you will see in the section on uPortal itself, the portal provides several setup and administrative functions through Ant. Building the uPortal software, on the other hand, has been largely migrated to Maven. For the present, these 2 tools work together to handle build, deployment, and some management features of the portal.
uPortal 4.1 requires Maven version 3.0.3 or later, which can be obtained from the Maven downloads page. Once you have the apache-maven-3.0.3-bin.zip file (or a more recent version), unzip it into your C:\portal directory. You should now have the following directory, which contains Maven:
C:\portal\apache-maven-3.0.3
Maven setup is very similar to Ant. Create a M2_HOME environment variable and update your Path variable.
M2_HOME = C:\portal\apache-maven-3.0.3
Path = {existing path};%M2_HOME%\bin
Finally, test your Maven setup by running the following command (REMINDER: open a new command window):
mvn -version
Apache Tomcat
Before we can install uPortal, we must have a servlet 2.5 or greater compliant web container available. A web container is a JEE server component that enables access to servlets and JSP pages. There are many to choose from including WebLogic (BEA), WebSphere (IBM), JRun (Macromedia), Resin (Caucho), Jetty (Mortbay), and Apache Tomcat. Tomcat is (by far) the easiest container to use with uPortal and is recommended for use with uPortal.
Download the Tomcat distribution from the Tomcat downloads page (note: uPortal 4.1 requires at least Tomcat 6.x, but we recommend Tomcat 7.x.)
Once you have the apache-tomcat-7.0.47.zip (or similar) file, unzip the file into the C:\portal directory. You should now have this directory containing Tomcat:
C:\portal\apache-tomcat-7.0.47\
Now, we need to configure Tomcat to work with uPortal. Locate the following file:
C:\portal\apache-tomcat-7.0.47\conf\catalina.properties
Find the shared.loader property and set the value as follows:
shared.loader=${catalina.base}/shared/lib/*.jar
WARNING! Make certain the shared.loader setting contains no typos, and no extra characters of any sort. An extra space at the end of this line can break the whole portal!
Next, locate the file:
C:\portal\apache-tomcat-7.0.47\conf\context.xml
Add sessionCookiePath="/" to the root <Content/> element, like so:
<Context sessionCookiePath="/">
The default uPortal installation requires Tomcat to use a bit more memory -- both PermGen memory and "regular" heap space -- then the default JVM configuration includes. To change these values, create a new file called setenv.bat (or setenv.sh on *-nix systems) in your Tomcat bin/ directory and add the following content:
set JAVA_OPTS=%JAVA_OPTS% -XX:+PrintCommandLineFlags -XX:MaxPermSize=384m -Xms1024m -Xmx1024m
Last, we will create desktop shortcuts to the batch files that start and stop Tomcat. These batch files are located at:
C:\portal\apache-tomcat-7.0.47\bin\startup.bat C:\portal\apache-tomcat-7.0.47\bin\shutdown.bat
Create shortcuts to these files and place them on the Windows desktop. Rename the shortcuts Start Tomcat and Stop Tomcat. To make sure Tomcat has been installed correctly -- and that the shortcuts are functioning -- double-click the Start Tomcat shortcut. A console window should open (and remain open) with a few startup messages from Tomcat. In a web browser, enter the URL http://localhost:8080/. This should bring up the Tomcat home page indicating that Tomcat is running successfully on your machine:
To shutdown Tomcat, simply double-click the Stop Tomcat shortcut on your desktop.
Git
The final prerequisite is a Git client for your operating system. Git is a "free and open source distributed version control system." The role of Git in your project is similar to Subversion or CVS, but the Distributed Version Control Paradigm is more complicated and takes some getting used to. On the up side, the capabilities this added complexity brings with it are extremely powerful, and especially effective for implementing an open source platform like uPortal. For Windows machines, I recommend the MSysGit client.
We need to install Git because that's how we're going to get (obtain) our copy of the uPortal source code. The Apereo uPortal project itself uses Git -- the project source code is available on GitHub. By getting uPortal this way, our copy of the source code remains linked to the Apereo project sources. This connection offers several important advantages:
- It's very easy to pull down new changes from Apereo. The Git tools for pulling and merging changes from multiple remote repositories are (relatively) simple, quick, and effective. It's a vast improvement over managing vendor branch merges in Subversion.
- It's very easy to contribute your enhancements, bug fixes, and new features back to Apereo. Even non-committers can submit updates using the Pull Requests feature on GitHub.
- It's very easy to promote the changes you make to Dev, Test, and Prod servers. This item isn't really Git-specific; any good version control system can be a big help in this respect. But a distributed version control system -- like Git -- can interact with the Apereo repo, your institution's repo, and as many other repos as needed all at once.
The uPortal Wiki space has a very nice section about using Git with uPortal that covers setup and common tasks in more detail than this article.
Follow the Git client installation instructions for your platform. You can test your Git client setup by running the following command (REMINDER: open a new command window):
>git --version
uPortal
At this point we have all the prerequisites installed and ready: the JDK, Ant, Maven, Tomcat, and a Git client. We are ready now to install uPortal. You can download the uPortal releases from the Apereo website, but for this exercise we want to obtain uPortal sources directly from the GitHub repo.
Execute the following commands in your C:\portal directory:
>git clone https://github.com/Jasig/uPortal.git >cd uPortal
Now you have a full, local copy of the uPortal source code -- as well as complete revision history, together with development branches for current/past/future releases and tags for every uPortal release!
The next step is to create a branch for your own work. (You can learn about why this step is important in the uPortal wiki space.) I suggest naming this branch for your institution, your portal itself (e.g. myU), or for your mascot. For this example, we'll use "titan" for a branch name. Use Git commands similar to the following:
#NOTE -- ordinarily we would start by checking out a tag or a branch, as in... #>git checkout rel-4-1-patches #But at the time of this writing no branch or tag exists for uPortal 4.1 since it hasn't yet been released. #Therefore we must base our deployment on the 'master' branch, which is already the default for a newly-cloned repository. >git checkout -b titan
Now we're ready to start implementing our portal. The first thing we need to do -- the only thing we really need to do before running our portal the first time -- is to tell uPortal about the servlet container we are using. We need to create a new build file by copying the build.properties.sample file to a new file named build.properties. Run the following command inside C:\portal:
>copy build.properties.sample build.properties
Now open the new file in an editor. Set the value of the server.home property as follows:
server.home=C:/portal/apache-tomcat-6.0.33
Important Note About Editing Files
I have experienced or observed many issues in the past caused by editing uPortal configuration files in Microsoft tools Textpad, Wordpad, and Word. I recommend that you avoid even opening uPortal files in any of these programs. Ever. Consider using something like Eclipse, IntelliJ Idea, or Textpad.
Initializing the Portal
Now it is time to build uPortal and load the database with an initial set of uPortal data (users, portlets, layout fragments, etc.)... but first, we need to start the database. Use the following command in your C:\portal\uPortal directory:
>start ant hsql
This command will launch the embedded HyperSQL portal database in a new DOS window. NOTE: This RDBMS platform is perfect for a local development portal, but not suitable for a large-scale production deployment. For your server deployments, you will need to choose a modern RDBMS -- typically Oracle, PostgreSQL ,or MS SQL Server -- and follow the instructions in the manual for configuring database connections.
Next, execute the Ant target that builds uPortal source, loads the database, and deploys the portal to Tomcat:
>ant initportal
The output should show information about the database and messages indicating that the database tables have been dropped, created, and populated. There should also be information about the publishing of portlets and layout fragments.
At this point you should be able to access the portal by starting Tomcat (restart Tomcat if it was already running) and visiting http://localhost:8080/uPortal in your browser.
That's it! Now you can log into the portal as the demo, student, staff, faculty, or admin user (HINT: the password is the same as the username).
