Custom Template Handling During Portal Update

Overview

You are planning to upgrade your Xinet Portal server and need to verify whether your custom Portal templates need to be replaced, updated, or backed up as part of the upgrade.

The expected behavior depends on the version of Xinet Portal you are upgrading to.

For versions prior to v2026.05.12, custom templates stored within the configured Document Root are not modified during the Portal upgrade.

Beginning with v2026.05.12, Portal template files are refreshed during every upgrade. This means customizations made directly to template files may be overwritten unless they are stored in the supported customization file.

Solution

For Xinet Portal versions prior to v2026.05.12

Due to how Xinet Portal handles the upgrade process, the custom templates you have created and stored within the Document Root are not modified. Prior to the Upgrade, ensure that your custom templates have been placed within your defined document root to avoid them being overwritten.

The current document root directory can be verified and modified from the Portal Admin > Edit > Server Details > Apache/PHP Settings page.

For Xinet Portal v2026.05.12 and later

Beginning with Xinet Portal v2026.05.12, the installportal process automatically refreshes every site’s templates/ directory from the default Portal template source directory:

/usr/etc/portal/TEMPLATES/

As a result, customizations made directly inside a deployed site’s templates/ directory may be overwritten during upgrade.

Examples of files that may be overwritten include:

browse.tmpl.html
portal.js
portal.css

The only file preserved inside the site’s templates/ directory is:

local.inc.php

local.inc.php is the intended customization mechanism for Portal templates.

Before Upgrading to v2026.05.12 or Later

Before upgrading to v2026.05.12 or later, audit each deployed Portal site for any hand-edited template files.

Check each site under:

/var/www/html/<site>/templates/

Look for custom changes made directly to HTML, JavaScript, or CSS files.

If customizations exist, either migrate them into:

/var/www/html/<site>/templates/local.inc.php

or keep a separate backup of the customized template files before performing the upgrade.

Backup Location After Upgrade

When upgrading to v2026.05.12 or later, a per-site copy of the previous template directory is written to:

/var/backups/xinet-portal-templates/<site>/<timestamp>/

This backup can be used after the upgrade to recover or compare previous template customizations.

Requirement for rsync

The template refresh process introduced in v2026.05.12 depends on rsync being installed on the Portal server and available on the system PATH.

If rsync is not available, installportal emits a warning and skips the template synchronization. In this case, deployed sites continue to serve their existing template files.

To apply the template refresh, install rsync and re-run installportal.

For example:

dnf install -y rsync

Then re-run:

installportal

Why This Changed

This change ensures that updated template assets shipped with new Portal releases are applied to deployed sites.

Previously, hand-edited or stale template directories could remain unchanged across upgrades. This meant important fixes or security updates in template assets might not reach end-user browsers.

For example, this change ensures updates such as the Moment.js 2.30.1 upgrade are applied correctly during the Portal upgrade process.

Summary

For Xinet Portal versions prior to v2026.05.12, custom templates stored within the configured Document Root are not modified during upgrade. Customers remaining on older versions should continue to ensure their custom templates are stored within the configured Document Root.

For Xinet Portal v2026.05.12 and later, each site’s templates/ directory is refreshed during upgrade from /usr/etc/portal/TEMPLATES/. Custom changes made directly to template files may be overwritten, except for local.inc.php.

Before upgrading to v2026.05.12 or later, review each site’s template directory, migrate supported customizations into local.inc.php, and keep backups of any custom template files.