Configuring Containers

Everything that is configurable in a Liferay installation is configurable in a Liferay Docker container.

Here are the most common things to configure:

• JVM Options
• Portal Properties
• Image-defined Environment Variables
• System Properties
• System Settings

note

The configuration use cases that involve providing a file to the container are demonstrated here using bind mounts. You can also use volumes and in some cases, use a docker cp command. See Providing Files to the Container for more information.

JVM Options

Tomcat’s JVM options can be appended or replaced.

Appending JVM Options to CATALINA_OPTS

JVM options can be appended to Tomcat’s CATALINA_OPTS variable by specifying them in a LIFERAY_JVM_OPTS environment variable when you create the container.

docker run -it -m 8g -p 8080:8080 -e LIFERAY_JVM_OPTS=[value\ with\ space] liferay/dxp:[tag]

warning

In the LIFERAY_JVM_OPTS value, use backslashes to escape space characters. Don’t use quotes.

The container runs with the LIFERAY_JVM_OPTS value appended to Tomcat’s CATALINA_OPTS.

Replacing the setenv.sh File

Another method of configuring JVM options involves overriding Tomcat’s setenv.sh script. A fast way to create a setenv.sh script is to copy one from a Liferay container. Here’s how to modify a copy of the script and use it in a new container:

1. If you have an existing Liferay container, start it. Otherwise, run a new one.

   docker run -it --name tmp-dxp -p 8080:8080 liferay/dxp:[tag]
   

2. Copy the setenv.sh file from the container.

   docker cp tmp-dxp:/opt/liferay/tomcat/bin/setenv.sh .
   

3. Stop the container.

4. Set the JVM options in your copy of setenv.sh.

5. Create a host folder and subfolders to create the path files/tomcat/bin.

   mkdir -p [host folder]/files/tomcat/bin
   cp setenv.sh [host folder]/files/tomcat/bin
   

6. Run a new container with a -v option that bind mounts to your host folder:

   docker run -it -m 8g -p 8080:8080 -v [host folder path]:/mnt/liferay liferay/dxp:[tag]
   

The container uses your setenv.sh script’s JVM options.

note

Please see Providing Files to the Container for more information on bind mounting to to the container’s /mnt/liferay folder.

note

See Using Liferay Docker Images for details on starting and operating Liferay containers.

Portal Properties

Container Portal Properties can be overridden in these two ways:

• Using Liferay Env Variables
• Using a Portal Properties File

Using Liferay Env Variables

There’s an Env variable for each Portal Property. Env variables are Docker environment variables that override a Liferay Docker container’s Portal Properties.

1. In the Portal Properties online description, find the property you want to override.

2. Copy the Env variable name displayed just below the property description. For example, here’s the Env variable for the jdbc.default.jndi.name Portal Property:

   Env: LIFERAY_JDBC_PERIOD_DEFAULT_PERIOD_JNDI_PERIOD_NAME
   

3. Create a container, passing in your Env variable assignments using -e options following the pattern -e VARIABLE_A=value -e VARIABLE_B=value .... For example,

   docker run -it -m 8g -p 8080:8080 -e LIFERAY_JDBC_PERIOD_DEFAULT_PERIOD_JNDI_PERIOD_NAME=jdbc/MyPool liferay/dxp:[tag]
   

   warning

   In the Env variable value, use backslashes to escape space characters. Don’t use quotes.

   note

   See Database Templates for database environment variable examples.

   note

   See Using Liferay Docker Images for details on starting and operating the containers.

The properties are visible in the Control Panel at Configuration → Server Administration → Properties → Portal Properties.

Using a Portal Properties File

You can override a container’s Portal Properties using a portal-ext.properties file. This example uses a bind mount.

1. Create a host folder and a subfolder called files.

   mkdir -p [host folder]/files
   

2. Add your property overrides to a portal-ext.properties file in the files subfolder you created. For example,

   echo "jdbc.default.jndi.name=jdbc/MyPool" >> [host folder]/files/portal-ext.properties
   

3. Create a container, that includes a bind mount that maps your portal-ext.properties file’s folder to the container’s /mnt/liferay/files folder. Since this example’s portal-ext.properties is in a folder called files, you can bind mount to the container’s /mnt/liferay folder.

   docker run -it -m 8g -p 8080:8080 -v [host folder path]:/mnt/liferay liferay/dxp:[tag]
   

The properties are visible in the Control Panel at Configuration → Server Administration → Properties → Portal Properties.

note

See Database Templates for database portal property examples.

Image-Defined Environment Variables

Liferay images define several environment variables. Some of the variables configure internal things, such as the Liferay Home path and the option to start Tomcat in debug mode. Other variables set Portal Properties. Here are the image-defined environment variables that set Portal Properties.

LIFERAY_MODULE_PERIOD_FRAMEWORK_PERIOD_PROPERTIES_PERIOD_OSGI_PERIOD_CONSOLE=0.0.0.0:11311
LIFERAY_SETUP_PERIOD_WIZARD_PERIOD_ADD_PERIOD_SAMPLE_PERIOD_DATA=false
LIFERAY_SETUP_PERIOD_WIZARD_PERIOD_ENABLED=false
LIFERAY_TERMS_PERIOD_OF_PERIOD_USE_PERIOD_REQUIRED=false
LIFERAY_USERS_PERIOD_REMINDER_PERIOD_QUERIES_PERIOD_ENABLED=false

Environment variables that correspond to Portal Properties are prioritized over Portal Properties file settings.

All Docker environment variables, including the ones above, are immutable. If you set any environment variables or rely on the Liferay image-defined environment variables, make sure the have the values you want.

Environment Variable Options

Here are the options for working with image-defined environment variables:

1. Use the image-defined defaults. They’re set automatically.

2. Override a default value by setting the environment variable when running the container. For example, docker run -e [variable]=[value] ....

3. Disable an environment variable by declaring it with no assignment (i.e., no = character). Here’s the format: -e [varable]

   Disabling an image-defined Portal Property environment variable gives you flexibility to specify the value you want in a Portal Properties file on container startup. For example,

   docker run -e [varable] -v [host folder path]:/mnt/liferay ...
   

Example: Working with an Image-Defined Portal Property Environment Variable

The following image-defined Portal Property environment variable declares that users don’t have to agree to your terms of use.

LIFERAY_TERMS_PERIOD_OF_PERIOD_USE_PERIOD_REQUIRED=false

Here’s how to disable it and work with it using a Portal Properties file:

1. Disable the environment variable and set a bind mount for a Portal Properties file:

   docker run -e LIFERAY_TERMS_PERIOD_OF_PERIOD_USE_PERIOD_REQUIRED -v $(pwd):/mnt/liferay ...
   

   The terms of use requirement is based on your Portal Properties. The default Portal Property setting (search for LIFERAY_TERMS_PERIOD_OF_PERIOD_USE_PERIOD_REQUIRED) requires the terms of use:

   terms.of.use.required=true
   

2. Specify the setting you want in a portal-ext.properties file that is in your bind mount path. See using a Portal Properties file.

   echo "terms.of.use.required=false" >> ./files/portal-ext.properties
   

3. Restart the container.

The container uses your property setting.

System Properties

System Properties can be overridden using a system-ext.properties file. This example uses a bind mount.

1. Create a host folder and subfolders to create the path [host folder]/files/tomcat/webapps/ROOT/WEB-INF/classes.

   mkdir -p [host folder]/files/tomcat/webapps/ROOT/WEB-INF/classes
   

2. Add your property overrides to a system-ext.properties file in the [host folder]/files/tomcat/webapps/ROOT/WEB-INF/classes folder you created. For example,

   echo "net.sf.ehcache.skipUpdateCheck=false" >> [host folder]/files/tomcat/webapps/ROOT/WEB-INF/classes/system-ext.properties
   

3. Run a new container with a -v option that bind mounts to your host folder:

   docker run -it -m 8g -p 8080:8080 -v [host folder path]:/mnt/liferay liferay/dxp:[tag]
   

   note

   Please see Providing Files to the Container for more information on bind mounting to to the container’s /mnt/liferay folder.

The properties are visible in the Control Panel at Configuration → Server Administration → Properties → System Properties.

System Settings

Liferay System Settings can be configured in the Control Panel or by providing Configuration Files (.config files) to the container. You can create a .config file from scratch or by exporting the component configuration values from the UI.

Modify the System Settings using one of these ways:

• Applying Configurations to a New Container
• Applying Configuration Files at Run Time
• Using the Control Panel

Applying Configurations to a New Container

If you have not yet created a container, follow these steps to provide a .config file to a new container using a bind mount:

1. Create a host folder and subfolders to make the path [host folder]/files/osgi/configs.

   mkdir -p [host folder]/files/osgi/configs
   

2. Copy your .config files to the host folder’s files/osgi/configs subfolder. For example,

   cp ~/*.config [host folder path]/files/osgi/configs
   

3. Run the container with a -v option that bind mounts your host folder:

   docker run -it -m 8g -p 8080:8080 -v [host folder path]:/mnt/liferay liferay/dxp:[tag]
   

   note

   Please see Providing Files to the Container for more information on bind mounting to to the container’s /mnt/liferay folder.

The system component configurations are visible in the Control Panel at Configuration → System Settings, in the screen for that component.

Applying Configuration Files at Run Time

If you have a container already, you can copy .config files to your container at run time using a docker cp command like this one:

docker cp [config file] [container]:/opt/liferay/osgi/configs

Conclusion

Now you know how to configure a Liferay container’s JVM options, Portal Properties, image Env variable, System Properties, and System Settings.

Related Topics

• Using Liferay Docker Images
• Container Lifecycle and API
• Providing Files to the Container
• Installing Apps and Other Artifacts to Containers
• Patching DXP in Docker