Configuring Liferay DXP Using OS Environment Variables

This article outlines how environment variables can be used to configure portal properties within Liferay DXP 7.0 for a more flexible and cloud-native approach.

Using environment variables to configure DXP 7.0 provides another option to set environment specific portal properties. This option would commonly be used when working with a container-based environment, such as Docker containers.

Table of Contents

1. Requirements
2. Environment Variables
3. Liferay Portal Properties
4. Override Priorities

Resolution

Requirements

If using DXP 7.0, the platform must have DXP 7.0 Fix Pack 24 installed.

Environment Variables

Environment variables are configured within the Operating System (OS). This means the naming convention for environment variables is also determined by the OS.

General guidelines on how to properly construct an environment variable name are:

• Names must be defined using uppercase letters, digits, and underscores.
• Names cannot begin with a digit.

For example, a common Java environment variable that is commonly used: JAVA_HOME

Liferay Portal Properties

When using environment variables, we must follow the general naming convention. But, Liferay portal properties can consist of generally disallowed characters, such as: lowercase letters, periods, brackets, etc.  To use environment variables for Liferay portal properties, we use the following naming convention, which also fulfills the general naming convention requirements mentioned above.

Liferay Naming Convention (LNC)

• Names must start with the prefix LIFERAY_
• Names are converted to lowercase by default.
• Special encodings can be used for representing generally disallowed characters by using constant names provided by DXP 7.0 or using Unicode code point.

LNC: Using Constant Names in DXP 7.0 

Using constant names for the special encoding would be the common option. The constant names allow one to utilize common characters, such as: uppercase letters, periods, brackets, etc.  A list of constant names that are available can be found in CharPool.java

In order to use constant names in Liferay, we must also follow these guidelines for the environment variable name:

• A constant name must be declared using uppercase letters.
• If there are any '_' characters in a constant name, they must be removed.
• A constant name must be declared using a wrapped pair of '_'.

Example 1: Simple Portal Property

• Portal Property: setup.wizard.enabled=false
• Environment Variable: LIFERAY_SETUP_PERIOD_WIZARD_PERIOD_ENABLED=true

How It Works:

1. The name satisfies the guidelines mentioned in the General Naming Convention section.
2. The name begins with the prefix: LIFERAY_
3. The constant name PERIOD is used by being declared as: _PERIOD_

Example 2: Complex Portal Property

• Portal Property: setup.database.driverClassName[mysql]=com.mysql.jdbc.Driver
• Environment Variable: LIFERAY_SETUP_PERIOD_DATABASE_PERIOD_DRIVER_UPPERCASEC_LASS_UPPERCASEN_AME_OPENBRACKET_MYSQL_CLOSEBRACKET_=com.mysql.jdbc.Driver

How It Works:

1. The name satisfies the guidelines mentioned in the General Naming Convention section.
2. The name begins with the prefix: LIFERAY_
3. The constant name PERIOD is used by being declared as: _PERIOD_
4. The portion, driverClassName, involves uppercase characters:
   1. The constant name UPPER_CASE_C is used by being declared as: _UPPERCASEC_

   2. The constant name UPPER_CASE_N is used by being declared as: _UPPERCASEN_

5. The portion, [mysql], involves brackets: 

   1. The constant name OPEN_BRACKET is used by being declared as: _OPENBRACKET_

   2. The constant name CLOSE_BRACKET is used by being declared as _CLOSEBRACKET_ 

LNC: Using Unicode Code Point

Using Unicode code point values for the special encoding is an option, but it is less readable than using the constant names option. A reference table of Unicode code point values can be found here: Unicode Table

In order to use Unicode code point values, we must also follow these guidelines for the environment variable name:

• A code point must be represented by decimal numbers.
• A code point must be declared using a wrapped pair of '_'.

Example 1: Simple Portal Property

• Portal Property: setup.wizard.enabled=false
• Environment Variable: LIFERAY_SETUP_46_WIZARD_46_ENABLED=true

How It Works:

1. The name satisfies the guidelines mentioned in the General Naming Convention section.
2. The name begins with the prefix: LIFERAY_
3. The ‘.’ is being represented by Unicode code point ‘46’ and is being declared as:_46_.

Example 2: Complex Portal Property

• Portal Property: setup.database.driverClassName[mysql]=com.mysql.jdbc.Driver
• Environment Variable: LIFERAY_SETUP_46_DATABASE_46_DRIVER_67_LASS_78_AME_91_MYSQL_93_=com.mysql.jdbc.Driver

How It Works:

1. The name satisfies the guidelines mentioned in the General Naming Convention section.
2. The name begins with the prefix: LIFERAY_

3. The ‘.’ is being represented by Unicode code point ‘46’ and is being declared as: _46_

4. The portion, driverClassName, involves uppercase characters:

   1. The uppercase character ‘C’ is being represented by Unicode code point ‘67’ and is being declared as: _67_

   2. The uppercase character ‘N’ is being represented by Unicode code point ‘78’ and is being declared as: _78_

5. The portion, [mysql], involves brackets:

   1. The ‘[’ is being represented by Unicode code point ‘91’ and is being declared as: _91_

   2. The ‘]’ is being represented by Unicode code point ‘93’ and is being declared as: _93_

Override Priorities

Properties configured through OS environmental variables will take priority over properties configured in portal-ext, setup-wizard, patched, and developer properties files.  However, settings established through the System Settings section of the Configuration Control Panel menu will take priority over environmental variables.

Additional Information

This feature is only available to configure portal properties.  Properties found in .config files cannot be altered through environment variables.

With this additional option to configure Liferay portal properties, it would be good practice to also include any relevant environment variables when communicating with Liferay Support representatives.

Related Links: Setting Up Java and Ant Environment Variables