Properties Files and Properties Overrides

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. The properties files may be stored relative to CATALINA_HOME or PORTAL_HOME.

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

The PORTAL_HOME location is more flexible. For this option, place the overrides.properties or uPortal_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.

There are 2 options for properties overrides:

Option 1: overrides.properties (also used by portlets)

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

Option 1 (overrides.properties) should be used for properties such as database connection values that the portlets could also use since they may load those property files. See the section 'Portlet Properties Overrides recommendation' below. If you are security conscious (running some untrusted portlets) and you have values for some reason you don't want portlets to have access to or the property name value conflicts with values used by a portlet, store the values in uPortal_overrides.properties.

new with uPortal 4.3.0: Option 2: uPortal_overrides.properties

${CATALINA_HOME}/portal/uPortal_overrides.properties
${PORTAL_HOME}/uPortal_overrides.properties

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. See

Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.

, Unable to locate Jira server for this macro. It may be due to Application Link configuration. , and linked issues.

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