Properties Files and Properties Overrides

Owned by Andrew Wills (Deactivated)
Last updated: Jan 16, 2015 by James Wennmacher (Deactivated)
2 min read

uPortal is a Spring-configured Java web application, and as such it primarily uses XML-based Spring context files for configuration.  (See the sections on User Attributes & Authenticating Against LDAP for examples.)  Nevertheless, many important configuration settings are managed in Java properties files.  These files are then "read in" by the Spring context, and their values are used to configure the beans at the heart of uPortal.

These files include:

  • uportal-war/src/main/resources/properties/portal.properties (general settings)
  • uportal-war/src/main/resources/properties/rdbm.properties (database connection settings)
  • uportal-war/src/main/resources/properties/security.properties (authentication settings)

Maven Filters

NOTE: Some settings controlled by these files are not normally configured directly within them in uPortal source code. uPortal manages most environment-specific* settings in special files called "filters files:" these are located in the filters/ directory, and their values are injected into the above properties files at build time by Maven.

*Environment-specific settings are those that are likely to be different for each environment, e.g. DEV, TEST, PROD.

Properties Overrides

Beginning with version 4.0.10, uPortal provides an optional mechanism to override these settings with a file that is completely outside uPortal source, the build/deploy system, and even Tomcat.  This approach allows systems administrators to change these settings without rebuilding.  It also provides an easy way for adopters to keep sensitive information outside of their Source Code Management system.

There are 2 options for properties overrides

  1. ${CATALINA_HOME}/portal/overrides.properties
  2. ${PORTAL_HOME}/overrides.properties

The first of these (#1) is a canonical location approach:  simply create a portal/ directory within your Tomcat root (CATALINA_HOME) and place a file named overrides.properties within it.  Use this option if this location works for you.

The second approach (#2) is more flexible.  For this option, place the overrides.properties file anywhere you want, then set PORTAL_HOME as an environment variable or pass it as a JVM argument (e.g. -DPORTAL_HOME=/my/chosen/location).

In either case, you choose which properties to override.  As the name suggests, values in overrides.properties will trump (override) values set elsewhere.

Portlet Properties Overrides recommendation

Though not required, it's recommended that portlets load property override values using the following locations.  This allows portlets to share property values with each other and with uPortal, in particular the Hibernate DB connection property values.

  • ${CATALINA_HOME}/portal/overrides.properties
  • ${CATALINA_HOME}/portal/{portletName}_overrides.properties
  • ${PORTAL_HOME}/overrides.properties
  • ${PORTAL_HOME}/{portletName}_overrides.properties