Quick running Liferay on a Tomcat bundle

The simplest way to run Liferay is to download a specific bundle from the Liferay official site. A Liferay bundle is just a compressed archive that contains all that is needed to host the Liferay Portal. A bundle consists of a Java-based application server and the deployed Liferay Portal core application. Liferay provides these bundle runtimes with different application servers (that is, Tomcat, JBoss, Geronimo, and so on) so that you can use any one based on your choice. This method is recommended for people who just want to run Liferay Portal, look at its functionalities, and configure their site using the GUI. In this recipe, you will learn the art of setting up Liferay on Tomcat and the MySQL database engine.

Getting ready

First, make sure that JRE or JDK is properly installed. Type the following command line:

$ java -version

The result should be similar to this:

$ java -version
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode).

Also, check out the Java SDK version. Liferay recommends Java 7 or later.

Moreover, determine whether the MySQL server installation is done:

$ mysql --version

As a result, the actual installed version should be displayed. Here is an example:

mysql  Ver 14.14 Distrib 5.5.34, for debian-linux-gnu (x86_64)

Also, check out the MySQL version. We recommend 5.5 version or later.

How to do it...

In order to run Liferay on a Tomcat bundle, follow these steps:

1. Create a database with the name lportal:

   CREATE DATABASE lportal CHARACTER SET utf8 COLLATE utf8_general_ci;
   grant all privileges on lportal.* to '{USERNAME}'@'%' identified by 'PASSWORD';

   Make sure that the MySQL user has permissions to create tables.

2. Download the correct Liferay version on the Tomcat bundle from http://www.liferay.com/downloads/liferay-portal/available-releases.
3. Unzip the downloaded archive.
4. Go to the extracted folder liferay-portal-6.2-ce-ga2. This path will be called ${liferay.home} folder.
5. Go to the ${liferay.home} folder and create a file called portal-ext.properties.
6. Edit portal-ext.properties and set the database properties:

   jdbc.default.driverClassName=com.mysql.jdbc.Driver
   jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
   jdbc.default.username={USERNAME}
   jdbc.default.password={PASSWORD}

7. Find the Tomcat folder and go to the tomcat-7.0.42/bin/ location.
8. Run the ./startup.sh script (startup.bat for Windows OS) and look into the tomcat-7.0.42/logs/catalina.out log.
9. In a browser, type http://localhost:8080 location. By default, Tomcat listens on port 8080. It should render the Liferay setup wizard by default. This wizard will ask for basic information, such as, portal name, default language, and administrator user details.

How it works...

Running the Liferay Portal from a prepared bundle is quite an easy task to accomplish. However, it is worth knowing what exactly happens when Tomcat is being started. Take a brief look at the catalina.out log and try to examine it line by line.

Loading the configuration descriptor

The first thing is to deploy ROOT.xml. In our catalina.out file, there is a line present, which is shown as follows:

INFO: Deploying configuration descriptor /home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/conf/Catalina/localhost/ROOT.xml

It means that the configuration file turns on the crossContext attribute in Tomcat 7. This setting is required because Liferay is a portlet container. Hence, it is an application that should have access to other applications called portlets. The Apache Tomcat documentation says:

"Set to true if you want calls within this application to ServletContext.getContext() to successfully return a request dispatcher for other web applications running on this virtual host."

Loading system properties and portal properties

The next few lines of the logfile show portal properties and system properties that are loaded from specific locations:

Loading jar:file:/home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT/WEB-INF/lib/portal-impl.jar!/system.properties
Loading jar:file:/home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT/WEB-INF/lib/portal-impl.jar!/system.properties
Loading jar:file:/home/piotr/liferay-portal-6.2-ce-ga2/tomcat-7.0.42/webapps/ROOT/WEB-INF/lib/portal-impl.jar!/portal.properties
Loading file:/home/piotr/liferay-portal-6.2-ce-ga2/portal-ext.properties

The main configuration file for Liferay Portal is portal.properties, which contains a detailed explanation about the properties that it defines. There are at least three possible ways to override portal.properties. There is a functionality to put portal-ext.properties in the ext plugin, in the ${liferay.home} directory, or in portal-setup-wizard.properties. But which file is the most important? The answer is placed in portal.properties file. The default read order is portal.properties, portal-bundle.properties, portal-ext.properties, and then portal-setup-wizard.properties:

    include-and-override=portal-bundle.properties
    include-and-override=${liferay.home}/portal-bundle.properties
    include-and-override=portal-ext.properties
    include-and-override=${liferay.home}/portal-ext.properties
    include-and-override=portal-setup-wizard.properties
    include-and-override=${liferay.home}/portal-setup-wizard.properties

Detecting the database and database dialect

The next step is to recognize the database's dialect:

12:35:47,469 INFO  [localhost-startStop-1][DialectDetector:71] Determine dialect for MySQL 5
12:35:47,504 INFO  [localhost-startStop-1][DialectDetector:136] Found dialect org.hibernate.dialect.MySQLDialect

Liferay supports many database engines, such as DB2, Derby, Hypersonic, Ingres, MySQL, Oracle, P6Spy, PostgreSQL, and Sybase. The default database is Hypersonic, which stores all data in the ${liferay.home}/data/hsql/lportal directory. This is a good option for developers who want to run JUnit tests, which modify data by testing the persistence layer or business process.

On every restart, Liferay tries to get the build number (Liferay version) from the Release_ table. If this table doesn't exist, it calls ReleaseLocalService.createTablesAndPopulate().

If it is not possible to get the build number, Liferay logs the following information:

WARN  [localhost-startStop-1][ReleaseLocalServiceImpl:171] Table 'lportal.Release_' doesn't exist

The createTablesAndPopulate method runs following scripts:

• liferay-portal/sql/portal-tables.sql: This creates the required tables
• liferay-portal/sql/portal-data-common.sql: This adds the default data
• liferay-portal/sql/portal-data-counter.sql: This inits the unique key generator
• liferay-portal/sql/portal-data-release.sql: This sets the release date
• liferay-portal/sql/indexes.sql: This adds database indexes
• liferay-portal/sql/sequences.sql: By default, this file is empty.

Apart from creating tables and populating data, Liferay triggers the VerifyProcess mechanism. This process will run on every startup to verify and fix any integrity problems found in the database. This is the perfect place for developers to add custom code to check the integrity of specific cases.

Starting the autodeploy scanner and deploying plugins

The last step is initializing the autodeploy and the hotdeploy listeners. In general, these mechanisms install all the plugins into the Tomcat container and register them as portlets, hooks, themes, and so on. In particular, there are at least three deploying approaches: sandbox deploy, autodeploy, and hotdeploy.

Note

By default, Liferay uses the autodeploy and hotdeploy listeners. In fact, sandbox can currently deploy only themes and portlets.

The autodeploy mechanism is responsible for listening on a specific directory to install on-the-fly new plugins and copying them into the Tomcat hotdeploy process. A definition of that directory is placed in portal.properties, and by default, it is in the deploy folder:

auto.deploy.deploy.dir=${liferay.home}/deploy

Every type of plugin has its own autodeploy mechanism. This mechanism runs all the necessary steps to install it correctly in the Liferay container. In simple terms, the autodeploy mechanism generates the web.xml file and adds the required libraries to specific plugins. Definitions of these classes are placed in the portal.properties file with an auto.deploy.* prefix. Each class extends BaseAutoDeployListener.

The second process, hotdeploy, is responsible for registering plugins in Liferay. There are many steps, such as creating database tables, setting preferences, registering Spring application contexts, and so on. Of course, each step depends on the type of plugin. In portal.properties, there are definitions for each type of class:

hot.deploy.listeners=
com.liferay.portal.deploy.hot.PluginPackageHotDeployListener,
com.liferay.portal.deploy.hot.SpringHotDeployListener,
com.liferay.portal.deploy.hot.ServletContextListenerHotDeployListener,
com.liferay.portal.deploy.hot.ExtHotDeployListener,
com.liferay.portal.deploy.hot.HookHotDeployListener,
com.liferay.portal.deploy.hot.JSONWebServiceHotDeployListener,
com.liferay.portal.deploy.hot.LayoutTemplateHotDeployListener,
com.liferay.portal.deploy.hot.PortletHotDeployListener,
com.liferay.portal.deploy.hot.SocialHotDeployListener,
com.liferay.portal.deploy.hot.ThemeHotDeployListener,
com.liferay.portal.deploy.hot.ThemeLoaderHotDeployListener,
com.liferay.portal.deploy.hot.MessagingHotDeployListener

Tip

In the deployment process, the Liferay deployer modifies the web.xml file, adds specific dependencies, and packs it again. Ensure that you do not copy the WAR file directly to the Tomcat webapps folder. If you do so, the plugin will not work.

There's more...

Often, enterprises have an established Java EE infrastructure upon which they would like to install Liferay. You must consider also the enterprise's security policies. These policies sometimes prevent the download and installation of the Tomcat bundle into a location of your choice. In this situation, a bundle will not suffice, and you have to manually install Liferay from its WAR archive into an already existing Apache Tomcat application server.

There are six steps to achieve this goal. They are as follows:

1. Copy specific JAR files and dependencies to the Tomcat global lib folder, $TOMCAT_HOME/lib/ext.
2. Enable crossContext by adding the ROOT.xml file to the $TOMCAT_HOME/conf/Catalina/localhost folder.
3. Set custom $JAVA_OPTS parameters in the $TOMCAT_HOME/bin/setenv.sh file:

   JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF8 -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx1024m -XX:MaxPermSize=256m"

4. Update the common.loader property located in $TOMCAT_HOME/conf/catalina.properties with the following lines of code:

   common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,${catalina.home}/lib/ext,${catalina.home}/lib/ext/*.jar

5. Specify the URI encoding as UTF-8 in $TOMCAT_HOME/conf/server.xml as follows:

   <Connector port="8080" protocol="HTTP/1.1"
     connectionTimeout="20000"
     redirectPort="8443" URIEncoding="UTF-8" />

6. Deploy Liferay Portal using Tomcat manager or manually put the WAR archive into the $TOMCAT_HOME/webapps folder. The WAR file is available at http://www.liferay.com/downloads/liferay-portal/available-releases#additional-versions.

Note

More detailed instructions of how to install Liferay on the Tomcat server are available on the official Liferay documentation at https://www.liferay.com/documentation/liferay-portal/6.2/user-guide/-/ai/installing-liferay-on-tomcat-3.

See also

For information about running Liferay on the clustered environment, refer to the Clustering Liferay Portal recipe in Chapter 11, Quick Tricks and Advanced Knowledge, and the Scalable infrastructure recipe in Chapter 12, Basic Performance Tuning. For information about setting the developer's environment, refer to the next recipe.