Upgrading to dotCMS 3.x - Documentation topics on: dotcms 3.0,upgrade,upgrading,.

Upgrading to dotCMS 3.x

This document describes the steps required to upgrade from a dotCMS 2.5.x installation to dotCMS 3.x.

Important: To upgrade successfully, you must complete all steps listed in this document, including all preparation steps and all upgrade steps.

Steps to Prepare for the Upgrade

Important Things to Avoid

The upgrade from 2.5.x to 3.x is considered a major upgrade. Before we begin, there are a couple of important things NOT to do:

  • Do NOT use Push Publishing/Bundles to upgrade.
    • Bundles are NOT guaranteed to be compatible across versions, major or minor.
  • Do NOT use the .zip file produced by the Backup function on the Maintenance Screen.
    • Backup ZIP files are NOT compatible across versions, major or minor.

Those out of the way, below is the Upgrade Process - follow the steps listed below:

1. If you have over-ridden your startup file, you must change the -javaagent parameter.

Find the following parameter in your startup file (startup.sh on Linux/OS-X/Unix, or startup.bat on Windows):


And replace it with the following:


2. DotCMS 3.x should be run in Java 7 or higher

  • Java 8 is also supported in dotCMS version 3.2 or higher
    • Important: Java 8 is required for dotCMS version 3.5 or higher.
    • Therefore, if you are upgrading to dotCMS version 3.2 or higher, it is strongly recommended that you use Java 8 or higher.
  • For security and performance reasons, whenever possible use the latest update available for whatever version of Java you use.

Important: Remember to set the JAVA_HOME environment variable to the proper value for your selected version of Java.

3. Review your auto cluster configuration

Auto cluster configuration is no longer configured in the dotmarketing-config.properties file. Instead, it now has its own configuration file, dotcms-config-cluster.properties.

If you have made any changes to your cluster configuration, please review the new cluster configuration settings, and change your configuration to use the new auto-cluster implementation.

To disable cluster auto-wiring, please see the manual cluster configuration documentation.

4. Download the latest dotCMS distribution

All installations should be run out from the downloaded distribution - never from source

Please see the dotCMS download page for the latest distribution packages.

5. For developers: Migrate your OSGI plugins from ant to gradle

The build system in dotCMS 3.x now uses ./gradlew instead of ant.

It is recommended that you migrate any OSGI plugins you have from ant to gradle. Please review the /docs folder for examples.

6. Copy your plugins to the new 3.x plugins location

Important: Plugins in dotCMS 3.x have changed. Please read the following carefully and update and copy all your 2.5.x plugins appropriately.

Plugin pathing has changed

  • The plugin directory has been removed from the dotserver directory, and located as a top level root directory.
  • The name of the tomcat directory has also changed to include the version, so any reference to a dotCMS file from a 2.X plugin will probably need to be changed.

Most of the jars living on dotCMS were repackaged

To avoid conflicts with different versions of libraries used in app servers and custom plugins, the packaging of dotCMS repackaged jars has changed, and now have the prefix: com.dotcms.repackage.

For example, the previous command:

import javax.portlet.PortletConfig;

Has been changed to:

import com.dotcms.repackage.javax.portlet.PortletConfig;
  • Be sure to inspect all dotCMS package references in your plugins and alter them to conform to the new dotCMS 3.x jar packaging.
    • After this is done, the plugin will need to be repackaged using the plugin deploy commands mentioned in the steps below.

7. Identify and begin to replace deprecated macros

Many Macros Have Been Deprecated

Please search the dotCMS documentation for a list of all deprecated macros.

Deprecated macros should be replaced with alternate methods as soon as practical. These macros will continue to work for some period of time, but in some unspecified future version will be eliminated and will no longer work.

Upgrade Steps

8. Copy your assets directory from your 2.5.x installation to the your dotCMS 3.x installation

The dotCMS 3.x assets folder is ./dotserver/tomcat-8.0.18/webapps/ROOT/assets.

9. Backup your database

10. Create your 3.x database

A. Create a new database for your 3.x installation

B. Restore your existing 2.5.x database backup into this new 3.x database

Double-check: You backed up your database first, right?

C. Run upgrade queries on the new 3.x database

Run the following queries on the new 3.x database:

delete from containers where not exists (select * from container_version_info where working_inode = containers.inode or live_inode = containers.inode);
delete from inode where type = 'containers' and inode not in (select inode from containers);

11. Copy any configuration plugin changes to the new configuration plugin folder

If you need to alter any file in dotCMS ie.. ROOT.xml, startup.sh/startup.bat, you should now use the ROOT folder of the com.dotcms.config plugin (which can override any file in dotCMS).

  • Copy any configuration files changed in 2.5.x instance (./dotserver/plugins/com.dotcms.config/ROOT), into the ./plugins/com.dotcms.config/ROOT directory in your 3.x instance.
  • If you changed the ROOT.xml file in 2.5.x, rename the file to context.xml.

For example, the following are paths to some of the most commonly changed configuration files in the new 3.x directory structure:


When you deploy your plugins (see below), any files in the ./plugins/com.dotcms.config/ROOT directory will be used to overwrite the files with the same names and paths in the ./dotserver/ directory.

For more information on the configuration plugin in dotCMS 3.x, please see the Changing dotCMS Configuration Properties and ROOT Folder in Plugins documentation.

12. Deploy your plugins

  • Change directory to the dotCMS 3.x root directory
  • Run the deploy-plugins script to deploy your plugins:
    • Linux/OS-X/Unix: ./bin/deploy-plugins.sh
    • Windows: bin\deploy-plugins.bat

For more information on plugins in dotCMS 3.x, please see the plugins documentation.

13. Start the dotCMS server

From the root of the dotCMS 3.x installation, run the dotCMS startup script:

  • Linux/OS-X/Unix: ./bin/startup.sh
  • Windows: bin\startup.bat

dotCMS will run through a number of startup data transformations that will convert your 2.5.x database to the 3.x schema.

14. Check your log files

Check your log files to ensure that your server has started properly.

If your server fails to start, or if you encounter any unexpected errors in the log files, please see Troubleshooting, below.

15. Reindex your database.

  • Login as you would normally.
  • Go to System -> Maintenance, select the Indexes tab, and click Reindex.


If the startup fails, or if you see errors in the log, please do the following:

  • Undeploy your plugins:
    • Linux/OS-X/Unix: ./bin/undeploy-plugins.sh
    • Windows: bin\undeploy-plugins.bat
  • Remove any plugins from the plugin directory other than the configuration plugin.
  • Repeat step 12 (to deploy ONLY your configuration plugin).


If you have any questions or comments on the upgrade process, please post to the dotCMS forum.