Submit Feedback

Portal Properties

Configuration options are specified using Portal Properties, sets of name/value pairs read from properties files and Docker environment variables on server startup. Default values are specified in the portal-impl.jar/portal.properties file.

Some properties can be changed through the user interface (UI), but others can only be changed in a properties file or Docker environment variables. These include connecting to a database, declaring the location of the Liferay Home folder, and changing how users authenticate (by screen name instead of by email address).

Liferay installations use properties files. By convention, portal-ext.properties should be created in your [Liferay Home] folder or [USER_HOME] folder to override default property values. You must restart DXP to apply a new or modified properties file.

Warning

Never directly modify the portal-impl.jar/portal.properties file; instead, create a separate file to override properties you want to change. The portal-ext.properties file has been defined for this purpose.

Using a portal-ext.properties file to override default properties has these benefits:

You can copy the file to other Liferay DXP environments and server nodes.
You can store configurations in a version control system to simplify configuration management.
Setting properties in the file before initial startup is the quickest way to configure Liferay.

Portal properties are applied to Liferay Docker containers with environment variables (Env variables) and properties files. Please see Configuring Containers to configure Docker containers with portal properties.

Contents:

Using Portal Properties
Portal Property Priority
Using System Settings and Configuration Files

Note

As of DXP 7.3, the per-virtual instance portal properties file feature has been removed. DXP no longer applies per-instance properties from files of the format portal-[companyId].properties to instances matching the company IDs.

Using Portal Properties

When creating [Liferay Home]/portal-ext.properties, a best practice is to copy the relevant section from portal-impl.jar/portal.properties into your portal-ext.properties file, and then change the value to what you want.

Note

If you use the Setup Wizard, DXP sets those properties in a file called portal-setup-wizard.properties in [Liferay Home].

Here are a few configuration examples.

Setting a Database Connection

Database connection properties are most commonly set in a portal-ext.properties file. If you want to change the database connection, for example, create a portal-ext.properties file and set the database connection properties to the values you want:

jdbc.default.driverClassName=org.mariadb.jdbc.Driver
jdbc.default.url=jdbc:mariadb://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
jdbc.default.username=joe.bloggs
jdbc.default.password=123456

For more database configuration details, see Database Configurations and Database Templates.

Setting the Liferay Home Location

Some application servers (e.g., WebLogic) require customizing the Liferay Home location before deploying the DXP WAR file. The liferay.home property sets the location.

liferay.home=/home/jbloggs/liferay

Changing How Users Authenticate

To change how users authenticate, add one of the following company.security.auth.type property values.

company.security.auth.type=emailAddress

company.security.auth.type=screenName

company.security.auth.type=userId

Portal Property Priority

Portal properties are set from three sources:

The portal.properties bundled in the portal-impl.jar
Extension properties files (e.g., portal-ext.properties)
Environment variables

For a given property, the last value read takes priority. The property sources are read in a deterministic order that is configurable through a property called include-and-override.

Configuration Processing

By default, properties are read in this order:

portal-impl.jar/portal.properties
include-and-override=portal-bundle.properties
include-and-override=${liferay.home}/portal-bundle.properties
include-and-override=portal-ext.properties
include-and-override=${liferay.home}/portal-ext.properties
include-and-override=portal-setup-wizard.properties
include-and-override=${liferay.home}/portal-setup-wizard.properties
include-and-override=${external-properties}
include-and-override=${liferay.home}/${external-properties}
[Added `include-and-override` files]
[Liferay Docker Env variables]

The portal-impl.jar/portal.properties file specifies the above include-and-override definitions. If any other valid properties source defines additional or competing include-and-override property values, these are used to override the defaults.

The list of included extension files your DXP server is using is available in the Server Administration page of the Control Panel's Configuration section

The ${external-properties} definition represents any properties file assigned to DXP’s Java property external-properties (for example, -Dexternal-properties=some.properties).

Liferay Docker containers aggregate Liferay environment variables into a Portal Properties source that’s added to the list.

Important

If you override a property in more than one file, the last defined property source wins. All others are ignored.

Portal Property Priority Examples

The following examples demonstrate how properties sources and specific properties configure DXP.

Example 1: Using `portal-ext.properties` to Override a Property

If you’ve configured a mail session on your application server and it’s named differently than the default in portal-impl.jar/portal.properties (it sets mail.session.jndi.name=mail/MailSession), specify your mail session name in a portal-ext.properties file.

New value in portal-ext.properties:

mail.session.jndi.name=mail/SomeMailSession

Resulting properties source order:

portal-impl.jar/portal.properties
[Liferay Home]/portal-ext.properties

The last value defined for mail.session.jndi.name is in [Liferay Home]/portal-ext.properties.

Resulting configuration:

mail.session.jndi.name=mail/SomeMailSession

Example 2: Adding a Properties File

You can add a properties file for a specific environment, such as a development environment. Then you can use a single portal-ext.properties for common properties, and an environment-specific configuration for others.

Create an arbitrary extension file (e.g., portal-developer.properties) for your environment and add environment-specific properties to it:
```
mail.session.jndi.name=mail/DevMailSession
```
Include the new extension file as a properties source by adding this include-and-override property to the top of your portal-ext.properties file:
```
include-and-override=portal-developer.properties
```

Resulting properties source order:

portal-impl.jar/portal.properties
[Liferay Home]/portal-ext.properties
[Liferay Home]/portal-developer.properties

The last value defined for mail.session.jndi.name is in [Liferay Home]/portal-developer.properties.

Resulting configuration:

mail.session.jndi.name=mail/DevMailSession

Tip

Using as few properties files as necessary simplifies managing DXP configuration.

Using System Settings and Configuration Files

Some properties can be set using System Settings and Configuration Files. The SAML authentication properties, for example, are properties available in System Settings.

Properties stored in the DXP database are prioritized over properties set in Portal Properties files.

Go to Control Panel at Configuration → System Settings to find System Settings. System Settings can be exported as .config files to save in source control and use in distributed DXP installations. Portal properties set via System Settings and configuration files are stored in the database. Some properties are applied immediately while others require restarting the server.