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
In this article, you’ll step through these basic steps and install Liferay DXP on your existing JBoss EAP 6.4 application server. Before proceeding, you must download these Additional Files:
- Liferay DXP WAR file
- Dependencies ZIP file
- OSGi Dependencies ZIP file
Liferay Home is one folder above JBoss’s install location.
Liferay Home
refers to the folder containing your JBoss server folder. When Liferay DXP is
installed on JBoss, the Liferay Home folder contains the JBoss server folder as
well as data
, deploy
, logs
, and osgi
folders. You’ll also see the term
$JBOSS_HOME
used in this guide. $JBOSS_HOME
refers to your JBoss server
folder. This folder is usually named jboss-eap-[version]
.
Installing Liferay DXP Dependencies
Liferay DXP depends on many JARs that are included in the Liferay DXP JBoss bundle. Some JARs in the bundle are not strictly required but can still be useful. You can download the required JARs from third-parties, as described below.
-
Create the folder
$JBOSS_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$JBOSS_HOME/modules/com/liferay/portal/main
folder. -
Download the com.liferay.registry.api.jar JAR and insert it into the same folder.
-
Create the file
module.xml
in the$JBOSS_HOME/modules/com/liferay/portal/main
folder and insert the following contents:<?xml version="1.0"?> <module name="com.liferay.portal" xmlns="urn:jboss:module:1.0"> <resources> <resource-root path="com.liferay.registry.api.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:
-
Inside the
$JBOSS_HOME/modules/com/liferay/portal/main
folder, verify that the following are present:a.
com.liferay.registry.api.jar
b.portal-kernel.jar
c.portlet.jar
d. (database of your choicejar
) (e.g. MySQL, SQL Server…) -
Inside the
osgi
folder, verify the following folders are present:a.
configs
b.core
c.marketplace
d.target-platform
e.test
Running Liferay DXP on JBoss EAP 6.4 in Standalone Mode vs. Domain Mode
JBoss EAP 6.4 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 JBoss EAP 6.4 Administration and Configuration Guide. Liferay DXP fully supports JBoss EAP 6.4 when it runs in standalone mode but not when it runs in domain mode.
You can run Liferay DXP on JBoss EAP 6.4 in domain mode, but this method is not
fully supported. In particular, Liferay DXP’s hot-deploy does not work, since JBoss
EAP 6.4 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 JBoss EAP 6.4 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 JBoss to access anything (such as JSP files)
from an exploded .war
file on the file system.
Configuring JBoss
Now you’ll make some adjustments in your configuration to support using Liferay DXP.
You can specify the JBoss server instance’s configuration in the XML file
$JBOSS_HOME/standalone/configuration/standalone.xml
. You must also make some
modifications to your configuration and startup scripts found in the
$JBOSS_HOME/bin/
folder. Lastly, you’ll need to make some modifications in
your $JBOSS_HOME/modules/
. You’ll begin with making changes to
standalone.xml
.
Make the following modifications to standalone.xml
:
-
In the
<jsp-configuration>
tag, set the Java VM compatibility for Liferay source and class files. They are compatible with Java 8 by default.<jsp-configuration 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"/> </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>
-
Disable the default JBoss Welcome page by setting the
enable-welcome-root
attribute tofalse
, as seen in the snippet below.<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false"> <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/> <virtual-server name="default-host" enable-welcome-root="false"> ...
-
In the same
<subsystem ... />
element that was outlined in the previous step, add the following snippet above the<connector ... />
element:<configuration> <jsp-configuration source-vm="1.8" target-vm="1.8" development="true" /> </configuration>
Checkpoint:
-
The
standalone.xml
has been modified with the following values:a.
deployment-timeout="360"
has been set. The value is in seconds. b. The JAAS security domain has been added. c. The propertyenable-welcome-root="false"
has been set. d. The propertyjsp-configuration source-vm="1.8" target-vm="1.8" development="true"
has been set in the<configuration>
element. This is required because Liferay DXP runs on Java JDK 1.8 or else there will be a JasperException and the instance will fail to start.
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
$JBOSS_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=-Xms1G -Xmx1G -XX:MaxPermSize=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=$JBOSS_HOME/bin/server.policy -Djboss.home.dir=$JBOSS_HOME -Duser.timezone=GMT -Xmx1024m -XX:MaxMetaspaceSize=384m"
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=$JBOSS_HOME/bin/server.policy -Djboss.home.dir=$JBOSS_HOME -Duser.timezone=GMT -Xmx1024m -XX:MaxMetaspaceSize=384m"
Make sure you replace the $JBOSS_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:
-
The
standalone.conf.bat
file has been updated with the following changes:a. UTF-8 file encoding b. The user time-zone c. The preferred protocol stack d. Increased the default amount of memory available.
-
If using the IBM JDK with the JBoss server,
<module name="ibm.jdk" />
has been added to the$JBOSS_HOME/modules/com/liferay/portal/main/module.xml
file. -
The additional IBM JDK paths have been set in the
$JBOSS_HOME/modules/system/layers/base/sun/jdk/main/module.xml
file.
The prescribed script modifications are now complete for your Liferay DXP installation on JBoss. Next you’ll configure mail and the database.
Database Configuration
If you want JBoss 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.2">
<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 JBoss 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:1.2">
<mail-session jndi-name="java:jboss/mail/MailSession" >
<smtp-server ssl="true" outbound-socket-binding-ref="mail-smtp">
<login username="USERNAME" password="PASSWORD"/>
</smtp-server>
</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 7.0 can access them.
-
First, navigate to the Liferay Home folder, which is one folder above JBoss’s install location (i.e.
$JBOSS_HOME/..
). -
If you’re using JBoss 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 7.0 to manage your data source, follow the instructions for using the setup wizard.
-
If you’re using Liferay DXP 7.0 to manage your mail session, this configuration is done in Liferay DXP 7.0. 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 JBoss 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 7.0 on your JBoss 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 JBoss server from security threats. To do so, you can enable Java Security on your JBoss 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 JBoss section. The
-Dsecmgr
Java option enables security on JBoss. 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 $JBOSS_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
$JBOSS_HOME/standalone/deployments/ROOT.war
already exists in your JBoss installation, delete all of its subfolders and files. Otherwise, create a new folder$JBOSS_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$JBOSS_HOME/standalone/deployments/
folder. On startup, JBoss detects the presence of this file and deploys it as a web application. -
Start the JBoss application server by navigating to
$JBOSS_HOME/bin
and runningstandalone.bat
orstandalone.sh
.
The JBoss application server starts and deploys Liferay DXP.
You’re now an expert when it comes to deploying Liferay DXP on JBoss!