Upgrading dotCMS documentation for the dotCMS Content Management System

The dotCMS upgrade process provides fine-grained control over the upgrade steps and little downtime, and enables a quick rollback to the prior version if needed.

Preparation Steps

1. Important: Review the Change Log for the version that you are upgrading to

The change log contains specific information on both the changes that have been made in the new version and how this may affect your individual dotCMS installation. Importantly, the change log for the new version may suggest additional upgrade steps you need to take, based on your individual dotCMS configuration.

Note:

  • The changes are inclusive, so you should review all changes between the older version you are running and the newer version you are upgrading to.
  • Please also review the list of deprecated macros and features to determine if any features in your installation have been newly deprecated.

2. Download and extract the new version of dotCMS

The new version should be put into a folder alongside the existing and running version (so both the new and prior version dotCMS directories should now exist at the same level).

3. (Optional) If you are upgrading using a source installation:

(If you are are using a pre-built binary installation, you can skip this step).

Run ant deploy to build the application in the new version directory.

Copy Your Plugins

4. If your application configuration and customization has been deployed using static plugins (a strongly recommended practice):

  1. Copy each of the individual plugin folders under the old version's /plugins/ directory to the new version.
    • Important: Do not copy the entire plugins folder.
      • If you overwrite the common.xml file in the new version's /plugins/ directory, your plugins may not deploy properly.
    • Make sure the copy of each plugin folder is recursive (including all subdirectories), and overwrites the files from the new distribution.
  2. Copy the /plugins/plugins.xml file from the old version to the new version's /plugins/ directory.
    • Overwrite the plugins.xml file from the new version.
  3. Run bin/deploy-plugins.sh (bin\deploy-plugins.bat on Windows) in the new version directory to apply the configuration and customizations from the plugins.

5. If you have made any changes to the application files outside of the plugins system:

  • Edit each modified file in the new version and apply the same changes that you made in the old version's files.
  • Warning: Do not overwrite the files in the new version with your modified files from the old version.
    • The files in the new version may have necessary additions that do not exist in the old files, and overwriting them may prevent the new version from working properly.

6. If you are using any OSGi (dynamic) plugins:

  • Copy your OSGi plugins from the /dotserver/tomcat-X.x.xx/webapps/ROOT/WEB-INF/felix/load directory in your old version to the matching directory in the new version (dotserver\tomcat-X.x.xx\webapps\ROOT\WEB-INF\felix\load on Windows).
  • Alternately, the dynamic plugins can be re-installed using the backend web interface after the upgrade.

Backup Your Existing Site

Note: These steps outline the actions necessary to perform a full backup of your existing site. For more information on how to perform any of these steps, please see the Backup and Restore documentation.

7. Implement a content freeze

Alert dotCMS users that they must not edit any content until the upgrade window is complete or their changes may be lost.

8. Perform a full backup of the dotCMS database

9. (Mandatory) Back up the license files

Make backup copies of the license.dat and server_id.dat license files from the dotserver/tomcat-X.x.xx/webapps/ROOT/dotsecure/ directory (dotserver\tomcat-X.x.xx\webapps\ROOT\dotsecure on Windows).

A server can not be upgraded without these files on any dotCMS 3.x or higher version.

10. (Recommended) Perform a full backup of the assets directory

The assets directory for the old version is located in /dotserver/tomcat-X.x.xx/webapps/ROOT/assets (\dotserver\tomcat-X.x.xx\webapps\ROOT\assets on Windows).

  • The assets are very unlikely to be damaged by any problems with a minor version upgrade, as long as you remove or rename the starter.zip file.
    • So some clients skip this step as it can be fairly time-consuming depending on your infrastructure.
  • However there is no way to recover the assets if they are damaged during the upgrade.
    • So if you are risk-averse or do not have relatively current backups of your assets, you should perform this step.

11. (Recommended) Perform a full back of the Elasticsearch indexes directory

The Elasticsearch indexes directory for the old version is located in /dotserver/tomcat-X.x.xx/webapps/ROOT/dotsecure (\dotserver\tomcat-X.x.xx\webapps\ROOT\dotsecure on Windows).

Note:

  • This can be fairly time-consuming depending on your infrastructure.
  • The indexes are unlikely to be damaged by any problems with a minor version upgrade, so many clients skip this step.
    • However if you are risk-averse, you may wish to perform this step.

Switch to the New Version

12. Stop the old version of dotCMS

Run bin/shutdown.sh (bin\shutdown.bat on Windows) from the old version directory to stop dotCMS.

13. Give the new version access to the assets from your old version

Note:

  • If your assets are stored in the dotCMS application directory (they are by default), move or copy the assets from the old version to the new version.
    • The default location for your assets folder is /dotserver/tomcat-X.x.xx/webapps/ROOT/assets (dotserver\tomcat-X.x.xx\webapps\ROOT\assets on Windows) within the dotCMS distribution.
    • Move is typically much faster and does not duplicate the disk space.
  • If your assets are stored outside of the application directory, make sure that the ASSET_REAL_PATH configuration value is configured properly in the new version.
    • Note that if you implement configuration changes via ROOT folder plugins (which is the recommended practice), this will happen automatically when you copy your plugins folder to the new release (step 3, above).

14. Give the new version access to the ElasticSearch indexes from your old version

Note:

  • If your ElasticSearch indexes are stored in the dotCMS application directory (they are by default), move or copy them from the old version to the new version.
    • The default location for your elasticsearch index folder is /dotserver/tomcat-X.x.xx/webapps/ROOT/dotsecure/esdata (dotserver\tomcat-X.x.xx\webapps\ROOT\dotsecure\esdata on Windows) within the dotCMS distribution.
  • If your ElasticSearch indexes are stored outside of the application directory, make sure that the DYNAMIC_CONTENT_PATH, es.path.data, and es.path.work configuration values are configured properly in the new version.
    • Note that if you implement configuration changes via ROOT folder plugins (which is the recommended practice), this will happen automatically when you copy your plugins folder to the new release (step 3, above).

15. Copy the license files from your old version

Copy the license.dat and server_id.dat license files from the dotserver/tomcat-X.x.xx/webapps/ROOT/dotsecure/ directory (dotserver\tomcat-X.x.xx\webapps\ROOT\dotsecure on Windows) in your old version to the same folder in your new version.

16. (Recommended) Remove or rename the starter.zip file from the new version directory

The starter.zip file is located in the /dotserver/tomcat-X.x.xx/webapps/ROOT folder of your dotCMS installation tree (dotserver\tomcat-X.x.xx\webapps\ROOT on Windows). Removing this file ensures that your assets and database will not be overwritten if there are any errors in your configuration that prevent dotCMS from finding the assets or database from your old version.

Start the New Version

17. Start dotCMS on a single server

Run bin/startup.sh (bin\startup.bat on Windows) from the new version directory to start the dotCMS application.

Important: If you have a cluster configuration
  • You must start up a single server in the cluster first, before starting up any of the other cluster nodes.
  • Once you are able to login to the admin screen on the initial server, you can start up the remaining servers in the cluster, and they will automatically synchronize with the initial server to receive the upgraded content.

18. Monitor the log file for errors

The main dotCMS log file is located in /dotserver/tomcatX.x.xx/webapps/ROOT/dotsecure/logs/dotcms.log (\dotserver\tomcatX.x.xx\webapps\ROOT\dotsecure\logs\dotcms.log on Windows).

  • Server startup is complete once you see INFO ... startup.Catalina: Server startup in xxxxx ms in the log.
  • Any modifications needed to upgrade the database to the new version will be performed during this startup.
    • Once the database upgrade has been completed, the database will no longer work in the old version.
    • Therefore, if you need to roll back to the old version of your site after performing this step, you will need to restore the database from a prior backup.

Verify and Finalize the Upgrade

19. Test functionality

Test functionality on both the frontend and backend, to ensure everything works as intended.

20. Lift the content freeze

Allow dotCMS users to access the system backend to edit content again.

21. (Optional) Start a full reindex

  • This is a maintenance step that normally only needs to be done in case of content inconsistencies.
  • However it can be useful to perform this step following an upgrade to:
    1. Ensure that the index is 100% accurate.
    2. Make sure the reindex process runs reliably before a reindex is actually needed.
      • In rare circumstances, unexpected data can keep the reindex process from completing and it is good to identity and fix this proactively.
  • It is a common practice to use a symbolic link to point to the current running version of dotCMS.
  • If you use this kind of a link, update it once the new version has been successfully installed.
    • Ex: ln -s /opt/dotcms/dotCMS-X.x.x /opt/dotcms/current.
Please help us improve our documentation
Suggest changes or request new documentation