Coming Soon: Vaadin 7 Control Panel

General Blogs October 2, 2014 By David H Nebinger

The Vaadin 7 Control Panel is a custom control panel designed to manage the shared Vaadin environment in Liferay.

What is the shared Vaadin environment?  It is one of two modes1 for creating Vaadin portlets and refers to the shared Vaadin environment hosted within the ROOT Liferay web application (under Vaadin 6, the shared Vaadin environment was the only supported mode).

Unfortunately managing the shared Vaadin environment has never been easy.  Vaadin requires not only jars, but also the theme and compiled widgetset files from the /html/VAADIN directory within Liferay.  Vaadin Add-Ons, deployed as Jar files, must be deployed to the ROOT/WEB-INF/lib directory (and included in the widgetset compile).  The only approved way of deploying these artifacts to Liferay is through plugins; a JSP hook can handle the theme files, but an EXT plugin is necessary for deploying the Add-On jars.

Vaadin 7 Control Panel to the Rescue!

The Vaadin 7 Control Panel solves these and other issues.  The new control panel has the following features:

  • An About Vaadin page that contains definitions for common Vaadin terms, helps those new to Vaadin understand Vaadin-speak:

About Vaadin Page

  • The Overview page summarizes everything in your shared Vaadin environment:

Overview Page

  • It is easy to change the shared Vaadin 7 version:

Change Version Page

  • Upgrade Vaadin even when the server cannot access the website:

Manual Vaadin Upload

  • The change version process reports detailed information on what is changed:

Change Version Details

  • Vaadin Add-Ons can be easily uploaded into Liferay for inclusion in the widgetset:

Add-On Upload

  • Before completing the upload, the Add-On details are presented for confirmation:

Add-On Confirmation

  • Additional dependencies for the widgetset compile can be included (these are sometimes needed for Add-Ons):

Additional Dependencies

  • Settings for the control panel can be changed inline, including memory settings used to compile the themes and widgetsets:


  • Custom themes can be created, edited, compiled, deleted, imported and exported.  The import/export feature will prove very useful to deploy themes to all nodes in a cluster, for theme promotion in corporate environments, etc.

Custom ThemesSelected Theme

  • Themes can be viewed inline.  Source files are presented in a syntax-highlighting viewer, images are previewed, and the folder hierarchy can be navigated: 

Theme Viewer

  • Custom themes can be edited inline using a syntax-highlighting editor.  Also new assets can be uploaded (images, other css files, etc.):

Custom Theme Editing

  • Compiling a theme shows detailed information about what is being done:

Theme Compiling

  • Widgetset compilation also gives detailed information:

Widgetset Compiling

Aside from these visual changes, there are a number of important non-visual changes.  The Vaadin 7 Control Panel supports localization (although currently only a language bundle will be available for English; submit your language bundle changes to for inclusion in a future release).

The Vaadin 7 Control Panel also includes a service layer.  By using the service layer, a Vaadin 7 portlet can:

  • Query for the version of the shared Vaadin 7.
  • Determine if the Valo theme is available.
  • List all available Vaadin themes.
  • List all available Vaadin Add-Ons.
  • Deploy Vaadin themes and/or Add-Ons after hot deployment.

This last item is significant.  Using the deployment features, a Vaadin plugin will be able to deploy custom themes and/or Add-Ons without requiring an administrator to set up the Vaadin environment in advance.  This opens the door for Vaadin 7 Marketplace plugins that need themes and/or Add-Ons as prerequisites, deploying them automatically so they are available when the portlet is used.  It can also be used in corporate environments to push themes and/or Add-Ons with plugins as they are promoted during development or to populate all nodes of a cluster, all without additional Liferay/Vaadin administration.

I'm really excited to get this published so it is available for the world to try.  Not just because it is a tool I've been working on for awhile, but because I see it opening doors for using Vaadin in the Marketplace as well as in the enterprise.

Vaadin is a great platform to build rich internet applications, we were just lacking a tool to pull everything together and make it easy to administrate.




1 Vaadin has been recommending a second mode for using Vaadin, a standalone mode.  In this mode, each individual portlet contains Vaadin and the theme(s) and the Add-Ons and the widgetsets, everything to be a working Vaadin portlet.  Since it is self contained, it is isolated from what goes on in the portal.  Unfortunately I believe there are some issues with this practice that have not been identified, discussed, or mitigated in any way.

For example, when you run a Vaadin portlet there is a client-side library that handles the DOM manipulation, javascript stuff, the theme application, etc.  The problem as I see it comes if you have a page with, say, 5 different Vaadin self-contained portlets.  This will lead to 5 different copies of the client-side library running in the browser!  Even if Vaadin were smart enough to handle them all in a single copy of the client side engine, what happens if one or more of the 5 were built with different versions of Vaadin, all self contained?

Same kind of issues with Add-Ons...  One plugin has version 1.0 of an addon while another has 1.1.  How does this work in the browser?  How will they be kept straight?  How do we know that there isn't some sort of bleed over from one to another?

Long story short, because of inadequate tools using the shared Vaadin environment in Liferay was a pain (some would use harsher words) and the standalone mode was seen as a way to allow developers to use Vaadin without having to figure out how to manage the shared environment.

With this new Vaadin 7 Control Panel, it will be much easier to manage the shared environment (which doesn't suffer from all of the issues the standalone mode may have) and my continuing recommendation would be to use it and avoid the standalone mode.


Vaadin Liferay Development...

General Blogs April 20, 2013 By David H Nebinger

NOTE: The following blog post is about Vaadin 6 and Liferay.  I'll be doing future posts on Vaadin 7, but for now I recommend sticking with Vaadin 6 in Liferay.



About two years ago, I noticed the Liferay IDE allowed for the creation of a new type of portlet based on Vaadin.  Curious, I did some research and found I could create Liferay portlets based upon the Vaadin Framework.

According to the Vaadin FAQ, Vaadin ("Vaadin" sounds like vuh-din, emphasis on first syllable, the long 'a':s sound like the 'a' in "ago") is a Java web application framework. It is designed for creating rich and interactive applications that run in the browser, without any plugins. A server-driven architecture together with reusable component model is used to simplify programming of applications and for better web application security. No HTML, XML or JavaScript necessary and all Java libraries and tools are at your disposal.

Translation is that it's a framework that you do most of your development in Java and, since it is based on the GWT, runs mostly in the client browser and uses lots of AJAX to communicate with the backend.

It's not a flashy framework in that it's not really designed to support lots of browser eye-candy.  It is, however, very well suited for enterprise development where you want to support forms, tables, and other basic widgets to create real and responsive enterprise applications.

Unfortunately, the wizard in the Liferay IDE was the only info I found on creating Vaadin portlets.  I couldn't find a real developer guide, didn't understand some of the requirements from the Vaadin website, and I basically struggled through the development of an initial Vaadin portlet.

So this blog post is going to help explain Vaadin in Liferay and what you'll need to use to become an effective Vaadin portlet developer.



These are the UI elements that are rendered in the browser.  Vaadin includes support for a basic set of UI widgets and include buttons, checkboxes, option groups, tables, trees, labels, text fields, etc.

Widgets have two aspects: the server side code and the client side code.  The server side widget is referred to as a Component.  Components are instantiated, configured, and added to define what the client side will represent.  The client side code is in Javascript and is generated using GWT to compile the Java code for the components into the javascript version for the client side.


A widgetset is the set of compiled javascript for all of the widgets that are used in the Vaadin application.

Widgetsets have names.  The widgetset name is a Java class-like name complete with a package path, i.e. com.vaadin.portal.gwt.PortalDefaultWidgetSet.  There's actually a corresponding file in the classpath at the location defined by the widgetset name with the extension ".gwt.xml", and this file defines the widgetset and all included modules.  The com/vaadin/portal/gwt/PortalDefaultWidgetSet.gwt.xml file is read by the GWT compiler to compile the widgetset used on the client side.

A Vaadin application requires a correctly compiled widgetset for the Vaadin version used in the application to render the client side correctly.


Vaadin widgets are rendered in the browser using a theme.  Vaadin ships with a number of themes out of the box, including a theme named "liferay" which is based on the standard Liferay classic theme in blue.

Custom themes are created by writing CSS.  Sounds pretty simple, but can be quite complex.  Every widget has it's own classes automatically added to them, and the components can have classes added to them in the Java code (components have an addStyleName() method to add a CSS class to the component, yes I know it's misnamed, but I think they were trying to avoid confusion with Java classes).


Vaadin Add-Ons are supplemental widgets that can be added to a Vaadin application to add new widgets that can be used in the application.  For example, there are Add-Ons to provide integration with charting packages, new layouts, extended core widgets that provide additional functionality, etc.

When an Add-On is added to a Vaadin application, the widgetset must be recompiled to create the complete widgetset for the application.  If the widgetset is not recompiled, the server side will have the code for the component (so you the developer can create, configure, and add the component), but the client side will not be able to render the widget.

Add-Ons can be found in the Vaadin Add-On Directory.

Vaadin in Liferay

The Vaadin website covers Vaadin as servlets in great detail, and touches on Vaadin portlets somewhat, but there are some things about using Vaadin in Liferay that are important to keep in mind...

The Widgetset

Vaadin portlets use a single, shared widgetset.  This widgetset is normally com.vaadin.portal.gwt.PortalDefaultWidgetSet, but it can be changed by setting the "vaadin.widgetset" property in

The single widgetset is used by all Vaadin portlets deployed in the portal, so the widgetset must contain all of the Add-Ons used by any single Vaadin portlet.  Have a single Vaadin portlet that uses, say, the Refresher Add-On?  It must be in the widgetset for all portlets.

The Theme

Vaadin portlets will, by default, use a single, shared theme.  This is actually a good thing because it will make your Vaadin portlets look consistent across the portal.

The default portal theme is "liferay", but it can be changed by setting the "vaadin.theme" property in

The Add-Ons

Add-Ons must be deployed into Liferay's WEB-INF/lib directory.  This is the only directory that will be used to compile the widgetset (details coming shortly), so this is where they must go. Vaadin portlets that use the Add-On(s) will use the file to define a dependency on the portal's jar.

The Resources

The compiled widgetset and the theme files represent all of the static files (resources) that Vaadin portlets will be using.  These files are always part of the Liferay ROOT web application, and will normally be available as /html/VAADIN/...  Vaadin will automatically be looking for the VAADIN directory to get the static resources, and this directory is found in the "/html" path, but this can be changed by setting the "vaadin.resources.path" property in  NOTE: The resources path must be part of the ROOT application and must be in an accessible path for the client browser, as the browser will be submitting HTTP requests to get the static resources.

Vaadin Control Panel

All Liferay instances that will be using Vaadin in their portlets must add the Vaadin Control Panel.  It's not included in Liferay by default, but your ability to leverage Vaadin in the portal will be severely limited without it.

There are two key functions that the Vaadin Control Panel provides:

  • The ability to change Vaadin versions on the fly.
  • The ability to compile the portal's single, shared widgetset.

The Vaadin Control Panel for Liferay is a portlet that provides a new control panel for Vaadin.  It can be downloaded from the Add-On directory here.

Download the portlet and drop it into the deploy directory, and Liferay should deploy it.  Note that the control panel portlet does not adhere to Liferay's packaging requirements (it's missing the crucial file), so it may complain about it during deployment, but should still be functional.  You may or may not need to restart your application container post-deployment (I have seen it deploy successfully and be available, but also have seen cases where a restart is necessary).

When you go to the control panel, you'll have a new entry at the bottom of the Portal section named "Vaadin".

The interface is rather simplistic:

Vaadin 6 Control Panel

The first thing to notice is the "Change Version" link at the top of the file.  Liferay by default comes with a fairly old version of Vaadin.  You're going to want to change your version of Vaadin in the portal to the latest version as soon as possible.

The next thing to notice is the "Select Add-ons" checkboxes.  When you download an Add-On, you'll have a jar file that contains the Add-On code.  The jar file must be put into Liferay's WEB-INF/lib directory.  You can see the path where the jar file must go in the filesystem.

The checkboxes here allow you to select and deselect Add-Ons that will be included in the widgetset compile.

The last thing to notice is the "Compile Widget Set" button.  When you change the Vaadin version or when you enable/disable Vaadin Add-Ons, you MUST recompile the widgetset using this button.  Failure to do so will result in errors on the client side.

When you hit the "Compile Widget Set" button, a bunch of stuff will scroll in the "Output Console" section of the window.  This is the output of the GWT widgetset compiler.  In most cases you should get a successful result at the end of the compile.  If you get errors in the window, I would search the Vaadin forums for a match or try posting to the Vaadin or Liferay forums.

Issues Upgrading Vaadin in Liferay

The Vaadin Control Panel makes changing Vaadin versions really easy, but it does not handle the upgrade completely...

The Vaadin Control Panel only changes the version of the vaadin.jar in Liferay, but does not deal with the Vaadin themes.  Vaadin themes are released for each Vaadin release, and the themes contain bug fixes also.

Vaadin provides a special download for Liferay users, the Vaadin 6 Liferay Update Package.  This download will include the precompiled widgetsets (that you won't use since you're compiling your widgetset using the Vaadin Control Panel) and the updated themes.  You'll want to extract the themes directory from the download and copy it up to the Vaadin resources directory (default would be ROOT/html/VAADIN directory).  I actually deploy this locally using a JSP hook plugin (create a JSP hook plugin, put the new themes directory in the hook plugin, build and deploy to let Liferay handle the updating of the ROOT webapp).


Well, that about covers administrating Vaadin in Liferay.  My next blog post will cover developing Vaadin portlets...


Service Builder Presentation Info

General Blogs April 20, 2013 By David H Nebinger

So I received bunch of emails on Service Builder after my webinar last month...  Thought I'd write up a blog entry that will end up in the search engines and hopefully lead folks here to get to the details...

Anyway, the recorded presentation is available on the Liferay LIVE Web Events page.  You can listen to the whole presentation and watch as my demo fails during the presentation...  wink

All of the projects used for demo are actually available in this forum post in the second message of the thread.

Now for the keywords that will get you here...

The presentation covers how to do some basic Service Builder functions, but also features:

  • one-to-many relationship handling.
  • many-to-many relationship handling.
  • accessing an external (non-Liferay) database.
  • using 'fake' (non-database-backed entities) to build shared code modules using Service Builder.
  • Vaadin and Service Builder integration.


Backup/Restore a Liferay Environment

General Blogs April 20, 2013 By David H Nebinger



This page documents two important administrative functions: backing up Liferay (and restoration) and setting up a copy for development usage.

Having a backup of the database is an important issue, in order to restore the database after some sort of catastrophe. The first thing that we're going to cover is backing up the Liferay data.

Liferay uses a database for primary data storage, but also uses the filesystem to store things such as image files, documents, etc.

Since I'm using Liferay with a Mysql database running on a Linux box, these instructions will focus only on that implementation. But the details should be adaptable to any database and operating system that can host Liferay.

So first the plan: the current Mysql server is going to host a second database. The production database will be the one that the main Liferay instance will use, and the development database will be a relatively recent copy of the production database. It will be allowed to get out of sync with production because I don't want changes I'm in the middle of making overwritten just because cron thinks it is time.

Create the Development Database

Create the development database, lpdev, with the following commands:

$ mysql -u root -p mysql
mysql> create database lpdev;
mysql> grant all privileges on lpdev.* to 'lportal'@'%' with grant option;
mysql> quit;

This will create the database lpdev and give all privileges to the lportal user.

Create Backup Script

First we'll set up a backup script for the production database and data files. I'm going to create and use a local directory, /var/liferay/backups. This will centralize the backups to make them easy to use for restoration later on.

In my /etc/cron.daily folder I created a script liferay-backup.cron with the following contents:

# Back up the Liferay data.
# Get a variable to store the current date.
date=`date -I`
# Backup the liferay mysql database.
mysqldump -u lportal -p<password> lportal | bzip2 -9 -c > /var/liferay/backups/lportal-$date.sql.bz2
# Also create a backup of the Liferay data files.
tar cjf /var/liferay/backups/lportal-$ -C /opt/liferay data

You will have to change the <password> tag, replacing it with your lportal user password. NOTE: There is no space between the -p and the password. If you don't have an /etc/cron.daily directory, you can do your standard cron thing to create the backup.

This will create two files in the /var/liferay/backups directory, the sql to recreate the database and a tar file to recreate the data directory. These files are still on the same Linux box as the database and the server, so you may want to integrate the files into an off-system datastore or removable media.

This backup script runs while Liferay is still active. There is the potential of database issues (capturing partially committed data) or filesystem issues (the Lucene indices in a state of flux). Running the backup in the very early morning will help protect against this, but the potential is still there...

Recovering Liferay/Refreshing Development

The steps to recover Liferay are pretty much the same as refreshing the development environment, the only difference being the database used on the command line and the location of the data when extracted.

Restoration and refreshing should be done while Liferay is not running as changing the data on the fly could impose some serious application issues. But if you find yourself having to recover the database, it's a good bet that Liferay is not running anyway.

Recovering the Database

Recovering the database is a one-line command:

$ bzcat /var/liferay/backups/liferay-<date>.sql.bz2 | mysql -u lportal -p<password> lportal

Replace the <date> tag with a valid date from your backups. Dates will be formatted as YYYY-MM-DD. Replace the <password> tag with your lportal user password. NOTE: There is no space between the -p and the password.

Refreshing the Development Database

To refresh the development database, lpdev, you'd run the following command:

$ bzcat /var/liferay/backups/liferay-<date>.sql.bz2 | mysql -u lportal -p<password> lpdev

Do the replacements as indicated in the Recovering the Database section above.

Recovering the Data

The filesystem data has things such as the image gallery files, documents, etc. Our backup has all of these files, but you should clean out your data directory prior to expanding the backed-up data. This will ensure that you won't have any lingering data from before the restoration.

Recovery is done through the following commands:

$ /bin/rm -rf /opt/liferay/data/*
$ tar xjf /var/liferay/backups/liferay-<date>.data.tar.bz2 -C /opt/liferay

After starting Liferay, you're going to want to go to the Control Panel, Server Administration page and choose "Reindex all search indexes". This will rebuild all of the Lucene indices from the restored information in the database and the data files and leave it in a consistent state.

Refreshing the Development Data

You'll know if your local Liferay data is out of sync when you start seeing broken image tags, etc., in your development portal. To fix these kinds of issues, you'll have to refresh the development data. Since we're doing development on a Windows box, refreshing the data is a bit more complicated. Basically you're going to complete the following steps:

  1. Get the liferay-<date>.data.tar.bz2 file from your Linux box to your Windows box.
  2. Delete the contents of the c:\liferay\bundle\data directory.
  3. Expand the contents in the c:\liferay\bundle directory (Since the archive already is prefixed with the data directory, you should not expand in the data directory or you'll have c:\liferay\bundle\data\data and Liferay won't find it at startup).
  4. After starting Liferay, you're going to want to go to the Control Panel, Server Administration page and choose "Reindex all search indexes" to ensure the Lucene indices are consistent.


So now you're all set w/ your backup and recovery for Liferay. You can also refresh your development environment so that it matches production.

If you have just created your development database, you're going to want to run the Liferay backup script to create the sql and data files. Then follow the steps to refresh your development environment. Don't forget to change the database to lpdev in your file in c:\liferay\bundle\tomcat-6.0.29\webapps\ROOT\WEB-INF\classes so you access the right database in development.

Liferay and SSL

General Blogs April 20, 2013 By David H Nebinger



So I've got my Liferay site up and running under Tomcat and fronted by Apache HTTPd. The next thing I wanted to do was add an SSL certificate so that I could get it all under HTTPS...

SSL certificates, from sites like VeriSign or Thawte or Network Solutions are usually the players that come to mind when you want to get a certificate.

A quick Google search, however, yields scores of other companies that provide SSL certificates. After pricing a bunch of them, I finally settled on a certificate from GoDaddy. At $12.99 per certificate per year, it's hard to beat the price and they are handled in most browsers.

For the most part the instructions for getting a certificate on the GoDaddy site are straight-forward. There were a few hiccups along the way, mostly due to my use of the Apache Portable Runtime (APR) in conjunction with Apache HTTPd and Tomcat.

So I'm going to lay out all of the steps that I had to take in order to request the certificate, get the certificate, install the certificate in Apache and Tomcat, and finally get it all working.

Create the Certificate Signing Request

Creating the csr, or Certificate Signing Request, is a fairly simple process. Since we're getting a certificate to install into both Apache and Tomcat, you could look at two different sets of instructions, one for each server. Since I think (but do not know for sure) that getting the certificate into Tomcat is going to be the harder of the two, I elected to follow the Tomcat instructions.

To generate the csr for Tomcat, you have a number of commands to execute in the shell to create the csr file and then you have to paste the contents of the csr file into the GoDaddy form.  The GoDaddy instructions for creating the csr are here.

The first step involves creating the keystore that Tomcat will be referencing. You'll need to know where on the filesystem your keystore will be stored, because you'll eventually be pointing Tomcat to it for usage. On my Gentoo system, certificates are usually in the /etc/ssl directory, so that's where I built mine. I created the /etc/ssl/tomcat directory and then cd'd to that directory. The remainder of the shell script commands were all executed from this directory.

Creating the keystore involves running the following command:

$ keytool -keysize 2048 -genkey -alias tomcat -keyalg RSA -keystore tomcat.keystore

When you type this command, you'll be prompted with a series of questions, and the GoDaddy instructions tell you what needs to go into each field.

If you don't want to go through the prompts, a web-based form for building the command to create the keystore can be found at Note that you'll have to edit the script they generate to change the alias specified above, but otherwise the tool works quite well.

Next you need to generate the csr using the following command:

$ keytool -certreq -keyalg RSA -alias tomcat -file <your file name>.csr -keystore tomcat.keystore

Replace the <your file name> with the csr filename you want to use. It is not that important because you don't really send the file anywhere. I named mine dnebinger.csr.

The part that is missing from the GoDaddy instructions relates to whether you are using the Apache Portable Runtime (as I am). When using the APR, you will be needing the private key that is currently stored inside of the tomcat.keystore file. I couldn't find a way to extract the private key using keytool, but I did find a tool at that could do it. Download the tool and run it as instructed from the link to get the PKCS#8 format and direct it to a file. Give the file a .pem extension; I used the tool to create my dnebinger.pem file.

$ java ExportPriv /etc/ssl/tomcat/tomcat.keystore tomcat {keystore_password} > /etc/ssl/tomcat/<your file name>.pem

Cat your .csr file and copy it into the clipboard. Go to the GoDaddy form and paste in your csr. You'll then have to wait for GoDaddy to create your certificate.

Wait for Your SSL Certificate

While waiting, I did get an email from GoDaddy indicating that they could not verify that I was in control of the domain (my whois information is blocked from public consumption, thank you Network Solutions!). One option was to create a specially named html file and serve it from my Apache web server. I followed the instructions to create the html file, naming it correctly and putting the right stuff inside. Since I have Apache fronting my Liferay/Tomcat and do not have html file extensions JkUnmount'd, I had to temporarily add the JkUnmount for html files so when GoDaddy would come looking for the file I'd be able to serve it up quickly and easilly. I then went to the GoDaddy site and followed their further instructions for validating using the special file. Domain control was verified immediately, and they created the certificate.

Download Your SSL Certificates

So, next comes downloading the certificate. When downloading, you choose the type of server that you're installing the certificate into. I chose first to download the Tomcat version, then I chose to download the Apache version. The certificates are downloaded in zip format, you'll need to expand them. I extracted the Tomcat version to /etc/ssl/tomcat and the Apache one to /etc/ssl/apache.

Setup Tomcat to Use the Certificate

You don't really have to follow the Tomcat instructions for installing the certificate, it is actually quite easy. Since I'm using APR, I don't need to install the certificate into the keystore, but I do need the private key.

Using the certificate in Tomcat is a matter of editing the /opt/liferay/tomcat/conf/server.xml file (use whatever path is appropriate for your local environment). Find the <Connector /> tag for port 8443 and add the following attributes:

SSLPass="<your keystore password>"

And change the attribute for SSLProtocol so it says "TLSv1".

Setup Apache to Use the Certificate

Setting up Apache simply requires following GoDaddy's instructions. For my Gentoo system, I had to edit /etc/apache2/vhost.d/00_default_ssl_vhost.conf. For the SSLCertificateChainFile entry, they're referring to the gd_bundle.crt file that was part of the downloaded zip. The SSLCertificateKeyFile entry refers to the private key file that was created, in my case it is dnebinger.pem.

Setup Liferay to Use HTTPS

Since you've got this new certificate, you're going to want Liferay to use it. You need to edit your /opt/liferay/tomcat/webapps/ROOT/WEB-INF/classes/ file and add the following entries:


At this point everything should be configured and ready to go. Restart your Liferay/Tomcat and Apache servers, and then you can hit them using either the http or https urls. Since we've configured Liferay to prefer https, you should see that when you use the http url you will eventually be redirected to the https url.


Fronting Liferay Tomcat with Apache HTTPd daemon

General Blogs April 20, 2013 By David H Nebinger



So here's my situation...

I've got a Gentoo Linux server sitting around that I wanted to get Liferay 6.0.6 up and running on. Although this blog will cover the setup I did for my Gentoo box, for the most part you should be able to adapt what I've done for your Linux box. Heck, a lot of this will probably work on a Windows system too, but you're on your own as far as that goes...

Installing Dependencies and the Liferay Tomcat Bundle

My system already has the Java SDK, OpenSSL, and other dependent software installed, so I'm not going to rehash that installation and setup. Suffice it to say that you may find yourself installing some missing components along the way to satisfy dependencies...

Gentoo makes installation pretty easy for all of the components that I needed. Specifically I issued the following command:

$ emerge www-servers/apache dev-libs/apr dev-libs/apr-util www-apache/mod_jk

So that installs the basic software for Apache HTTPd version 2.2.17, but doesn't complete the configuration for us.

Next I downloaded the Liferay 6.0.6/Tomcat bundle in preparation for installation.

Now you might be asking yourselves why I didn't install Tomcat using Gentoo's emerge command and then install Liferay into Gentoo's Tomcat. The reason is that Gentoo's Tomcat actually gets installed to many different directories and doesn't retain the 'all in one directory' setup that's pretty standard w/ Tomcat installs. The tomcat/logs directory ends up over in /var/log, the tomcat/temp directory ends up over in /var/tmp, the tomcat/bin, tomcat/lib, and tomcat/webapps directories end up in /usr/share/tomcat-6, and tomcat/conf ends up in /etc. From a Linux standards perspective, this reorganization makes total sense. Knowing all of the reconfiguration I'd be doing in order to get Liferay up and running in this setup seems to be more trouble than it's worth, at least in the short term. Who knows, maybe if I get some time I'll explore what is involved in doing it the Gentoo way, but for now I've decided to skip it...

Instead I expanded the Liferay 6.0.6 Tomcat bundle to /opt, with the final installation path as /opt/liferay-portal-6.0.6. To make upgrading easier, I created a symbolic link as /opt/liferay using the following command:

$ ln -s /opt/liferay-portal-6.0.6 /opt/liferay

So the path for tomcat is now /opt/liferay/tomcat-6.0.29, and I created another symlink for that as /opt/liferay/tomcat.

The first thing I did was delete the provided JRE that is part of the bundle. This makes the and scripts unhappy as they want to use that JRE, so I had to edit them to use my installed Java environment. I also took the opportunity to hard code the CATALINA_HOME environment variable and tweak the Java command line arguments for memory handling, timezone, etc.

From here you'll want to skip over to and use their documentation to get your database defined, mail server changes done, and fix up your files.

At the end of all of this configuration, I could start up Tomcat and hit Liferay by going to Tomcat's port 8080 in order to verify that it was up and running.

So next we have to worry about setting up Apache so that it can front Tomcat. A lot of folks have trouble doing this (you'll see a lot of questions and stuff when you search your favorite search engine). I have to admit that I had to go back and forth tweaking the files until I got it all right...

So now I'm going to be referring to the Apache config files, specifically as initially installed in my Gentoo system. The file paths will probably be different on your system, but the content of the changes should basically be the same...

Configure mod_jk

Gentoo installed mod_jk as part of our previous emerge command, but we need to enable it so Apache will use it when it is running. So we have to edit /etc/conf.d/apache2 and find the line with the APACHE2_OPTS defined. At the end of the line (but still within the quotes), add -D JK. This will enable the loading of the mod_jk when Apache starts up.

The default configuration for mod_jk as installed in Gentoo is pretty complete and shouldn't require any significant editing. The only change I had to make to /etc/apache2/modules.d/88_mod_jk.conf was to change the only uncommented JkMount line so it read:

JkMount /* ajp13

I also changed the JkAutoAlias so that it pointed to /opt/liferay/tomcat/webapps, but honestly I don't know if it was really necessary or not.

Now, the one thing you'll see going forward is that I actually have the JkMount thing in another file. This change was the most obvious one (I mean, the default Gentoo file already had a JkMount here), but it didn't work the first time I started Apache up. So there will be another place in this blog where the JkMount will come up again, and if you do them all you should have the same success that I had.

Gentoo's workers file is /etc/apache2/ It's got a lot of comments in it, but basically you should end up w/ the following:


The ajp13 is actually going to be our Liferay/Tomcat guy. Perhaps I should have changed it to, say, liferay, but I didn't feel that I wanted to make such sweeping changes to Gentoo's default config.

I said the JkMount would come up again, and here it is. I had to modify the /etc/apache2/vhosts.d/default_vhost.include file, and I added the following:

<IfModule jk_module>
  JkMount /* ajp13

This change applies the JkMount to the default virtual host, and was necessary for Apache to pass the requests through to Liferay.

After these changes were made, I could fire up Apache and hit the regular port 80 of Apache and it passed the requests through to Tomcat, and it was all working great!

Have Apache Serve Liferay Static Content

The best reason to front Liferay/Tomcat with Apache is to let Apache handle the serving of the static content (images, stylesheets, etc) and let Tomcat deal w/ the dynamic content.

To do this, you're going to have to do some directory copying... First copy the /opt/liferay/tomcat/webapps/ROOT/html directory to Apache's htdocs directory, /var/www/localhost/htdocs in my case. You should also copy all of the other webapps directories (all except for ROOT) to the htdocs directory. By copying all of these directories, any incoming requests for static content will be handled by Apache rather than Tomcat.

NOTE: As you redeploy your portlets, themes, etc. to Liferay, you should also copy the directories over to the htdocs directory, otherwise Apache might serve an older version of the file(s).

For Apache to handle static files, you need to go back to the /etc/apache2/vhosts.d/default_vhost.include file and add some lines just below the JkMount line you added earlier. You'll end up with the following:

<IfModule jk_module>
  JkMount /* ajp13

  JkUnmount /*.jpg ajp13
  JkUnmount /*.jpeg ajp13
  JkUnmount /*.gif ajp13
  JkUnmount /*.png ajp13
  JkUnmount /*.ico ajp13
  JkUnmount /*.css ajp13
  JkUnmount /*.js ajp13

By using JkUnmount, you're indicating to Apache that it should handle requests with the given extension(s) rather than passing them through to Tomcat.

The one obvious extension that is missing from the above is the .html extension. Since the servlet mapping mechanism in a web application can map .html extensions to a servlet, adding this extension might not give you the result you're expecting. The way I figure it, it's better to let Tomcat serve the single html file (if it is static) rather than break some servlet or portlet functionality, but it is really just a matter of research in the various web.xml files to see if you have any servlet mappings expecting .html extensions. If you don't have any such mappings (now or in the future), you can add the extension as a JkUnmount and let Apache handle them. If you do have the mappings, expect to have the mappings, or just don't want to do the research, then leaving the JkUnmount out for this extension is the safest bet.

Since we're talking about JkUnmounts, if you have other directories in your htdocs folder that Apache should always handle, then add them as JkUnmounts. For example, say I have a javadocs directory in my htdocs folder and I need Apache to handle it, I'd add the following line:

  JkUnmount /javadocs/* ajp13

Setup Liferay To Use Apache

The final step involves editing your /opt/liferay/tomcat/webapps/ROOT/WEB-INF/classes/ file to include the following:


This ensures that Liferay will know that it is operating behind Apache HTTPd and will handle redirects correctly.

That's all there is to it. The fact that you're seeing this on port 80 rather than 8080 is proof that these instructions work!

My First Liferay Blog...

General Blogs April 16, 2013 By David H Nebinger

I was going to take a queue from Jelmer and start with just a test blog post, but don't want to take the wind out of his sails...  Must say, though, that your blog post did make me laugh Jelmer!  laugh

Instead, I'm going to lead w/ my blogging plans...

First, I've got a handful of blog postings I had put together about HTTPS/Apache Httpd/Tomcat/Liferay that I'm going to restore here.  Had them up on my home Linux box, but as it's my home server I end up making changes and playing with different versions of Liferay, so although the blog entries had value, they're not up anymore.  Pulling them over here will give them a little more permanence and keep them safe from my Linux server hacking...

Then comes the fun stuff, I'm going to dive into Vaadin portlet development under Liferay.  I'll cover the dev environment setup, the must-have Vaadin Control Panel, then maybe move into some actual Vaadin portlet development...

Oh, boy, I just can't wait...

Showing 7 results.
Items 20
of 1