Liferay DXP 7.0 bundled with Wildfly is available on the Help Center (DXP) or the Community Downloads page (Portal CE). The Wildfly bundle contains JARs, scripts, and configuration files required for deploying Liferay DXP 7.0. Copying these files from the Liferay DXP Wildfly bundle facilitates installing Liferay DXP on an existing Wildfly application server.
Whether you copy bundle files (recommended) or download and create the files, you must download these Additional Files for DXP or Portal CE:
- Liferay DXP WAR file
- Dependencies ZIP file
- OSGi Dependencies ZIP file
Installing Liferay DXP manually requires these basic steps:
- Installing Liferay DXP dependencies to your application server
- Configuring your application server for Liferay DXP
- Installing the Liferay DXP WAR file to your application server
Liferay Home is one folder above Wildfly’s install location.
Liferay Home
refers to the folder containing your Wildfly server folder. When Liferay DXP is
installed on Wildfly, the Liferay Home folder contains the Wildfly server folder
as well as data
, deploy
, logs
, and osgi
folders. You’ll also see the
term $WILDFLY_HOME
used in this guide. $WILDFLY_HOME
refers to your Wildfly
server folder. This folder is usually named wildfly-[version]
.
Installing Liferay DXP Dependencies
Liferay DXP depends on many JARs that are included in the Liferay DXP Wildfly bundle. Some JARs in the bundle are not strictly required but can still be useful. If you don’t have a Liferay DXP Wildfly bundle, you can download the required JARs from third-parties, as described below.
-
Create the folder
$WILDFLY_HOME/modules/com/liferay/portal/main
. Unzip the the Liferay DXP Dependencies zip file and copy the.jar
files to this folder. -
Download your database driver
.jar
file and copy it into the same folder. For example, for MySQL, download the MySQL Connector/J driver and put its.jar
file into the$WILDFLY_HOME/modules/com/liferay/portal/main
folder. -
Download the remaining required JAR and insert it into the same folder.
Be sure to remove the version number from the JAR file names or update their names where they’re defined (you’ll see where the
com.liferay.registry.api.jar
is defined next). -
Create the file
module.xml
in the$WILDFLY_HOME/modules/com/liferay/portal/main
folder and insert the following contents:<?xml version="1.0"?> <module xmlns="urn:jboss:module:1.0" name="com.liferay.portal"> <resources> <resource-root path="com.liferay.registry.api-[version].jar" /> <resource-root path="mysql-connector-java-[version]-bin.jar" /> <resource-root path="portal-kernel.jar" /> <resource-root path="portlet.jar" /> </resources> <dependencies> <module name="javax.api" /> <module name="javax.mail.api" /> <module name="javax.servlet.api" /> <module name="javax.servlet.jsp.api" /> <module name="javax.transaction.api" /> </dependencies> </module>
Make sure to replace
[version]
with the correct version of the MySQL JDBC driver. If you are using a different database, replace the MySQL.jar
with the driver JAR for your database (e.g., HSQL, PostgreSQL, etc.). -
Create an
osgi
folder in your Liferay Home folder. Then extract the OSGi ZIP file that you downloaded into theosgi
folder.Liferay DXP requires an OSGi runtime, and the
osgi
folder provides this with many required JAR files and configuration files.
Checkpoint:
- At this point, you should have the following files in the
$WILDFLY_HOME/modules/com/liferay/portal/main
folder:
com.liferay.registry.api.jar
portal-kernel.jar
portlet.jar
- a database
jar
such as the MySQL Connector.
-
The
module.xml
has listed all jars in the<resource-root-path>
elements. -
The
osgi
folder has the following subfolders:
configs
core
marketplace
target-platform
test
Great! You have your .jar
files ready.
Running Liferay DXP on Wildfly 10.0 in Standalone Mode vs. Domain Mode
Wildfly 10.0 can be launched in either standalone mode or domain mode. Domain mode allows multiple application server instances to be managed from a single control point. A collection of such application servers is known as a domain. For more information on standalone mode vs. domain mode, please refer to the section on this topic in the Wildfly 10 Admin Guide. Liferay DXP fully supports Wildfly 10.0 when it runs in standalone mode but not when it runs in domain mode.
You can run Liferay DXP on Wildfly 10.0 in domain mode, but this method is not fully
supported. In particular, Liferay DXP’s hot-deploy does not work, since Wildfly 10.0
cannot deploy non-exploded .war
files in domain mode. Instead, .war
files
are in the domain/data/content
directory. Deployments are only possible using
the command line interface. This prevents many Liferay DXP plugins from working as
intended. For example, JSP hooks don’t work on Wildfly 10.0 running in domain
mode, since Liferay DXP’s JSP override mechanism relies on the application server
reloading customized JSP files from the exploded plugin .war
file location.
Other plugins, such as service or action hooks, should still work properly since
they don’t require Wildfly to access anything (such as JSP files) from an
exploded .war
file on the file system.
Configuring Wildfly
Now you’ll make some adjustments in your configuration to support using Liferay DXP.
You can specify the Wildfly server instance’s configuration in the XML file
$WILDFLY_HOME/standalone/configuration/standalone.xml
. You must also make some
modifications to your configuration and startup scripts found in the
$WILDFLY_HOME/bin/
folder. Lastly, you’ll need to make some modifications in
your $WILDFLY_HOME/modules/
. You’ll begin with making changes to
standalone.xml
.
Make the following modifications to standalone.xml
:
-
In the
<jsp-config>
tag, set the Java VM compatibility for Liferay source and class files. They are compatible with Java 8 by default.<jsp-config development="true" source-vm="1.8" target-vm="1.8" />
-
Locate the closing
</extensions>
tag. Directly beneath that tag, insert the following system properties:<system-properties> <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8" /> <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true" /> </system-properties>
-
Add a timeout for the deployment scanner by setting
deployment-timeout="360"
as seen in the excerpt below.<subsystem xmlns="urn:jboss:domain:deployment-scanner:2.0"> <deployment-scanner deployment-timeout="360" path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" runtime-failure-causes-rollback="${jboss.deployment.scanner.rollback.on.failure:false}"/> </subsystem>
-
Add the following JAAS security domain to the security subsystem
<security-domains>
defined in element<subsystem xmlns="urn:jboss:domain:security:1.2">
.<security-domain name="PortalRealm"> <authentication> <login-module code="com.liferay.portal.kernel.security.jaas.PortalLoginModule" flag="required" /> </authentication> </security-domain>
-
Remove the following tags (if necessary):
<location name="/" handler="welcome-content"/>
<extension module="org.jboss.as.weld"/>
<subsystem xmlns="urn:jboss:domain:weld:2.0"/>
<subsystem xmlns="urn:jboss:domain:weld:3.0"/>
-
Find the
<jsp-config/>
tag and insert thedevelopment="true"
attribute into the tag. Once finished, the tag should look like the following:<jsp-config development="true" />
Checkpoint:
Before continuing, verify the following properties have been set in the standalone.xml
file:
-
A new
<system-property>
has been created. -
The
<deployment-timeout>
has been set to360
. -
A new
<security-domain>
has been created. -
Four tags have been removed.
-
<jsp-config development>
has been set totrue
.
Now it’s time for some changes to your configuration and startup scripts.
Make the following modifications to your standalone domain’s configuration
script file standalone.conf
(standalone.conf.bat
on Windows) found in your
$WILDFLY_HOME/bin/
folder.
These modifications change the following options:
- Set the file encoding
- Set the user time-zone
- Set the preferred protocol stack
- Increase the default amount of memory available.
Make the following edits as applicable to your operating system:
On Windows, comment out the initial JAVA_OPTS
assignment as demonstrated in
the following line:
rem set "JAVA_OPTS=-Xms64M -Xmx512M -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m"
Then add the following JAVA_OPTS
assignment one line above the
:JAVA_OPTS_SET
line found at end of the file:
set "JAVA_OPTS=%JAVA_OPTS% -Dfile.encoding=UTF-8 -Djava.net.preferIPv4Stack=true -Dsecmgr -Djava.security.policy=$WILDFLY_HOME/bin/server.policy -Dwildfly.home.dir=$WILDFLY_HOME -Duser.timezone=GMT -Xmx1024m -XX:MaxMetaspaceSize=384m -XX:MetaspaceSize=200m"
On Unix, merge the following values into your settings for JAVA_OPTS
,
replacing any matching attributes with the ones found in the assignment
below:
JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Djava.net.preferIPv4Stack=true -Dsecmgr -Djava.security.policy=$WILDFLY_HOME/bin/server.policy -Dwildfly.home.dir=$WILDFLY_HOME -Duser.timezone=GMT -Xmx1024m -XX:MaxMetaspaceSize=384m -XX:MetaspaceSize=200m
Make sure you replace the $WILDFLY_HOME
references with the appropriate
directory. You’ll notice some Java security options. You’ll finish configuring
the Java security options in the Security Configuration section.
Checkpoint:
At this point, you’ll have finished configuring the application server’s JVM settings.
-
The file encoding, user time-zone, preferred protocol stack have been set in the
JAVA_OPTS
in thestandalone.conf.bat
file. -
The default amount of memory available has been increased.
-
If using IBM’s JDK, the
sun crypto
properties have been set in the$WILDFLY_HOME/modules/system/layers/base/sun/jdk/main/module.xml
file.
The prescribed script modifications are now complete for your Liferay DXP installation on Wildfly. Next you’ll configure mail and the database.
Database Configuration
If you want Wildfly to manage your data source, follow the instructions in this section. If you want to use the built-in Liferay DXP data source, you can skip this section.
Modify standalone.xml
and add your data source and driver in the
<datasources>
element of your data sources subsystem.
-
First, add your data source inside the
<datasources>
element.<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url>jdbc:mysql://localhost/lportal</connection-url> <driver>mysql</driver> <security> <user-name>root</user-name> <password>root</password> </security> </datasource>
Be sure to replace the database name (i.e.
lportal
), user name, and password with the appropriate values. -
Add your driver to the
<drivers>
element also found within the<datasources>
element.<drivers> <driver name="mysql" module="com.liferay.portal"/> </drivers>
Your final data sources subsystem should look like this:
<subsystem xmlns="urn:jboss:domain:datasources:1.0">
<datasources>
<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
<connection-url>jdbc:mysql://localhost/lportal</connection-url>
<driver>mysql</driver>
<security>
<user-name>root</user-name>
<password>root</password>
</security>
</datasource>
<drivers>
<driver name="mysql" module="com.liferay.portal"/>
</drivers>
</datasources>
</subsystem>
Now that you’ve configured your data source, the mail session is next.
Mail Configuration
If you want Wildfly to manage your mail session, use the following instructions. If you want to use the built-in Liferay DXP mail session, you can skip this section.
Specify your mail subsystem in standalone.xml
as in the following example:
<subsystem xmlns="urn:jboss:domain:mail:2.0">
<mail-session jndi-name="java:jboss/mail/MailSession" name="mail-smtp">
<smtp-server ssl="true" outbound-socket-binding-ref="mail-smtp" username="USERNAME" password="PASSWORD"/>
</mail-session>
</subsystem>
...
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
...
<outbound-socket-binding name="mail-smtp">
<remote-destination host="smtp.gmail.com" port="465"/>
</outbound-socket-binding>
</socket-binding-group>
You’ve got mail! Next, you’ll make sure Liferay DXP can connect using your new mail session and database.
Configuring data sources and mail sessions
Now that your data source and mail session are set up, you need to ensure Liferay DXP can access them.
-
First, navigate to the Liferay Home folder, which is one folder above Wildfly’s install location (i.e.
$WILDFLY_HOME/..
). -
If you’re using Wildfly to manage your data source, add the following configuration to your
portal-ext.properties
file in your Liferay Home to refer to your data source:jdbc.default.jndi.name=java:jboss/datasources/ExampleDS
If you’re using Liferay DXP to manage your data source, follow the instructions for using the setup wizard.
-
If you’re using Liferay DXP to manage your mail session, this configuration is done in Liferay DXP. That is, after starting your portal as described in the Deploy Liferay DXP section, go to Control Panel → Server Administration → Mail and enter the settings for your mail session.
If you’re using Wildfly to manage your mail session, add the following configuration to your
portal-ext.properties
file to reference that mail session:mail.session.jndi.name=java:jboss/mail/MailSession
Before you deploy Liferay DXP on your Wildfly app server, you should enable and configure Java security so you can use Liferay DXP’s plugin security manager with your downloaded Liferay DXP applications.
Security Configuration
When you’re ready to begin using other people’s apps from Marketplace, you’ll want to protect your Liferay DXP instance and your Wildfly server from security threats. To do so, you can enable Java Security on your Wildfly server and specify a security policy to grant your Liferay DXP instance access to your server.
Remember, you set the -Dsecmgr
and -Djava.security.policy
Java options in
the standalone.conf.bat
file earlier in the Configuring Wildfly section. The
-Dsecmgr
Java option enables security on Wildfly. Likewise, the
-Djava.security.policy
Java option lists the permissions for your server’s
Java security policy. If you have not set these options, you’ll need to do so
before using Java security.
This configuration opens up all permissions. You can tune the permissions in
your policy later. Create the $WILDFLY_HOME/bin/server.policy
file and add the
following contents:
grant {
permission java.security.AllPermission;
};
For extensive information on Java SE Security Architecture, see its specification documents at http://docs.oracle.com/javase/7/docs/technotes/guides/security/spec/security-spec.doc.html. Also, see the Plugin Security and PACL tutorial to learn how to configure Liferay DXP plugin access to resources.
Deploy Liferay DXP
-
If the folder
$WILDFLY_HOME/standalone/deployments/ROOT.war
already exists in your Wildfly installation, delete all of its subfolders and files. Otherwise, create a new folder$WILDFLY_HOME/standalone/deployments/ROOT.war
. -
Unzip the Liferay DXP
.war
file into theROOT.war
folder. -
To trigger deployment of
ROOT.war
, create an empty file namedROOT.war.dodeploy
in your$WILDFLY_HOME/standalone/deployments/
folder. On startup, Wildfly detects the presence of this file and deploys it as a web application. -
Start the Wildfly application server by navigating to
$WILDFLY_HOME/bin
and runningstandalone.bat
orstandalone.sh
.
You’re now an expert when it comes to deploying Liferay DXP on Wildfly!