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:
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]
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:
-
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]
-
Copy the
setenv.sh
file from the container.docker cp tmp-dxp:/opt/liferay/tomcat/bin/setenv.sh .
-
Set the JVM options in your copy of
setenv.sh
. -
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
-
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.
Please see Providing Files to the Container for more information on bind mounting to to the container’s /mnt/liferay
folder.
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
There’s an Env variable for each Portal Property. Env variables are Docker environment variables that override a Liferay Docker container’s Portal Properties.
-
In the Portal Properties online description, find the property you want to override.
-
Copy the
Env
variable name displayed just below the property description. For example, here’s the Env variable for thejdbc.default.jndi.name
Portal Property:Env: LIFERAY_JDBC_PERIOD_DEFAULT_PERIOD_JNDI_PERIOD_NAME
-
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]
warningIn the
Env
variable value, use backslashes to escape space characters. Don’t use quotes.noteSee Database Templates for database environment variable examples.
noteSee 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.
-
Create a host folder and a subfolder called
files
.mkdir -p [host folder]/files
-
Add your property overrides to a
portal-ext.properties
file in thefiles
subfolder you created. For example,echo "jdbc.default.jndi.name=jdbc/MyPool" >> [host folder]/files/portal-ext.properties
-
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’sportal-ext.properties
is in a folder calledfiles
, 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.
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:
-
Use the image-defined defaults. They’re set automatically.
-
Override a default value by setting the environment variable when running the container. For example,
docker run -e [variable]=[value] ...
. -
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:
-
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
-
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
-
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.
-
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
-
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
-
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]
notePlease 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:
-
Create a host folder and subfolders to make the path
[host folder]/files/osgi/configs
.mkdir -p [host folder]/files/osgi/configs
-
Copy your
.config
files to the host folder’sfiles/osgi/configs
subfolder. For example,cp ~/*.config [host folder path]/files/osgi/configs
-
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]
notePlease 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.