uPortal 5 on Ubuntu 24.04 on Azure User Guide

Overview

Apereo uPortal is a free, open source enterprise portal framework built by and for the higher education community. It aggregates content and self-service applications into a single, personalised dashboard of portlets, presents content on the basis of group membership and user attributes, integrates with single sign-on, and gives administrators a web console for managing tenants, groups, permissions and the portlet registry. The cloudimg image ships the Apache-2.0 licensed uPortal 5.17.9 release, deployed with the official uPortal-start overlay on Apache Tomcat with OpenJDK 11 behind nginx as a reverse proxy. PostgreSQL 17 is the application database and uPortal's built-in Lucene index provides portal search. Tomcat listens on 127.0.0.1:8080 and PostgreSQL on the loopback interface only; both are reached through nginx on port 80.

The image is secure by default. uPortal-start seeds a set of well known demo logins (admin, staff, student, faculty, developer, each with the password equal to the username). The cloudimg image poisons every one of those passwords so they are dead in the shipped image, and on the first boot of every VM a one shot service mints a unique administrator password and a unique database password, writes them to /root/uportal-credentials.txt (mode 0600), and only then starts the public web interface. The demo tenant ships intact so you have an explorable, portlet-rich portal to sign in to immediately. Backed by 24/7 cloudimg support.

What is included:

• Apereo uPortal 5.17.9 deployed with the uPortal-start overlay on Apache Tomcat 8.5 with OpenJDK 11
• nginx reverse proxy on :80 in front of Tomcat (bound to loopback :8080)
• PostgreSQL 17 as the application database, bound to loopback only
• uPortal's built-in Lucene portal search (no external search service to run)
• A one shot first boot service that mints a unique admin password and a unique database password per VM and disables every demo login
• The uPortal demo tenant: a ready to explore dashboard of portlets plus the full administration tools

Recommended VM size: Standard_B2ms (2 vCPU, 8 GiB) or larger. uPortal is a Spring/Tomcat application running alongside PostgreSQL; 8 GiB gives the JVM comfortable headroom under real multi-user load.

Deploy the image

From the Azure Marketplace

1. In the Azure portal, choose Create a resource and search for the cloudimg uPortal listing.
2. Select the plan, then Create.
3. Choose a resource group and region, set the VM size to Standard_B2ms or larger, and provide an administrator username (for SSH) and SSH public key.
4. On the Networking tab, allow inbound SSH (22) and HTTP (80) from the addresses you will manage the portal from.
5. Review and create. When the VM is running, note its public IP address.

From the Azure CLI

Replace the resource group, image reference, size, admin username and SSH key path to suit your environment.

az vm create \
  --resource-group my-uportal-rg \
  --name uportal-vm \
  --image <cloudimg-uportal-image-urn> \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

# Open the HTTP port so you can reach the portal
az vm open-port --resource-group my-uportal-rg --name uportal-vm --port 80 --priority 900

The first boot service takes a minute or two on the very first start while it mints the per-VM secrets and warms up Tomcat. Give it a couple of minutes before browsing to the site.

Confirm the services are running

SSH to the VM as the administrator user you set at deploy time, then confirm PostgreSQL, uPortal (Tomcat) and nginx are all active:

systemctl is-active postgresql uportal-tomcat nginx

Only nginx is published on the network; Tomcat and PostgreSQL are bound to the loopback interface and are never exposed directly:

sudo ss -tln | grep -E ':80|:8080|:5432'

Retrieve the per-VM administrator login

On the first boot of every VM, uportal-firstboot.service rotates the database password and the uPortal admin password to values unique to that instance, disables the shipped demo logins, and writes the results to a root-only file. Read it over SSH:

sudo cat /root/uportal-credentials.txt

The file lists the portal URL, the admin login and its per-VM password, and the database name, user and per-VM database password. The first boot log shows the sequence, and the credentials file is readable only by root:

The shipped default logins are dead. You can confirm that the well known admin / admin login is rejected while the per-VM administrator password authenticates through the real portal login:

First sign-in

Browse to http://<your-vm-public-ip>/ and the portal redirects to /uPortal/. Unauthenticated visitors see the public portal with a set of demo content portlets and a Sign In control at the top right.

Click Sign In and enter admin with the uportal.admin.pass value from /root/uportal-credentials.txt. After signing in you land on the administrator dashboard, a grid of portlets and administration tools that you can favourite, search and arrange:

Change the administrator password from the portal after your first sign-in, and create named accounts for your users rather than sharing the administrator login.

Administer the portal

uPortal's administration tools are reached from the dashboard. Portlet Administration is the portlet registry, where you register, publish, categorise and manage every portlet in the portal:

Groups Administration manages groups of portlets (by category) and groups of people (by role), which drive who can see and use each portlet:

From here you can also reach Permissions, Fragment Administration (shared layout fragments), the Import/Export portlet, Cache Manager and the other tools shown on the dashboard.

Enable HTTPS (recommended)

For production use, put the portal behind HTTPS. Point a DNS name at the VM's public IP, then use certbot with the nginx plugin to obtain and install a Let's Encrypt certificate:

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

certbot edits the nginx site to serve HTTPS and sets up automatic renewal. After enabling TLS, restrict inbound access so only 443 (and 22 for administration) is reachable from the internet.

Backup and maintenance

The portal state lives in the PostgreSQL uPortal database. Take a logical backup with pg_dump:

sudo -u postgres pg_dump uPortal | gzip > uportal-backup-$(date +%F).sql.gz

Keep the operating system patched with the usual Ubuntu updates:

sudo apt-get update && sudo apt-get upgrade -y

To restart the portal after a configuration change:

sudo systemctl restart uportal-tomcat

Support

This image is maintained by cloudimg with 24/7 support. If you need help deploying or operating uPortal on Azure, contact cloudimg support through the marketplace listing.