Deploying Portlets to uPortal

Owned by Jen Bourey
Jun 12, 2013
6 min read

Using "ant deployPortletApp"

Portlets should be built using their native build mechanism (in the case of Jasig portlets, generally Maven). This build process should result in a .war file with a web.xml file that does not specify any Pluto-specific information or contain any Pluto jars.

The uPortal "ant deployPortletApp" task is designed to apply the appropriate modifications for the version of Pluto that uPortal uses, then deploy the updated portlet war to the appropriate Tomcat location.

ant deployPortletApp -DportletApp=/path/to/my/portlet.war

If you'd like to make sure any existing matching portlet application is deleted before being redeployed, please set the value of "removeExisting" in uPortal's build.properties file to "true" (this is the default value).

# Should the existing webapp be removed before deploying the new webapp
removeExisting=true

You can also choose whether the ant task will extract the war file while copying it to the servlet container. To perform extraction, set "extractWars" in uPortal's build.properties file to "true".

# Should the deployment tools extract the WARs when copying them into the servlet container 
extractWars=true

Adding Portlets to uPortal's Portlet Overlays

Although portlets may be manually deployed via the ant command described above, adopters may also instead choose to add a portlet to the uPortal build to be automatically deployed each time the "ant deploy-ear" task is run. This method also allows adopters to use vanilla versions of portlets from a public maven repository, then create "overlays" for any files requiring customization. By following this strategy, adopters no longer need to maintain custom separate portlet projects.

Add the portlet overlay

To add a portlet to the uPortal build as an overlay, first create a folder inside uPortal/uportal-portlet-overlays. If I were adding the Jasig Announcements portlet to the overlay, I might name the folder "Announcements". Next, create a POM file for this portlet.

In the top level of the portlet, create a file named "pom.xml". This file will use the main portal pom as its parent and use the portal's version as its version. The project will declare the desired portlet as a dependency. The groupId and artifactId of the dependency should match those of the project itself. The artifactId for the module can be whatever you'd like, but it's easiest to make it the same as the project.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <parent>
        <groupId>org.jasig.portal.portlets-overlay</groupId>
        <artifactId>uportal-portlets-overlay-parent</artifactId>
        <version>3.2.5-SNAPSHOT</version>
    </parent>

    <modelVersion>4.0.0</modelVersion>
    <artifactId>Announcements</artifactId>
    <packaging>war</packaging>

    <name>Announcements Portlet</name>
    <description>Overlay on Bookmarks Portlet.</description>

    <dependencies>
        <!-- ===== Compile Time Dependencies ============================== -->
        <dependency>
            <groupId>org.jasig.portlet</groupId>
            <artifactId>Announcements</artifactId>
            <version>${AnnouncementsPortlet.version}</version>
            <type>war</type>
        </dependency>
        
        <dependency>
            <groupId>${jdbc.groupId}</groupId>
            <artifactId>${jdbc.artifactId}</artifactId>
            <version>${jdbc.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-war-plugin</artifactId>
            </plugin>
           <plugin>
                <groupId>org.apache.pluto</groupId>
                <artifactId>maven-pluto-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Add a property named "AnnouncementsPortlet.version" to the main uPortal pom file. This will allow the version to be easily updated in the future. To do this, open uPortal/pom.xml and locate the <properties/> element. Add a new property to indicate the version of the Announcements portlet:

    <properties>

        . . .

        <!-- WAR Dependency Version Properties -->
        . . .
        <AnnouncementsPortlet.version>1.1-M1</AnnouncementsPortlet.version>
        . . .
    </properties>

The new overlay needs to be added to the overlays project pom as a module. Open uPortal/uportal-portlet-overlays/pom.xml and add your new folder as a dependency:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    . . . 

    <modules>
        <module>BookmarksPortlet</module>
        . . .
        <module>Announcements</module>
    </modules>

    . . . 

</project>

Add the overlay as a dependency of the uportal-ear project

Once you've created your new overlay, it needs to be added to the uportal ear file. To do this, add the new module as a dependency in uportal/uportal-ear/pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    . . .

    <dependencies>

        . . .
        
        <dependency>
            <groupId>org.jasig.portal.portlets-overlay</groupId>
            <artifactId>Announcements</artifactId>
            <version>${project.version}</version>
            <type>war</type>
        </dependency>

        . . .
    </dependencies>        

    <build>
        <finalName>${uportal.docbase}</finalName>
        <plugins>
            <plugin>
                <artifactId>maven-deploy-plugin</artifactId>
                <configuration>
                    <skip>true</skip>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-ear-plugin</artifactId>
                <configuration>
                    <modules>
                        . . .
                        <webModule>
                            <groupId>org.jasig.portal.portlets-overlay</groupId>
                            <artifactId>Announcements</artifactId>
                            <bundleFileName>Announcements.war</bundleFileName>
                            <contextRoot>/Announcements</contextRoot>
                        </webModule>
                    </modules>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Using uPortal's Maven Plugin