Setting Up Liferay Portal on JBoss 6 EAP

This article will outline how to set up JBoss 6 EAP and deploy Liferay 6.1 EE and 6.2 EE to this application server.

Resolution

Before You Begin, download JBoss EAP 6.0.1 or 6.1, and install it to your preferred location, henceforth referred to as $JBOSS_HOME.

Please Note: Liferay Home defaults to the directory containing JBoss. This can be modified via the following property:

##
## Liferay Home ##
#
# Specify the Liferay home directory. #
liferay.home=${resource.repositories.root}

Also note: The desired version of the Liferay WAR can be found on the Help Center (https://www.help.liferay.com). The Liferay dependencies for the desired version are found on the Help Center (https://www.help.liferay.com)

Dependency Jars

1. Create folder $JBOSS_HOME/modules/com/liferay/portal/main, and unzip the jar files found in the Liferay Portal Dependencies zip file to this folder. 

2. Download the database driver .jar file and put it into the $JBOSS_HOME/modules/com/liferay/portal/main folder as well. For example, download the MySQL Connector driver from http://dev.mysql.com/downloads/connector/j/ and put its .jar file into the $JBOSS_HOME/modules/com/liferay/portal/main folder.

3. Create the file module.xml in the $JBOSS_HOME/modules/com/liferay/portal/main folder and insert the following lines:

<?xml version="1.0"?>
<module xmlns="urn:jboss:module:1.0"name="com.liferay.portal">
    <resources>
        <resource-root path="mysql-connector-[versionHere]-bin.jar" />
        <resource-root path="portal-service.jar" />
        <resource-root path="portlet.jar" />
    </resources>
    <dependencies>
        <module name="javaxapi" />
        <module name="javaxmailapi" />
        <module name="javaxservletapi" />
        <module name="javaxservletjspapi" />
        <module name="javaxtransactionapi" />
    </dependencies>
</module>

For all other database drivers, replace the path of the MySQL resource root entry with the name of the database connector jar.

Running Liferay On Jboss 6 EAP In Standalone Mode Vs. Domain Mode

JBoss 6 EAP 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 6 EAP Admin Guide. Liferay fully supports JBoss 6 EAP when it runs in standalone mode but not when it runs in domain mode.

You can run Liferay on JBoss 6 EAP in domain mode, but this method is not fully supported. In particular, Liferay’s hot-deploy does not work, since JBoss 6 EAP 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 plugins from working as intended. For example, JSP hooks don’t work on JBoss 6 EAP running in domain mode, since Liferay’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.

Note: This does not prevent Liferay from running in a clustered environment on multiple JBoss servers. You can set up a cluster of Liferay instances running on JBoss 6 EAP servers running in standalone mode. Please refer to the chapter of this guide on Configuring Liferay for High Availability for information on setting up a Liferay cluster.

Configuring JBoss

Specify the JBoss server instance's configuration in the XML file $JBOSS_HOME/standalone/configuration/standalone.xml. Users must also make some modifications to their configuration and startup scripts found in the $JBOSS_HOME/bin/ folder.

Modify standalone.xml

1. Disable the welcome root of the web subsystem's virtual server default host by specifying enable-welcome-root="false".

<subsystem xmlns="urn:jboss:domain:web:1.1"default-virtual-server="defaulthost">
    <connector name="http" scheme="http" protocol="HTTP/1.1" socket-binding="http"/>
    <virtual-server name="defaulthost" enable-welcome-root="false">
        <alias name="localhost" />
        <alias name="examplecom" />
    </virtual-server>
</subsystem>

2. Insert the following <configuration> element within the web subsystem element

<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="defaulthost">.

<configuration>
    <jsp-configuration development="true" />
</configuration>

3. Add a timeout for the deployment scanner by setting deployment-timeout="240" as seen in the excerpt below.

<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
    <deployment-scanner name="default"
            path="deployments"
            scan-enabled="true"
            scan-interval="5000"
            relative-to="jboss.server.base.dir"
            deployment-timeout="240"/>
</subsystem>

4. 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.security.jaas.PortalLoginModule" flag="required"/>
    </authentication>
</security-domain>


5. Add the following system properties between the </extensions> and <management> tags:

<system-properties>
    <property name="orgapachecatalinaconnectorURI_ENCODING" value="UTF-8" />
    <property name="orgapachecatalinaconnectorUSE_BODY_ENCODING_FOR_QUERY_STRING" value="true" />
</system-properties>
 

Modify the module.xml

The file is located in  $JBOSS_HOME/modules/sun/jdk/ main

Add the following in the <paths>...</paths> element:

​<path name="com/sun/crypto"/>
<path name="com/sun/crypto/provider"/>
<path name="com/sun/image/codec/jpeg" />
<path name="com/sun/org/apache/xml/internal/resolver" />
<path name="com/sun/org/apache/xml/internal/resolver/tools" />

Configuration and Startup Scripts

1. Modify the standalone domain's configuration script file standalone.conf (standalone.conf.bat for Windows) found in the $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.

To configure the JVM settings on Windows:

  • On Windows, comment out the initial JAVA_OPTS assignment as demonstrated in the following line:

    Rem # set "JAVA_OPTS=-Xms64M -Xmx512M -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 -Djava.security.manager -Djava.security.policy=%JBOSS_HOME%/bin/server.policy -Djboss.home.dir=$JBOSS_HOME -Duser.timezone=GMT -Xmx1024m-XX:MaxPermSize=256m"​

To configure JVM settings on UNIX/Linux:

  • On Unix, merge the following values for JAVA_OPTS like so:
    if [ "x$JAVA_OPTS" = "x" ]; then
    JAVA_OPTS="-Xms1303m -Xmx1303m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Djava.net.preferIPv4Stack=true"
    JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Djava.security.policy=server.policy -Djboss.home.dir=$JBOSS_HOME -Duser.timezone=GMT -Xmx2048m -XX:MaxPermSize=256m -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"

2. Database Configuration

If using JBoss to manage the data source, follow the instructions in this section. If using the built-in Liferay data source, skip this section.

In the standalone.xml, add the data source and driver within the <datasources> element of the data sources subsystem.

  1. First, add the data source within the <datasources> element in <subsystem xmlns="urn:jboss:domain:datasources:1.1">
        <datasource jndi-name="javajdbcLiferayPool" pool-name="LiferayPool" 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 URL database value (i.e. lportal), user value and password value with values specific to the database.

  2. Then add the driver to the <drivers> element also found within the <datasources> element.
        <drivers><driver name="mysql" module="comliferayportal"/></drivers>
       

The final datasources subsystem should look something like this:

<subsystem xmlns="urn:jboss:domain:datasources:1.1">
    <datasources>
        <datasource jndi-name="javajdbcLiferayPool"
                pool-name="LiferayPool"
                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="comliferayportal"/>
        </drivers>
    </datasources>
</subsystem>

 

Mail Configuration

At the time this document was written, JavaMail was not yet supported in JBoss AS 7.0.1 - however, it was implemented in the JBoss AS 7.1 alpha (see https://issues.jboss.org/browse/AS7-1177). If users wish to have JBoss to manage their mail session, use the following instructions which are based on the implementation found in JBoss AS7.1 alpha. If users want to use the built-in Liferay mail session, skip this section.

Verify that the standalone.xml is configured as in the following example:

<subsystem xmlns="urn:jboss:domain:mail:1.0">
    <mail-session jndi-name="javamailMailSession" >
        <smtp-server address="smtp.gmail.com" port="465">
            <login name="username" password="password"/>
        </smtp-server>
        <pop3-server address="pop.gmail.com" port="110"/>
        <imap-server address="imap.gmail.com" port="993">
            <login name="username" password="password"/>
        </imap-server>
    </mail-session>
</subsystem>

Configuring data sources and mail sessions

  1. First, navigate to the Liferay Home folder, which is one folder above JBoss's install location (i.e. $JBOSS/..).
  2. If using JBoss to manage the data source, add the following to the portal-ext.properties file in the Liferay Home to refer to use data source:

    jdbc.default.jndi.name=java:jdbc/LiferayPool

  3. If using Liferay Portal to manage the data source, follow the instructions in the Deploy Liferay section for using the setup wizard.
  4. If using Liferay Portal to manage the mail session, this configuration is done within Liferay Portal.
  5. Go to Control Panel > Server Administration > Mail and enter the settings for the mail session.
  6. If using JBoss to manage the mail session, add the following to the portal-ext.properties file to reference that mail session:

    mail.session.jndi.name=java:mail/MailSession

SECURITY CONFIGURATION

When you’re ready to begin using other people’s apps from Marketplace, you’ll want to protect your portal 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 portal access to your server.

Remember, we set the -Djava.security.manager and -Djava.security.policy Java options in the standalone.conf.bat file earlier in the Configuring JBoss section. The -Djava.security.manager 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 section Understanding Plugin Security Management in the Developer’s Guide to learn how to configure Liferay plugin access to resources.

Deploy Liferay

  1. If the folder $JBOSS_HOME/standalone/deployments/ROOT.war already exists, delete all of its subfolders and files. Otherwise, create a new folder $JBOSS_HOME/standalone/deployments/ROOT.war.
  2. Unzip the Liferay .war file into the ROOT.war folder.
  3. In the ROOT.war file, open the WEB-INF/jboss-deployment-structure.xml file. In this file, replace the <module name="comliferayportal" /> dependency with the following configuration:

    <module meta-inf="export" name="com.liferay.portal">
        <imports>
            <include path="META-INF" />
        </imports>
    </module>

    This allows OSGi plugins like Audience Targeting to work properly, by exposing the Portal API through the OSGi container.

  4. To trigger deployment of ROOT.war, create an empty file named ROOT.war.dodeploy in the $JBOSS_HOME/standalone/deployments/ folder. On startup, JBoss detects the presence of this file and deploys it as a web application.
  5. Remove the eclipselink.jar from $JBOSS_HOME/standalone/deployments/ROOT.war/WEB-INF/lib to assure the Hibernate persistence provider is used instead of the one provided in the eclipselink.jar.
  6. If this is the first time starting Liferay Portal, the setup wizard is invoked on server startup. If users want to re-run the wizard, specify setup.wizard.enabled=true in the properties file (e.g. portal-setup-wizard.properties). Start the setup wizard along with Liferay Portal - Do this if users want to configure the portal, set up a site's administrative account and/or manage the database within Liferay.
  7. Otherwise, if users want to preserve their current portal settings, they can start the portal without invoking the setup wizard.

    To start the server without triggering the setup wizard, specify setup.wizard.enabled=false  in the portal-ext.properties. Users are strongly discouraged from modifying the portal.properties.

    Note: Property values in portal-setup-wizard.properties override property values in portal-ext.properties.

  8. Start the JBoss application server; in the command console, enter: standalone.bat (./standalone.sh in a UNIX/Linux environment).
    • If the setup wizard was disabled, the site's home page opens automatically in the browser at http://localhost:8080.
    • Otherwise, the setup wizard opens in the browser.

Additional Information

A JBoss EAP bundle contains more than just an application server; the latest JBoss EAP contains standalone instances as well as a domain mode for clustered environments. The bundle contains the community version of AS 7.x as well as enterprise level products. Alternate versions of AS 7 is Wildfly; Wildfly XSDs are found in the 6.3 version and above.

Other changes include upgrades to the jboss domains and webservices, all in the backend.  Users can see the incrementation in the \..\standalone\configuration\standalone.xml as well as the schema. For domain security management, the add-user password policy is more user friendly, giving hints when a proposed password fails the requirements.

For more information, see the change logs on the JBoss EAP release notes.

Known Issue

When a portal is running on JBoss 6.x EAP, warning messages will often appear in portal's log as follows:

19:55:18,123 WARN [org.jboss.as.server.deployment] (MSC service thread 1-2) JBAS015960: Class Path entry unoloader.jar in /JBOSS_HOME/jboss-eap-6.1/standalone/deployments/ROOT.war/WEB-INF/lib/jurt.jar does not point to a valid jar for a Class-Path reference.
19:55:18,124 WARN [org.jboss.as.server.deployment] (MSC service thread 1-2) JBAS015960: Class Path entry ../../lib/ in /JBOSS_HOME/jboss-eap-6.1/standalone/deployments/ROOT.war/WEB-INF/lib/jurt.jar does not point to a valid jar for a Class-Path reference.
19:55:18,124 WARN [org.jboss.as.server.deployment] (MSC service thread 1-2) JBAS015960: Class Path entry ../bin/ in /JBOSS_HOME/jboss-eap-6.1/standalone/deployments/ROOT.war/WEB-INF/lib/jurt.jar does not point to a valid jar for a Class-Path reference.

Resolution

While these warnings do not affect the portal's functionality, they stem from an issue withing jboss. A solution is provided by Redhat here. Please note that to use this solution, one must be a subscriber to Redhat.

Was this article helpful?
0 out of 0 found this helpful