How to Upgrade Liferay

I’ve been using Liferay for several years now, starting with version 4.3 and upgrading it each 6 month or so. I recently upgraded from 5.1.2 to 5.2.3. This was so far the most painful upgrade, though everything is now OK.

Here is a short list of points worth considering when upgrading a Liferay deployment. The notes refer to an Apache/Tomcat/MySQL deployment.

Backup and restore

  • Consistency of the deployment. Always backup database plus jackrabbit at the same time.
  • Jackrabbit file names contain special character, notably %, which are sometimes replaced automatically by some tools. There number of files in jackrabbit grows very fast, and is absolutely disproportional to the size of the document library. So better pack your jackrabbit directory first if you need to transfer it over a network, especially winscp.
  • Case-sentitivity of the database. Some tables have uppercase. Depending on MySQL and the OS the system will be case sensitive or not. You can use the trick lower_case_table_names if necessary.
  • Make sure you export and import the database with UTF-8 encoding. If necessary force the encoding with --default-character-set.


  • Read the release notes carefully.
  • Merge catalina startup files (setenv, catalina, startup) if you’added custom stuff there
  • Merge property files (portal-ext, portal-legacy-XX)
  • Update theme(s), especially the supported version number
  • Update built-in theme under /html/themes/classic if you’ve made changes there
  • Update custom layouts in template.xml plus directory layouttpl
  • Merge web.xml
  • Update context.xml, if still used
  • Update static HTML files if they’ve been copied somewhere else for faster delivery
  • Remove any hook, e.g. sevencog hook
  • Change the directory for deploy & jackrabbit, make sure you use the right separator ( “/” or “\” )
  • Update mod_jk URL aths if necessary
  • Adjust the min/max memory of JVM if necessary


  • Corrupted XML in database. If Liferay update complains about corrupted XML, export the database as flat SQL file, track the faulty characters (carriage return, or other special character) with a text editor, and restore the database.
  • Theme names in database. If you theme has special character in it ( dot or underscope ) you may need to update it database
  • Default company and omni admin. You can specify the default company in web.xml and it will be the only one for which you can be omni admin. If this doesn’t work, update the company ID in database and ensure the default one is the first one (lowest ID).
  • Indexes. Better rebuild all indexes after an upgrade. Either go to the admin console and/or remove lucene directory.
  • Remove Tomcat temporary files. Remove the work and temp directories of Tomcat after upgrade.